Agent API

启动 Node.js 的 Elastic APM 代理并返回自身。

有关可用选项，请参阅配置文档。

添加于：v1.5.0

使用 isStarted() 检查代理是否已启动。如果代理已启动，则返回 true，否则返回 false。

添加于：v3.11.0

获取配置的serviceName。如果未显式配置服务名称，则此值可能已自动确定。服务名称在 agent.start() 之前不会确定，因此在此之前将为 undefined。配置错误的代理可能具有 null 服务名称。

添加于：v4.2.0

获取配置的serviceVersion。如果未显式配置服务版本，则此值可能已自动确定。服务版本在 agent.start() 之前不会确定，因此在此之前将为 undefined。

添加于：v4.2.0

获取配置的environment。

添加于：v4.2.0

获取配置的serviceNodeName。如果 APM 代理未配置显式值，则返回 undefined。

添加于：v2.8.0

在代理启动后，设置或更改 frameworkName 或 frameworkVersion。这些配置选项也可以作为常规代理配置的一部分提供。

添加于：v0.1.0

使用 addFilter() 提供一个过滤器函数。

每个过滤器函数将在数据发送到 APM 服务器之前被调用。这将允许您操作发送的数据，例如删除敏感信息（如密码等）。（注意：通过 addFilter 添加的过滤器不会应用于发送到 APM 服务器的“metadata”对象 — 请改用 addMetadataFilter。）

每个过滤器函数将按照添加的顺序被调用，并将接收一个 payload 对象作为唯一参数，其中包含即将发送到 APM 服务器的数据。

有效负载的格式取决于发送的事件类型。有关不同格式的详细信息，请参阅事件接收 API 文档。

过滤器函数是同步的，应返回已操作的有效负载对象。如果过滤器函数不返回任何值或返回一个假值，则不会调用其余的过滤器函数，并且有效负载不会发送到 APM 服务器。

用法示例

apm.addFilter(function redactSecretHeader(payload) {
  if (payload.context &&
      payload.context.request &&
      payload.context.request.headers &&
      payload.context.request.headers['x-secret']) {
    // redact sensitive data
    payload.context.request.headers['x-secret'] = '[REDACTED]'
  }

  // remember to return the modified payload
  return payload
})

虽然您还可以使用过滤器函数向 user 和 custom 属性添加新的上下文信息，但建议您为此目的使用 apm.setUserContext() 和 apm.setCustomContext()。

添加于：v2.0.0

与 apm.addFilter() 类似，但 fn 仅会使用错误有效负载调用。

添加于：v2.0.0

与 apm.addFilter() 类似，但 fn 仅会使用事务有效负载调用。

添加于：v2.0.0

与 apm.addFilter() 类似，但 fn 仅会使用跨度有效负载调用。

添加于：v3.14.0

使用 addMetadataFilter(fn) 为发送到 APM 服务器的元数据对象提供一个过滤器函数。这将允许您操作发送的数据，例如删除可能敏感的信息。

每个过滤器函数将按照添加的顺序被调用，并将接收一个 metadata 对象作为唯一参数。过滤器函数是同步的，必须返回已操作的对象。用法示例

apm.addMetadataFilter(function dropArgv(metadata) {
  if (metadata.process && metadata.process.argv) {
    delete metadata.process.argv
  }
  return metadata
})

警告：作者有责任确保返回的对象符合 元数据模式，否则所有 APM 数据注入都会失败。破坏元数据的元数据过滤器将导致代理记录错误，如下所示

ERROR (elastic-apm-node): APM Server transport error (400): Unexpected APM Server response
APM Server accepted 0 events in the last request
Error: validation error: 'metadata' required
  Document: {"metadata":null}

添加于：v0.1.0

调用此函数以使用有关用户/客户端的信息来丰富收集的性能数据和错误。此函数可以在请求/响应生命周期的任何时间点（即在事务活动期间）调用。

给定的 context 将被添加到活动事务中。如果找不到活动事务，则返回 false。否则返回 true。

可以在同一活动事务的范围内多次调用此函数。对于每次调用，context 参数的属性都将与先前给定的上下文进行浅合并。

如果捕获到错误，则会使用活动事务的上下文作为捕获错误的上下文，并且作为 apm.captureError 的第二个参数提供的任何自定义上下文都将优先，并浅合并到顶部。

提供的用户上下文会存储在 Elasticsearch 中错误和事务的 context.user 下。

添加于：v0.1.0

调用此方法可以使用任何您认为有助于调试性能问题或错误的信息来丰富收集到的错误和事务。可以在事务活动期间的任何时刻调用此函数（例如，在传入 HTTP 请求的请求/响应生命周期中）。

