Koa 入门指南

为你的 Koa 应用设置 Elastic APM 非常简单，你可以通过多种方式进行调整以满足你的需求。请按照以下指南开始使用，有关更多高级主题，请查看 API 参考。

Koa 没有内置路由，由于我们需要依赖路由信息来实现全面支持，因此无法直接支持 Koa。我们目前支持最流行的 Koa 路由库 koa-router。

如果你的 Koa 应用使用了其他路由，请提交 Issue，以便我们确保支持你的技术栈。同时，你可以配置 Elastic APM 以配合任何技术栈使用。

安装

将 elastic-apm-node 模块作为依赖项添加到您的应用程序中

npm install elastic-apm-node --save

初始化

务必在 Node.js 应用中引入任何其他模块之前启动探针——即在 koa、http 等模块之前。

这意味着您应该在应用程序的主文件（通常是 index.js、server.js 或 app.js）中引入并启动代理。

以下是一个安装了 Elastic APM 探针的简单 Koa 示例

		// Add this to the VERY top of the first file loaded in your app
const apm = require('elastic-apm-node').start({
  // Override service name from package.json
  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
  serviceName: '',

  // Use if APM Server requires a token
  secretToken: '',

  // Use if APM Server uses API keys for authentication
  apiKey: '',

  // Set custom APM Server URL (default: http://127.0.0.1:8200)
  serverUrl: '',
})

const app = require('koa')()
const router = require('koa-router')()

router.get('/', function *(next) {
  this.body = 'Hello World'
})

app
  .use(router.routes())
  .use(router.allowedMethods())

app.listen(3000)
		
	

探针现在将监控你的 Koa 应用的性能并记录任何未捕获的异常。

高级配置

在上面的示例中，我们通过调用 start() 函数来初始化代理。此函数接受一个可选的配置对象用于配置代理。任何未通过选项对象提供的选项都可以改用环境变量进行配置。因此，如果您愿意，可以使用环境变量来设置相同的配置选项

		ELASTIC_APM_SERVICE_NAME=<service name>
ELASTIC_APM_SECRET_TOKEN=<token>
ELASTIC_APM_SERVER_URL=<server url>
		
	

然后像这样直接启动代理

		// Start the agent before any thing else in your app
var apm = require('elastic-apm-node').start()

在 API 文档中查看配置代理的所有可能方法。

完整文档

性能监控

Elastic APM 会自动测量你的 Koa 应用的性能。它会记录数据库查询、外部 HTTP 请求以及在 Koa 应用请求期间发生的其他缓慢操作的 span。

默认情况下，代理将对最常见的模块进行插桩。要对其他事件进行插桩，您可以使用自定义跨度。有关自定义跨度的信息，请参阅自定义跨度部分。

跨度按事务分组 —— 默认情况下，每个传入的 HTTP 请求对应一个事务。但也可以创建不与 HTTP 请求关联的自定义事务。有关详细信息，请参阅自定义事务部分。

未知路由

在 Elastic APM 中查看应用的性能指标时，你可能会看到一些名为 "unknown route" 的事务。这表明探针检测到了到达你应用的传入 HTTP 请求，但不知道该 HTTP 请求匹配了 Koa 应用中的哪个路由。

这可能只是 404 请求（按定义它们不匹配任何路由），或者可能暗示代理未正确安装。如果您看到此情况或无法显示任何有意义的指标，请遵循故障排除指南。

错误日志记录

默认情况下，Node.js 代理将监视未捕获的异常并自动将其发送到 Elastic APM。但在大多数情况下，错误不会被抛出，而是通过回调返回、被 Promise 捕获或单纯手动创建。这些错误不会自动发送到 Elastic APM。要手动将错误发送到 Elastic APM，只需将错误传入并调用 apm.captureError() 即可

		var err = new Error('Ups, something broke!')

apm.captureError(err)

有关错误的高级日志记录（包括向错误添加额外的元数据），请参阅 API 文档。

过滤敏感信息

默认情况下，Node.js 代理将在将错误和指标发送到 Elastic APM 服务器之前过滤常见的敏感信息。

您可以调整这些默认设置或删除任何您不想发送到 Elastic APM 的信息

默认情况下，Node.js 代理不会记录 HTTP 请求的正文。要启用此功能，请使用 captureBody 配置选项
默认情况下，Node.js 代理将过滤已知包含敏感信息的某些 HTTP 标头。要禁用此功能，请使用 sanitizeFieldNames 配置选项
要应用自定义过滤器，请使用其中一个过滤函数

添加您自己的数据

Node.js 代理将跟踪活动的 HTTP 请求，并在将它们发送到 Elastic APM 服务器时将它们链接到错误和记录的事务指标。这使您可以查看有关哪个请求导致了特定错误或哪个请求导致某个 HTTP 端点变慢的详细信息。

但在许多情况下，关于 HTTP 请求本身的信息是不够的。要向错误和事务添加更多元数据，请使用以下函数之一

apm.setUserContext() - 调用此函数可使用有关用户/客户端的信息来丰富收集到的性能数据和错误
apm.setCustomContext() - 调用此函数可使用您认为有助于调试性能问题和错误的任何信息来丰富收集到的性能数据和错误（此数据仅存储，而不在 Elasticsearch 中进行索引）
apm.setLabel() - 调用此函数可使用您认为有助于调试性能问题和错误的简单的键/值字符串来丰富收集到的性能数据和错误（标签在 Elasticsearch 中进行索引）

兼容性

有关详细信息，请参阅 支持的技术。

故障排除

如果您无法让 Node.js 代理按预期工作，请遵循故障排除指南。