配置选项

在 Elastic APM 中标识此服务的名称。同一服务的多个实例应使用相同的名称。允许的字符：a-z、A-Z、0-9、-、_ 和空格。

如果没有提供 serviceName，代理将尝试使用 "package.json" 中的 "name" 字段（从当前工作目录向上查找）。该名称将被规范化为允许的字符。如果无法从 package.json 推断出名称，则使用 "unknown-nodejs-service" 的回退值。

服务节点的唯一名称。这是可选的，如果省略，APM 服务器将回退到 system.container.id（如果可用），最后回退到 host.name（如果需要）。

此选项允许您手动设置节点名称以确保唯一性和意义。

APM 服务器可选地期望的秘密令牌。

APM 服务器可选地期望的 API 密钥。这是 secretToken 的替代方案。

此 base64 编码字符串用于确保只有您的代理可以将数据发送到您的 APM 服务器。您必须使用 APM 服务器命令行工具创建 API 密钥。有关如何执行此操作的详细信息，请参阅 APM 服务器文档。

部署 APM 服务器的 URL。

默认情况下，代理将在使用 HTTPS 时验证 APM 服务器的 TLS/SSL 证书。您可以通过将此选项设置为 false 来关闭此行为。

默认情况下，代理将使用 Mozilla 收集的知名 CA 来验证 APM 服务器的 TLS/SSL 证书，如 Node.js 文档中 tls.createSecureContext() 所述。您可以将此选项设置为包含将用作替代的 CA 证书的文件的路径。

除非禁用服务器证书验证，否则在使用自签名证书时，必须指定此选项。

当前运行的应用程序的版本。这可能是您 package.json 文件中的版本、git 提交引用或任何其他可能帮助您查明特定版本或部署的字符串。

一个布尔值，指定代理是否应处于活动状态。如果处于活动状态，代理将检测传入的 HTTP 请求并跟踪错误。通常，您不希望在开发或测试环境中运行代理。如果您使用的是 NODE_ENV 环境变量，则可以使用它来确定状态

var options = {
  active: process.env.NODE_ENV === 'production'
}

环境名称会自动与所有错误和事务一起记录。如果您想覆盖它，请使用此选项。

环境允许您在 APM 应用程序中轻松地在全局级别过滤数据。在跨代理命名环境时保持一致性很重要。有关更多信息，请参阅 APM 应用程序中的 环境选择器。

如果设置为 true，代理将减少其工作量，以支持自动 HTTP 跟踪上下文 传播（用于分布式跟踪）和日志关联。代理不会与 APM 服务器通信（不会转发跟踪数据，不会检索中央配置），也不会收集指标。此设置允许将 APM 代理与无法使用 APM 服务器的服务一起使用。使用预计很少见。

如果设置为 true，代理将照常工作，只是它不会尝试与 APM 服务器通信。跟踪和指标数据将被丢弃，代理将无法接收中央配置，这意味着在这种状态下，任何其他配置都无法在不重新启动服务的情况下更改。

此设置在功能上类似于 contextPropagationOnly。但是，disableSend 不会尝试减少收集跟踪数据所花费的时间。此设置的一个用例是在 CI 环境中，以测试代理功能，而无需配置 APM 服务器。

一个布尔值，指定代理是否应在加载支持的模块时自动对其应用检测。

请注意，active 和 instrument 都需要为 true 才能运行检测。

一个布尔值，指定代理是否应检测传入的 HTTP 请求。

要配置是否应检测传出的 http 请求，请参阅 disableInstrumentations。

通过 Kibana 激活 APM 代理配置。如果设置为 true，客户端将定期轮询 APM 服务器以获取新的代理配置。

添加于：v3.37.0
"patch" 上下文管理器已在以下版本中移除：v4.0.0

此配置选项提供了一种方法来覆盖 APM 代理跟踪 Node.js 异步任务的默认技术；有时称为“运行上下文”、“异步上下文”或仅“上下文”。大多数用户不需要更改此设置。此设置替换了旧的 asyncHooks 配置选项。

为了有效地跟踪应用程序，APM 代理需要跟踪异步任务中的逻辑控制线程。首选机制是 AsyncLocalStorage，可在 Node.js 版本 >=14.5 和 >=12.19 中使用。在旧版本的 Node 中，APM 代理将回退到使用 async_hooks，这可能会导致更高的性能开销，尤其是在 Promise 密集型应用程序中。

