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 请求，但不知道该 HTTP 请求与您的 Express 应用程序中的哪个路由匹配。

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