« TypeScript 入门 启动 Agent »
Elastic 文档 › ›设置 Agent

使用自定义 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

初始化

编辑

在您的 Node.js 应用程序中引入任何其他模块之前（即在http和您的路由器之前），务必先启动 Agent。

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

以下是如何通常引入和启动 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: '',
})

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

高级配置
编辑

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

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

然后只需启动 Agent，如下所示：

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

请参阅API 文档中配置 Agent 的所有可能方法。

完整文档
编辑

性能监控

编辑

Elastic APM 会自动测量自定义 Node.js 应用程序的性能。它会为数据库查询、外部 HTTP 请求以及在对自定义 Node.js 应用的请求期间发生的其它缓慢操作记录跨度。

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

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

路由命名
编辑

Node.js Agent 会跟踪对应用程序的传入 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 中查看应用程序的性能指标时，您可能会看到一些名为“未知路由”的事务。这表示 Agent 检测到对应用程序的传入 HTTP 请求，但不知道该 HTTP 请求与自定义 Node.js 应用中的哪个路由匹配。

这可能只是 404 请求（根据定义，这些请求与任何路由都不匹配），也可能是 Agent 安装不正确的一个症状。如果您看到这种情况或无法显示任何有意义的指标，请按照故障排除指南操作。

错误日志记录

编辑

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

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

apm.captureError(err)

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

中间件错误处理程序
编辑

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

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

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 Agent 将在将错误和指标发送到 Elastic APM 服务器之前过滤常见的敏感信息。

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

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

添加您自己的数据

编辑

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

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

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

兼容性

编辑

详情请参见支持的技术。

故障排除

编辑

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

« TypeScript 入门 启动 Agent »