支持的 contextManager 值为

用于限制对某些 URL 的请求被检测的数组或逗号分隔字符串。

当检测到传入的 HTTP 请求时，其 URL 路径名将针对此列表中的每个字符串进行测试。 transactionIgnoreUrls 属性支持精确字符串匹配、简单通配符 (*) 匹配，并且可能不包含逗号。通配符匹配默认情况下不区分大小写。您可以使用 (?-i) 前缀使通配符搜索区分大小写。

请注意，在忽略的 URL 的请求期间捕获的所有错误仍会发送到 APM 服务器，而与此设置无关。

如果您需要完整的正则表达式模式匹配，请参见 ignoreUrls。

示例用法

require('elastic-apm-node').start({
  transactionIgnoreUrls: [
    '/ping',
    '/fetch/*',
    '(?-i)/caseSensitiveSearch'
  ]
})

用于限制对某些 URL 的请求被检测。

此属性应设置为包含一个或多个字符串或 RegExp 对象的数组。当检测到传入的 HTTP 请求时，其 URL 将针对此列表中的每个元素进行测试。如果数组中的元素是 String，则将执行精确匹配。如果数组中的元素是 RegExp 对象，则其测试函数将使用正在测试的 URL 进行调用。

请注意，在忽略的 URL 的请求期间捕获的所有错误仍会发送到 APM 服务器，而与此设置无关。

如果您更喜欢简单的通配符模式匹配，请参见 transactionIgnoreUrls。

示例用法

require('elastic-apm-node').start({
  ignoreUrls: [
    '/ping',
    /^\/admin\//i
  ]
})

用于限制来自某些 User-Agent 的请求被检测。

此属性应设置为包含一个或多个字符串或 RegExp 对象的数组。当检测到传入的 HTTP 请求时，来自请求头的 User-Agent 将针对此列表中的每个元素进行测试。如果数组中的元素是 String，则它将与 User-Agent 的开头匹配。如果数组中的元素是 RegExp 对象，则其测试函数将使用正在测试的 User-Agent 字符串进行调用。

请注意，在被忽略的用户代理发出的请求期间捕获的所有错误仍会发送到 APM 服务器，而与此设置无关。

示例用法

require('elastic-apm-node').start({
  ignoreUserAgents: [
    'curl/',
    /pingdom/i
  ]
})

默认情况下，不会记录传入 HTTP 请求的 HTTP 主体，也不会将其发送到 APM 服务器。

可能的选项是：off、all、errors 和 transactions。

如果记录的主体大于 2 KiB，则会将其截断。

如果主体解析中间件将主体捕获为原始 Buffer 数据，则请求主体将表示为字符串 "<Buffer>"。

为了使代理能够访问主体，主体需要作为传入 HTTP request 对象上的属性提供。代理将在以下属性上查找主体：req.json || req.body || req.payload

默认情况下，会记录传入 HTTP 请求的 HTTP 标头及其生成的响应标头，并将它们发送到 APM 服务器。可以通过将此选项设置为 false 来禁用此功能。

一个布尔值，指定代理是否应该监控具有未结束 HTTP 请求的已中止 TCP 连接。如果发生这种情况，将生成错误并将其发送到 APM 服务器。

指定具有未结束 HTTP 请求的已中止 TCP 连接何时被视为错误的阈值。该值应以秒为单位，或应包含时间后缀。

如果 errorOnAbortedRequests 属性为 false，则会忽略此属性。

指定在决定是否跟踪请求时要使用的采样率。

这必须是 0.0 和 1.0 之间的值，其中 1.0 表示跟踪 100% 的请求。该值将四舍五入到小数点后四位精度（例如 0.0001、0.3333），以确保一致性和在 tracestate 标头中传播采样率时的大小合理，以进行 分布式跟踪。

操作系统主机名会自动与所有错误和事务一起记录。如果您想覆盖它，请使用此选项。

设置检测到的服务/应用程序使用的 Web 框架的名称。该名称将作为所有发送到 APM 服务器的错误和事务的元数据提供。这对于调试和过滤很有用。

默认情况下，如果可以自动检测到框架，代理将设置此配置选项的值。

设置检测到的服务/应用程序使用的 Web 框架的版本。该版本将作为所有发送到 APM 服务器的错误和事务的元数据提供。这对于调试和过滤很有用。

