Express 入门

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

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

npm install elastic-apm-node --save

在您需要 Node.js 应用程序中的任何其他模块（即在 express、http 等之前）之前启动代理非常重要。

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

这是一个安装了 Elastic APM 代理的简单 Express 示例

// 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('express')()

app.get('/', function (req, res) {
  res.send('Hello World!')
})

app.listen(3000)

代理现在将监控您的 Express 应用程序的性能并记录任何未捕获的异常。

在上面的示例中，我们通过调用 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 自动测量 Express 应用程序的性能。它会为数据库查询、外部 HTTP 请求以及在向您的 Express 应用程序发出请求期间发生的任何其他缓慢操作记录跨度。

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

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

在 Elastic APM 中查看应用程序的性能指标时，您可能会看到一些名为“未知路由”的事务。这表示代理检测到对应用程序的传入 HTTP 请求，但不知道 Express 应用程序中的哪个路由与 HTTP 请求匹配。

这可能仅仅是 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 代理正常工作，请按照 故障排除指南 进行操作。