提供的自定义上下文在 APM Server 7.0 之前的版本中存储在 context.custom 下，在 APM Server 7.0+ 版本中存储在 transaction.custom 和 error.custom 下。

给定的 context 将被添加到活动事务中。如果找不到活动事务，则返回 false。否则返回 true。

可以在同一活动事务的范围内多次调用此函数。对于每次调用，context 参数的属性都将与先前给定的上下文进行浅合并。

如果捕获到错误，则会使用活动事务的上下文作为捕获错误的上下文，并且作为 apm.captureError 的第二个参数提供的任何自定义上下文都将优先，并浅合并到顶部。

添加于：v0.1.0
从 apm.setTag() 重命名为 apm.setLabel()：v2.10.0
在 v3.11.0 中添加了 stringify 参数

apm.setLabel('productId', 42, false);

在当前事务上设置标签。您可以在同一事务上设置多个标签。如果在当前事务期间发生错误，它也会被标记上相同的标签。

添加于：v1.5.0
从 apm.addTags() 重命名为 apm.addLabels()：v2.10.0
在 v3.11.0 中添加了 stringify 参数

apm.addLabels({productId: 42, productName: 'butter'}, false);

在当前事务上添加多个标签。您可以多次添加标签。如果在当前事务期间发生错误，它也会被标记上相同的标签。

添加于：v3.47.0

扩展 globalLabels 配置。它允许设置应用于所有事务的标签。一个可能的用例是使用应用程序的状态指定标签：'initializing' | 'available' | 'unhealthy'。

添加于：v0.1.0

将错误发送到 APM Server

apm.captureError(new Error('boom!'))

apm.captureError('Something happened!')

apm.captureError({
  message: 'Could not find user %s with id %d in the database',
  params: ['Peter', 42]
})

// Sending some extra details about the user
apm.captureError(error, {
  user: {
    id: 'unique_id',
    username: 'foo',
    email: '[email protected]'
  }
})

// Sending some arbitrary details using the `custom` field
apm.captureError(error, {
  custom: {
    some_important_metric: 'foobar'
  }
})

apm.captureError(err, {
  request: req // an instance of http.IncomingMessage
})

apm.captureError(err, {
  response: res // an instance of http.ServerResponse
})

添加于：v0.1.0

返回一个中间件函数，用于收集错误并将错误发送到 APM 服务器。

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

const app = connect()

// your regular middleware:
app.use(...)
app.use(...)

// your main HTTP router
app.use(function (req, res, next) {
  throw new Error('Broke!')
})

// add Elastic APM in the bottom of the middleware stack
app.use(apm.middleware.connect())

app.listen(3000)

添加于：v0.1.0
事务 subtype 和 action 在 v3.25.0 中已弃用
事务 subtype 和 action 在 v4.0.0 中已删除

启动新的自定义/手动事务。有关如何使用自定义事务的详细信息，请参阅事务 API 文档。

请注意，APM 代理会自动为传入的 HTTP 请求启动事务。您只需使用此函数创建自定义事务，例如，对于定期后台例程。有一个名为 request 的特殊 type，代理在检测到传入 HTTP 请求时自动创建的事务将使用该类型。

如果 APM 代理尚未启动，则将返回一个无操作的“no-op”事务对象。

添加于：v0.1.0

结束活动事务。如果当前没有活动事务，则不执行任何操作。

请注意，对于所有常规 HTTP 事务，代理将自动为您执行此操作。您只需使用此函数结束由 apm.startTransaction() 创建的自定义事务，或者如果您希望提前结束常规事务。

或者，您可以直接在活动事务对象上调用 end()。

添加于：v1.9.0

如果在事务的上下文中，则获取当前活动的事务。

添加于：v2.0.0

如果在 Span 的上下文中，则获取当前活动的 Span。

添加于：v2.9.0

获取当前事务或 Span 的序列化 traceparent 字符串。

添加于：v0.1.0

如果您使用受支持的路由器/框架，则代理会自动为您设置事务名称。

如果您未使用 Express、hapi、koa-router、Restify 或 Fastify，或者如果代理由于某种原因无法检测到 HTTP 路由的名称，则事务名称将默认为 METHOD unknown route（例如 POST unknown route）。

在 自定义 Node.js 堆栈入门 文章中阅读有关手动命名路由的更多信息。

添加于：v1.1.0

启动并返回与当前活动事务关联的新自定义 Span。这与使用 apm.currentTransaction 获取当前事务，以及如果找到事务，则在其上调用 transaction.startSpan(name, type, options) 相同。

当 Span 启动时，它将测量时间，直到调用 span.end() 为止。