默认情况下，如果可以自动检测到框架，代理将设置此配置选项的值。

设置 frameworkName 和 frameworkVersion 的示例，用于名为 my-custom-framework 的框架

// read the version from the package.json file
var frameworkVersion = require('my-custom-framework/package').version

require('elastic-apm-node').start({
  frameworkName: 'my-custom-framework',
  frameworkVersion: frameworkVersion
})

设置代理日志的详细程度。请注意，这不会影响发送到 APM 服务器的错误类型。这只会控制代理在日志中的详细程度。可能的级别有：trace（最详细的日志记录，在生产环境中避免使用）、debug、info、warning、error、critical 和 off（禁用所有日志记录）。

此配置仅在使用内置日志记录器时适用。日志级别不会自动应用于自定义的 logger。

默认情况下，APM 代理以 ecs-logging 格式将日志记录到标准输出。使用 logger 配置传递自定义日志记录器对象。自定义日志记录器必须提供 trace、debug、info、warn、error 和 fatal 方法，这些方法接受字符串消息参数。

自定义日志记录器可能会导致结构化日志数据丢失。从 3.13 版本开始，代理使用 pino API 进行结构化日志记录。为了避免与不兼容的日志记录器 API 出现问题，提供的自定义日志记录器将以一种只传递日志消息的方式进行包装。作为特殊情况，如果提供的日志记录器是pino 日志记录器实例，那么它将直接使用，不会丢失结构化字段。设置环境变量 ELASTIC_APM_LOGGER=false 将忽略自定义日志记录器。这提供用于协助 调试模式 故障排除。

使用自定义 pino 日志记录器的示例

const pino = require('pino')
require('elastic-apm-node').start({
  logger: pino({ level: 'info' })
})

或使用 Bunyan 日志记录器

const bunyan = require('bunyan')
require('elastic-apm-node').start({
  logger: bunyan.createLogger({ level: 'info' })
})

要获取与 3.13 之前的代理版本类似的 非结构化日志输出，请使用以下方法

require('elastic-apm-node').start({
  logger: require('console-log-level')()
})

从 v4.0.0 开始，捕获的异常将始终打印到标准错误输出。

APM 代理是否应该监控未捕获的异常（uncaughtException）并将它们自动发送到 APM 服务器。这也包括未处理的拒绝（unhandledRejection），当节点进程使用 --unhandled-rejections=throw 启动时，这是从 v15 开始的 Node.js 默认行为（参考）。

当 captureExceptions 为 true 且发出 uncaughtException 事件时，APM 代理将：捕获错误详细信息，将该错误（以及缓冲的 APM 数据）发送到 APM 服务器，并 process.exit(1)（如 uncaughtException 处理程序应该那样）。需要注意一些事项

设置 captureExceptions: false 以禁用此功能，并获取未捕获异常的默认 Node.js 行为。

通常只有 Error 对象与它们关联的堆栈跟踪。当错误发送到 APM 服务器时，此堆栈跟踪与错误消息一起存储。堆栈跟踪指向 Error 对象实例化的位置。

但有时了解错误检测的位置，而不是错误实例化的位置，会很有价值。例如，当数据库驱动程序内部发生错误时，错误冒泡到的地方有时比错误发生的地方更便于调试。

将此配置选项设置为 always 以除了错误堆栈跟踪之外，还捕获 captureError 被调用的位置的堆栈跟踪。

默认情况下，此配置选项的值为 messages，这意味着只有在 captureError 被调用时，使用 字符串 或 特殊的参数化消息对象 时，才会记录捕获位置的堆栈跟踪，在这种情况下，正常的堆栈跟踪不可用。

将此配置选项设置为 never 以永远不记录捕获位置的堆栈跟踪。

捕获位置的堆栈跟踪永远不会为未捕获的异常生成。

添加于：v3.30.0，替换 captureSpanStackTraces 和 spanFramesMinDuration

使用此选项来控制是否从不为跨度捕获堆栈跟踪（默认值）、始终为跨度捕获堆栈跟踪，或者只为超过给定持续时间的跨度捕获堆栈跟踪。如果您选择启用跨度堆栈跟踪，即使只针对较慢的跨度，也请阅读 可能的性能影响。

