Koa 入门

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

Koa 没有内置路由器，因此我们无法直接支持 Koa，因为我们依赖路由器信息来提供全面支持。我们目前支持最流行的 Koa 路由器，称为koa-router。

如果您在 Koa 应用程序中使用其他路由器，请提出问题，以便我们确保支持您的堆栈。同时，您可以配置 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 应用程序发出请求期间发生的其它缓慢操作的跨度。

默认情况下，代理将检测最常见的模块。要检测其它事件，可以使用自定义跨度。有关自定义跨度的信息，请参阅“自定义跨度”部分。

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

未知路由编辑

在 Elastic APM 中查看应用程序的性能指标时，您可能会看到一些名为“未知路由”的事务。这表明代理检测到传入应用程序的 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 请求，并在将错误和记录的事务指标发送到 Elastic APM 服务器时将其链接到它们。这使您可以查看有关哪个请求导致特定错误或哪些请求导致某个 HTTP 端点速度慢的详细信息。

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

兼容性编辑

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

故障排除编辑

如果无法使 Node.js 代理按预期工作，请按照故障排除指南进行操作。