« 使用 TypeScript 入门 启动代理 »
Elastic 文档 › ›设置代理

使用自定义 Node.js 栈入门

编辑

使用自定义 Node.js 栈入门编辑

为您的自定义 Node.js 应用程序设置 Elastic APM 很容易，并且您可以通过多种方式对其进行调整以满足您的需求。请按照以下指南开始，有关更高级的主题，请查看 API 参考。

如果您使用的是 Express、hapi、Koa、Restify、Fastify 或 AWS Lambda，我们建议您阅读以下文章

安装编辑

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

npm install elastic-apm-node --save

初始化编辑

在您要求 任何 其他模块（例如，在 http 之前以及在您的路由器之前）之前启动代理非常重要。

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

以下是如何通常要求和启动 Elastic APM 的简单示例

// Add this to the VERY top of the first file loaded in your app
var 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: '',
})

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

高级配置编辑

在上面的示例中，我们通过调用 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 会自动测量自定义 Node.js 应用程序的性能。它会记录数据库查询、外部 HTTP 请求和其他在对自定义 Node.js 应用程序的请求期间发生的缓慢操作的跨度。

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

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

路由命名编辑

Node.js 代理跟踪传入的 HTTP 请求到您的应用程序，这些请求被称为“事务”。所有具有相同名称的事务会自动分组在一起。

在正常的 Web 应用程序中，您希望根据与传入 HTTP 请求匹配的路由来命名事务。因此，假设您有一个路由用于显示由 GET /posts/{id} 标识的博客上的帖子。您希望请求 GET /posts/12、GET /posts/42 等在名为 GET /posts/{id} 的事务下分组在一起。

如果您使用的是 Express、hapi、koa-router、Restify 或 Fastify，此命名将根据您的路由名称自动进行。如果您使用其他框架或自定义路由器，您会发现事务只是在名为“未知路由”的几个大块中分组在一起。在这种情况下，您需要通过为每个事务提供名称来帮助我们。您可以通过在请求期间的任何时间调用 apm.setTransactionName() 来实现，并将事务的名称作为第一个参数。

使用 patterns 模块进行路由处理的应用程序摘录

var apm = require('elastic-apm-node').start()
var http = require('http')
var patterns = require('patterns')()

// Setup routes and their respective route handlers
patterns.add('GET /', require('./routes/index'))
patterns.add('GET /posts', require('./routes/posts').index)
patterns.add('GET /posts/{id}', require('./routes/posts').show)

http.createServer(function (req, res) {
  // Check if we have a route matching the incoming request
  var match = patterns.match(req.method + ' ' + req.url);

  // If no match is found, respond with a 404. Elastic APM will in
  // this case use the default transaction name "unknown route"
  if (!match) {
    res.writeHead(404)
    res.end()
    return
  }

  // The patterns module exposes the pattern used to match the
  // request on the `pattern` property, e.g. `GET /posts/{id}`
  apm.setTransactionName(match.pattern)

  // Populate the params and call the matching route handler
  var fn = match.value
  req.params = match.params
  fn(req, res)
}).listen(3000)
未知路由编辑

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

这可能仅仅是 404 请求（根据定义，它们不匹配任何路由），或者可能是代理未正确安装的症状。如果您看到这种情况或无法显示任何有意义的指标，请按照 故障排除指南 进行操作。

错误日志记录编辑

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

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

apm.captureError(err)

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

中间件错误处理程序编辑

如果您使用的是 connect 模块，并且错误是在其中一个中间件函数中同步抛出，或者作为第一个参数传递给中间件 next() 函数，它将被传递给 Connect 错误处理程序。

建议您将代理注册为 Connect 错误处理程序。如果您有多个 Connect 错误处理程序，代理错误处理程序应该是链中的第一个，以确保它能正确接收错误。

var apm = require('elastic-apm-node').start()
var connect = require('connect')

var app = connect()

// Your regular middleware and router...
app.use(...)
app.use(...)
app.use(...)

// Add the Elastic APM middleware after your regular middleware
app.use(apm.middleware.connect())

// ...but before any other error handler
app.use(function (err, req, res, next) {
  // Custom error handling goes here
})

过滤敏感信息编辑

默认情况下，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 代理按预期工作，请遵循 故障排除指南。

« 使用 TypeScript 入门 启动代理 »