持续时间值应为 '<integer><unit>' 形式的字符串。允许的单位是 ms（毫秒）、s（秒）和 m（分钟），区分大小写。<unit> 是可选的，默认为毫秒。也可以提供毫秒的数字值。例如，'10ms' 和 10 为 10 毫秒，'2s' 为 2 秒。

（注意：如果您正在从已弃用的 spanFramesMinDuration 选项迁移，则负值和零值的含义已更改，并且默认单位已从秒更改为毫秒。）

弃用于：v3.30.0，请使用 spanStackTraceMinDuration

此选项已弃用，请使用 spanStackTraceMinDuration 代替。在 v3.30.0 之前的版本中，此选项的默认值为 true。从 v3.30.0 版本开始，此默认值已实际上更改为 false，因为默认值为 spanStackTraceMinDuration: '-1s'。

如果指定了 spanStackTraceMinDuration，则会忽略为此选项提供的任何值。否则，

弃用于：v3.30.0，请使用 spanStackTraceMinDuration

此选项已弃用，请使用 spanStackTraceMinDuration 代替。请注意，负值和零值的含义在新选项中已切换。还要注意，默认单位已在新选项中从 s 更改为 ms。

如果指定了 spanStackTraceMinDuration，则会忽略为此选项提供的任何值。否则，

持续时间值应为以下格式的字符串：'<整数><单位>'。允许的单位为 ms（毫秒）、s（秒）和 m（分钟），区分大小写。<单位> 为可选，默认为秒。也可以提供以秒为单位的数字值。例如，'10ms' 为 10 毫秒，'5' 和 5（数字）为 5 秒。

将此选项设置为 true，以便在无法确定其他路由的情况下使用 URL 路径作为事务名称。如果代理不支持您的路由器，您可以将此选项设置为 true，以便使用特定的 URL 路径作为事务名称，而不是 GET unknown route。

当代理捕获错误时，其堆栈跟踪将存储在 Elasticsearch 中。

默认情况下，代理还会收集堆栈跟踪中每个帧所在行周围的几行源代码。这可以使您更轻松地确定错误的原因，因为与错误相关的源代码直接在 Kibana 中可见。

代理区分所谓的应用程序内帧和库帧。库帧是属于 Node 核心和应用程序 node_modules 文件夹内代码的帧。应用程序内帧是所有其他帧。

使用以下两个配置选项更改要为不同类型的堆栈帧包含的源代码行数

sourceLinesErrorAppFrames

默认值 5 表示将为应用程序内错误帧收集 5 行源代码。堆栈帧行上方 2 行 + 下方 2 行 + 堆栈帧行本身。

将此配置选项设置为 0 表示不会为应用程序内错误帧收集任何源代码。

sourceLinesErrorLibraryFrames

默认值 5 表示将为错误库帧收集 5 行源代码。堆栈帧行上方 2 行 + 下方 2 行 + 堆栈帧行本身。

将此配置选项设置为 0 表示不会为错误库帧收集任何源代码。

当代理记录跨度时，会记录一个堆栈跟踪，以及该跨度，指向启动该跨度的位置。此堆栈跟踪与其他跨度数据一起存储在 Elasticsearch 中。

默认情况下，代理还会收集堆栈跟踪中每个帧所在行周围的几行源代码。这可以使您更轻松地确定跨度启动的原因和方式，因为与跨度相关的源代码直接在 Kibana 中可见。

代理区分所谓的应用程序内帧和库帧。库帧是属于 Node 核心和应用程序 node_modules 文件夹内代码的帧。应用程序内帧是所有其他帧。

使用以下两个配置选项更改要为不同类型的堆栈帧包含的源代码行数

sourceLinesSpanAppFrames

默认值 0 表示不会为应用程序内跨度帧收集任何源代码。

sourceLinesSpanLibraryFrames

默认值 0 表示不会为跨度库帧收集任何源代码。

在以下版本中已弃用：v3.21.0，请使用 longFieldMaxLength

此选项已弃用，请使用 longFieldMaxLength 代替。

允许的错误消息的最大长度。它以字节表示，或者包含大小后缀，例如 2kb。大小后缀不区分大小写，包括 b、kb、mb 和 gb。超过此长度的消息将在发送到 APM 服务器之前被截断。请注意，虽然配置选项接受字节数，但截断是基于 unicode 字符数，而不是字节数。

设置为 -1 可禁用截断。

这适用于以下属性

