配置选项

在 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 调用其 test 函数。

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

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

用法示例

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

用于限制对来自某些用户代理的请求进行检测。

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

请注意，在此设置中，在请求被忽略的用户代理期间捕获的所有错误仍会发送到 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 服务器的所有错误和事务的元数据。这对于调试和筛选很有用。

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

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

// 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 格式记录到 stdout。使用 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 版本开始，捕获的异常将始终打印到 stderr。

APM 代理是否应监视未捕获的异常（uncaughtException）并将其自动发送到 APM 服务器。这还包括未处理的拒绝（unhandledRejection），当 node 进程以 --unhandled-rejections=throw 启动时，这是自 v15 以来的默认 Node.js 行为 (参考)。

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

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

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

但有时了解 Error 在哪里被检测到而不是在哪里被实例化很有价值。例如，当错误发生在数据库驱动程序的深处时，错误冒泡到的位置有时比错误发生的位置更有助于调试。

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

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

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

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

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

使用此选项来控制是否永远不捕获 span 的堆栈跟踪（默认设置）、始终捕获 span 的堆栈跟踪，或者仅捕获持续时间长于给定持续时间的 span 的堆栈跟踪。如果您选择启用 span 堆栈跟踪，即使仅针对较慢的 span，请阅读可能的性能影响。

持续时间值应为 '<整数><单位>' 形式的字符串。允许的单位是 ms（毫秒）、s（秒）和 m（分钟），并且区分大小写。<单位> 是可选的，默认为毫秒。也可以提供毫秒的 Number 值。例如，'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（分钟），并且区分大小写。<单位> 是可选的，默认为秒。也可以提供秒的 Number 值。例如，'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 表示不会为错误库帧收集任何源代码。

当代理记录 span 时，会同时记录一个堆栈跟踪，指向 span 发起的位置。此堆栈跟踪与其他的 span 数据一起存储在 Elasticsearch 中。

默认情况下，代理还会收集堆栈跟踪中每一帧的行周围的一些源代码。这可以更容易地确定 span 发起的原因和方式，因为与 span 相关的源代码直接在 Kibana 中可见。

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

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

sourceLinesSpanAppFrames

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

sourceLinesSpanLibraryFrames

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

已弃用版本：v3.21.0，请使用 longFieldMaxLength

此选项已弃用，请改用 longFieldMaxLength。

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

设置为 -1 可禁用截断。

这适用于以下属性

以下事务、span 和错误字段将在发送到 APM 服务器之前在此 Unicode 字符数处截断

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

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

指定在请求事务中捕获的最大 span 数，超出此限制将丢弃后续的 span。设置为 -1 表示永远不会丢弃 span。

缓冲事件的最大大小。

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

较低的值会减少代理的堆开销，而较高的值会在吞吐量临时激增的情况下减少丢失事件的可能性。

代理维护与 APM Server 的开放 HTTP 请求，该请求用于将收集到的事务、span 和错误传输到服务器。

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

代理维护与 APM Server 的开放 HTTP 请求，该请求用于将收集到的事务、span 和错误传输到服务器。

为了避免与间歇性代理和负载均衡器出现问题，如果 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 过滤函数可能是更好的选择。

要禁用检测的模块名称的数组或逗号分隔字符串。当禁用模块的检测时，将不会收集该模块的 span。

使用选项对象的示例

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

使用环境变量的示例

ELASTIC_APM_DISABLE_INSTRUMENTATIONS=graphql,redis

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

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

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

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

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

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

指定要与所有报告的事件关联的 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

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

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.*) 记录在每种唯一类型的 span 中花费的自时间。此数据驱动 APM 应用程序中的 按 span 类型花费的时间图表。

添加于：v3.45.0

disableMetrics 配置变量是要不发送到 APM 服务器的指标名称的通配符模式列表。该过滤器应用于 核心 APM 代理指标、由 apm.registerMetric(name[, labels], callback) 定义的自定义指标，以及 使用 OpenTelemetry 指标 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 指标直方图的默认存储桶边界。默认情况下，该值为

[
  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 指标 SDK View。有关示例，请参阅 此脚本。

有关使用 OpenTelemetry 和此 APM 代理的一般指南，请参阅 OpenTelemetry bridge。

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

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

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

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

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

用法示例

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

添加于：v3.34.0

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

有效值为

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

将此选项设置为 false 将禁用 Span 压缩功能。Span 压缩减少了收集、处理和存储开销，并消除了 UI 中的混乱。折衷方案是，不会收集某些信息，例如所有压缩 span 的数据库语句。

用法示例

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

如果连续的跨度完全匹配且持续时间低于此阈值，则会被压缩成一个复合跨度。此选项不适用于复合跨度。这可以减少收集、处理和存储开销，并消除 UI 中的混乱。缺点是不会收集所有压缩跨度的 DB 语句。

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

用法示例

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

如果连续的、到相同目标的跨度持续时间低于此阈值，则会被压缩成一个复合跨度。此选项不适用于复合跨度。这可以减少收集、处理和存储开销，并消除 UI 中的混乱。缺点是不会收集所有压缩跨度的 DB 语句。

用法示例

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

在 v3.34.0 版本中作为实验性功能添加。

将此选项设置为 true 将启用 OpenTelemetry Bridge。简而言之，OpenTelemetry Bridge 允许您使用厂商无关的 OpenTelemetry Tracing 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。）