有关如何使用自定义 Span 的详细信息，请参阅Span API 文档。

添加于：v0.1.0

默认情况下，当检测到未捕获的异常时，代理将终止 Node.js 进程。如果您需要在进程终止之前运行任何自定义代码，请使用此函数。

apm.handleUncaughtExceptions(function (err) {
  // Do your own stuff... and then exit:
  process.exit(1)
})

在事件已发送到 APM 服务器 之后，使用以下参数调用回调

如果使用 captureExceptions 配置选项禁用了未捕获的异常处理程序，此函数也会启用该处理程序。

如果您不指定回调，则在捕获未捕获的异常并将其发送到 APM 服务器后，节点进程将自动终止。

建议您不要在收到未捕获的异常后保持进程运行，因此如果您使用可选的回调，请记住终止节点进程。

添加于：v0.12.0

// with node-style callback
apm.flush(function (err) {
  // Flush complete
})

// with promises
apm.flush().then(function () {
  // Flush complete
}).catch(function (err) {
  // Flush returned an error
})

// inside of an async function
try {
  await apm.flush()
  // Flush complete
} catch (err) {
  // Flush returned an error
}

手动结束与 APM 服务器的活动传出 HTTP 请求。否则，HTTP 请求会按照 apiRequestTime 和 apiRequestSize 配置选项控制的固定间隔自动结束。

如果将可选的 callback 作为此方法的第一个参数提供，则完成时会调用 callback(flushErr)。如果未提供 callback，则会返回一个 Promise，该 Promise 将解析为 void 或拒绝为 flushErr。

在活动 HTTP 请求结束后，将调用回调（如果未提供 callback 参数，则 Promise 将解析）。即使当前没有活动的 HTTP 请求，也会调用回调。

新增于: v1.4.0

exports.hello = apm.lambda(function (event, context, callback) {
  callback(null, `Hello, ${payload.name}!`)
})

手动检测 AWS Lambda 函数，以便围绕每次执行形成一个事务。可以选择提供类型以将 lambda 分组在一起。默认情况下，“lambda”将用作类型名称。

请阅读 Lambda 文章，了解更多关于 lambda 支持的信息。

新增于: v2.7.0

注册一个在拦截的 require 调用上应用的模块补丁。

一个模块可以有任意数量的补丁，并且将按照添加的顺序应用。

apm.addPatch('timers', (exports, agent, { version, enabled }) => {
  const setTimeout = exports.setTimeout
  exports.setTimeout = (fn, ms) => {
    const span = agent.startSpan('set-timeout')
    return setTimeout(() => {
      span.end()
      fn()
    }, ms)
  }

  return exports
})

// or ...

apm.addPatch('timers', './timer-patch')

此方法和其他与“Patch”相关的 API 方法应在启动 APM 代理之前调用。在代理启动且相关模块已被 `require` 后进行的更改可能会产生意想不到的缓存行为。

新增于: v2.7.0

删除模块补丁。通常只有在替换现有补丁时才需要这样做。要在保持上下文传播支持的同时禁用检测，请参阅 disableInstrumentations。

apm.removePatch('timers', './timers-patch')

// or ...

apm.removePatch(['timers'], './timers-patch')

// or ...

apm.removePatch('timers', timerPatchFunction)

新增于: v2.7.0

清除给定模块的所有补丁。通常只有在替换现有补丁时才需要这样做。要在保持上下文传播支持的同时禁用检测，请参阅 disableInstrumentations。

apm.clearPatches('timers')

// or ...

apm.clearPatches(['timers'])

新增于: v2.17.0

apm.currentTraceIds 生成一个包含 trace.id 以及当存在当前事务或 span 时包含 transaction.id 或 span.id 的对象。当没有可用的事务或 span 时，它将返回一个空对象。这使得可以将 日志关联到带有结构化日志记录器的 APM 跟踪。

{
  "trace.id": "abc123",
  "transaction.id": "abc123"
}
// or ...
{
  "trace.id": "abc123",
  "span.id": "abc123"
}

注册一个指标回调。

请注意不要使用内置指标的名称。

apm.registerMetric( 'ws.connections' , () => {
  return wss.clients.size;
})

// or, to additionally label the metric with "module: 'ws'":

apm.registerMetric( 'ws.connections' , {module : 'ws'}, () => {
  return wss.clients.size;
})

新增于: v3.12.0

将在当前事务上设置 outcome 属性。

有关更多信息，请参阅 事务 Outcome 文档。

新增于: v3.12.0

将在当前 span 上设置 outcome 属性。

有关更多信息，请参阅 Span Outcome 文档。