以下事务、跨度和错误字段将在发送到 APM 服务器之前被截断为指定数量的 unicode 字符

请注意，跟踪数据在上游 APM 服务器中限制为 max_event_size，默认值为 300kB。如果您将 longFieldMaxLength 配置得过大，可能会导致 APM 服务器拒绝事务、跨度或错误。

将其设置为 0 将禁用堆栈跟踪收集。任何有限的整数值都将用作要收集的帧的最大数量。将其设置为 Infinity 表示将收集所有帧。

指定在丢弃更多跨度之前，在请求事务中捕获的跨度最大数量。设置为 -1 表示跨度永远不会被丢弃。

缓冲事件的最大大小。

当代理无法跟上将事务、跨度和错误发送到 APM 服务器或 APM 服务器关闭时，事务、跨度和错误等事件将被缓冲。如果队列已满，则会拒绝事件，这意味着您将丢失事务和跨度。这可以防止应用程序消耗过多内存，并在 APM 服务器在较长时间内不可用时可能崩溃。

较低的值将减少代理的堆开销，而较高的值将降低在吞吐量暂时激增时丢失事件的可能性。

代理维护一个与 APM 服务器的开放式 HTTP 请求，用于将收集的事务、跨度和错误传输到服务器。

为了避免与间歇性代理和负载均衡器出现问题，HTTP 请求将在由此配置选项控制的定期间隔内结束并创建新的请求。该值应以秒为单位，或者应包含时间后缀。

代理维护一个与 APM 服务器的开放式 HTTP 请求，用于将收集的事务、跨度和错误传输到服务器。

为了避免与间歇性代理和负载均衡器出现问题，如果 HTTP 请求的主体变得过大，则会结束 HTTP 请求并创建新的请求。该限制由此配置选项控制。该值应以字节为单位，或者包含大小后缀，例如 1mb。大小后缀不区分大小写，包括 b、kb、mb 和 gb。

指定 APM 代理与 APM Server 之间通信所用套接字的超时时间。如果在该时间段内套接字上没有发送或接收数据，则请求将被中止。不建议将 serverTimeout 设置为低于 apiRequestTime 配置选项的值。这很可能会导致健康的请求过早中止。

该值应包含时间后缀（m 表示分钟，s 表示秒，或 ms 表示毫秒），但如果未指定后缀，则默认为秒。

新增于：v4.3.0

指定 APM 代理向 APM Server 发送 HTTP 请求时要包含的自定义标头。通常情况下，正常使用不需要此配置。

示例

ELASTIC_APM_APM_CLIENT_HEADERS="foo=bar,spam=eggs"

require('elastic-apm-node').start({
  apmClientHeaders: { foo: 'bar', spam: 'eggs' },
  // ...
})

删除发送到 Elastic APM 的敏感数据。

sanitizeFieldNames 配置值允许您配置一个字段名称通配符模式列表，这些模式将从代理有效负载中删除。通配符匹配默认情况下不区分大小写。您可以使用 (?-i) 前缀使通配符搜索区分大小写。这些模式适用于请求和响应 HTTP 标头、HTTP 请求 Cookie，以及在 application/x-www-form-urlencoded 数据请求期间捕获的任何表单字段。

sanitizeFieldNames 将删除任何匹配的字段名称。如果您希望过滤或删除其他数据，API 过滤函数 可能是更好的选择。

要禁用其检测的模块名称的数组或逗号分隔字符串。当为模块禁用检测时，不会为该模块收集任何跨度。

使用选项对象的示例

require('elastic-apm-node').start({
  disableInstrumentations: ['graphql', 'redis']
})

使用环境变量的示例

ELASTIC_APM_DISABLE_INSTRUMENTATIONS=graphql,redis

有关可以禁用其检测的模块的最新列表，请参阅代理存储库中的 lib/instrumentation/modules 文件夹。请注意，并非此目录中表示的所有模块都会生成跨度，将这些模块添加到此数组中不会产生任何影响。

要配置是否应检测传入的 HTTP 请求，请参阅 instrumentIncomingHTTPRequests。

指定要与所有报告的事件关联的 Docker 容器 ID。如果不存在，它将从 /proc/self/cgroup 文件中解析出来。

指定要与所有报告的事件关联的 Kubernetes 节点名称。

指定要与所有报告的事件关联的 Kubernetes 命名空间。

指定要与所有报告的事件关联的 Kubernetes Pod 名称。如果不存在，并且如果 kubernetesPodUID 从 /proc/self/cgroup 文件中解析出来，则此值将默认为本地主机名。

指定要与所有报告的事件关联的 Kubernetes Pod UID。如果不存在，它将从 /proc/self/cgroup 文件中解析出来。

指定向 APM Server 报告指标的间隔。间隔应以秒为单位，或应包含时间后缀。

要禁用所有指标报告，包括细分指标，请将间隔设置为 "0s"。

指定在任何给定时间跟踪的指标的最大数量。当插入一个新的指标，该指标将超过限制时，将删除最旧的指标以腾出空间。

提供要应用于代理记录的任何数据的键值对标签对象。

示例

ELASTIC_APM_GLOBAL_LABELS="subspace=sap-hana,rack=number6"

Node.js 代理将在当前工作目录中查找名为 elastic-apm-node.js 的文件。您可以使用此配置选项指定自定义路径（此路径必须包含文件名），例如

ELASTIC_APM_CONFIG_FILE=/path/to/my-elastic-apm-node.js

配置文件应导出一个对象，遵循与 options 对象相同的约定，该对象作为第一个参数传递给 start 函数，例如

module.exports = {
  // 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: '',

  // Set custom APM Server URL (default: http://127.0.0.1:8200)
  serverUrl: ''
}

设置 breakdownMetrics: false 以禁用细分指标的报告。请注意，如果 metricsInterval: 0，则不会报告细分指标。

细分指标 (span.self_time.*) 记录每个唯一跨度类型中花费的自有时间。此数据驱动 APM 应用程序中的 跨度类型花费的时间 图表。

新增于：v3.45.0

disableMetrics 配置变量是一个通配符模式列表，用于指定不发送到 APM Server 的指标名称。该过滤器应用于 核心 APM 代理指标、由 apm.registerMetric(name[, labels], callback) 定义的自定义指标，以及 使用 OpenTelemetry Metrics API 定义的指标。

例如，设置 ELASTIC_APM_DISABLE_METRICS="nodejs.*,my_counter" 环境变量（或等效的 disableMetrics: ['nodejs.*', 'my_counter'] 选项，传递给 apm.start([options])）将导致报告的指标不包括任何名为 my_counter 的指标，也不包括任何以 nodejs. 开头的指标。通配符匹配默认情况下不区分大小写。您可以使用 (?-i) 前缀使通配符搜索区分大小写。

使用 metricsInterval: '0s' 完全禁用指标收集。请参阅 metricsInterval。

新增于：v3.45.0，作为实验性功能

定义 OpenTelemetry Metrics 直方图使用的默认桶边界。默认值为

[
  0.00390625, 0.00552427, 0.0078125, 0.0110485,
    0.015625,  0.0220971,   0.03125, 0.0441942,
      0.0625,  0.0883883,     0.125,  0.176777,
        0.25,   0.353553,       0.5,  0.707107,
           1,    1.41421,         2,   2.82843,
           4,    5.65685,         8,   11.3137,
          16,    22.6274,        32,   45.2548,
          64,    90.5097,       128,   181.019,
         256,    362.039,       512,   724.077,
        1024,    1448.15,      2048,   2896.31,
        4096,    5792.62,      8192,   11585.2,
       16384,    23170.5,     32768,     46341,
       65536,    92681.9,    131072
]

这与 OpenTelemetry 默认直方图边界 不同。要使用 OpenTelemetry 默认边界，请使用以下配置 APM 代理：

apm.start({
  customMetricsHistogramBoundaries: [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 ],
  // ...
})

或

export ELASTIC_APM_CUSTOM_METRICS_HISTOGRAM_BOUNDARIES=0,5,10,25,50,75,100,250,500,750,1000,2500,5000,7500,10000

要自定义特定直方图指标的边界，请使用 OpenTelemetry Metrics SDK View。有关示例，请参阅 此脚本。

有关使用 OpenTelemetry 与此 APM 代理的通用指南，请参阅 OpenTelemetry 桥接。

在启动期间，Node.js 代理会查询本地环境以确定应用程序是否在云环境中运行，并向代理提供有关该环境的详细信息。这些详细信息称为元数据，并将与其他已检测数据一起发送到 APM 服务器。 cloudProvider 配置值允许您控制此行为。

如果该值不是上述五个值之一，代理将使用 auto 的值。

告诉代理在检测消息系统时忽略某些队列/主题的通配符模式数组或逗号分隔字符串。

当已检测的消息系统发送或接收消息时，代理将针对此列表中的每个通配符测试队列/主题名称。如果名称匹配，代理将跳过检测操作。

ignoreMessageQueues 属性支持简单的通配符 (*) 模式，并且可能不包含逗号。通配符匹配默认情况下不区分大小写。您可以使用 (?-i) 前缀使通配符搜索区分大小写。

示例用法

require('elastic-apm-node').start({
  ignoreMessageQueues: [
    'overnight_jobs',
    'events_*',
    '(?-i)caseSensitiveSearch'
  ]
})

添加于: v3.34.0

此选项允许对 APM 代理如何处理传入请求上的 W3C trace-context 标头进行一些控制。默认情况下， traceparent 和 tracestate 标头用于分布式跟踪的 W3C 规范。但是，在某些情况下， 不 使用传入的 traceparent 标头可能会有所帮助。一些示例用例

有效值为

从 Elastic Observability 8.2 开始，跨度链接将在跟踪视图中可见。

将此选项设置为 false 将禁用 跨度压缩 功能。跨度压缩减少了收集、处理和存储开销，并从 UI 中清除了杂乱。权衡是，某些信息（例如所有压缩跨度的数据库语句）将不会被收集。

示例用法

require('elastic-apm-node').start({
  spanCompressionEnabled: true
})

连续的跨度，它们是完全匹配的，并且持续时间低于此阈值，将被压缩成单个复合跨度。此选项不适用于复合跨度。这减少了收集、处理和存储开销，并从 UI 中清除了杂乱。权衡是，所有压缩跨度的数据库语句将不会被收集。

支持持续时间后缀 ms（毫秒）、s（秒）和 m（分钟）。

示例用法

require('elastic-apm-node').start({
  spanCompressionExactMatchMaxDuration:'100ms'
})

连续的跨度到同一个目标，并且持续时间低于此阈值，将被压缩成单个复合跨度。此选项不适用于复合跨度。这减少了收集、处理和存储开销，并从 UI 中清除了杂乱。权衡是，所有压缩跨度的数据库语句将不会被收集。

示例用法

require('elastic-apm-node').start({
  spanCompressionSameKindMaxDuration:'0ms'
})

添加于: v3.34.0 作为实验性功能

将此选项设置为 true 将启用 OpenTelemetry 桥接。简而言之，OpenTelemetry 桥接允许您使用供应商中立的 OpenTelemetry 跟踪 API (@opentelemetry/api) 手动检测您的代码，并让 Elastic Node.js APM 代理处理这些 API 调用。

示例用法

require('elastic-apm-node').start({
  opentelemetryBridgeEnabled: true
})

设置退出跨度的最小持续时间。如果退出跨度的持续时间小于此阈值，代理将尝试丢弃跨度，而不是发送它。

在某些情况下，退出跨度不会被丢弃。将跟踪上下文传播到下游服务的跨度（例如传出的 HTTP 请求）不会被丢弃。但是，不传播上下文的外部调用（例如对数据库的调用）可以使用此阈值进行丢弃。

此外，导致错误的跨度不会被丢弃。

示例用法

require('elastic-apm-node').start({
  exitSpanMinDuration: '10ms'
})

APM 代理将捕获使用 @elastic/elasticsearch 模块（或旧版 elasticsearch 模块）对 Elasticsearch 发出的请求主体，这些请求主体的 URL 路径模式。默认设置会捕获对 Elasticsearch REST API 进行搜索的请求主体。

捕获的请求主体（如果有）存储在 span.db.statement 字段中。捕获的请求主体将被截断到由 longFieldMaxLength 定义的最大长度。

在 v4.0.0 中更改默认值，在 v3.x 中默认值为 true

为了启用分布式追踪，代理会将追踪上下文头添加到传出的请求（例如 HTTP 请求等）。这些头（traceparent 和 tracestate）在W3C 追踪上下文 规范中定义。

当此设置为 true 时，代理还会添加头 elastic-apm-traceparent，以向后兼容旧版本的 Elastic APM 代理。（在下一个主要版本的 APM 代理中，此设置将默认设置为 false。）