升级到 v4.x

以下 Kubernetes 环境变量的支持已被移除：ELASTIC_APM_KUBERNETES_NAMESPACE、ELASTIC_APM_KUBERNETES_NODE_NAME、ELASTIC_APM_KUBERNETES_POD_NAME 和 ELASTIC_APM_KUBERNETES_POD_UID。这些配置变量的正确环境变量是 *不带* ELASTIC_APM_ 前缀的——例如 KUBERNETES_POD_NAME——并且自 v2.11.0 版本以来一直是这样记录的。

如何检查。 在您的项目中搜索任何使用 ELASTIC_APM_KUBERNETES_ 的地方。例如，使用 ripgrep，运行 rg ELASTIC_APM_KUBERNETES_。如果有任何匹配项，请移除 ELASTIC_APM_ 前缀。

对 filterHttpHeaders 配置选项的支持已被移除。HTTP 头部和请求 Cookie 的屏蔽由现有的配置选项 sanitizeFieldNames 控制。

如何检查。 在您的项目中搜索 rg filterHttpHeaders 或 rg ELASTIC_APM_FILTER_HTTP_HEADERS 并将其移除。

useElasticTraceparentHeader 配置选项的默认值已更改为 false。这意味着默认情况下，特定于供应商的 elastic-apm-traceparent 头部将不再添加到传出的 HTTP 请求中。APM 代理会添加 traceparent 头部（来自 W3C trace-context 标准）。如果您需要代理继续发送 elastic-apm-traceparent HTTP 头部，您可以通过环境变量或启动选项将其设置为 true。

如何检查。 在您的项目中搜索 rg useElasticTraceparentHeader 或 rg ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER。

contextManager 配置选项的 "patch" 值已被移除。这是一个有限的异步上下文管理，早于首选的 AsyncLocalStorage Node.js 核心机制用于上下文跟踪。同样，相关的和已弃用的 asyncHooks 配置选项也已被移除。两者都在 v3.37.0 中被弃用。

如何检查。 在您的项目中搜索将值设置为 "patch" 的 rg -w contextManager 或 rg -w ELASTIC_APM_CONTEXT_MANAGER。还搜索将值设置为 false 的 rg -w asyncHooks 或 rg -w ELASTIC_APM_ASYNC_HOOKS。如果是这样，则该配置设置不再受支持。

logUncaughtExceptions 配置选项已被移除。在 v3 和更早版本中，当 APM 代理 捕获未捕获的异常 时，设置 logUncaughtExceptions: true 将告诉代理在退出之前将错误详细信息打印到 stderr；但是 logUncaughtExceptions 默认值为 false。在 v4 中，默认情况下会将错误打印到 stderr（以模拟默认的 Node.js 未捕获异常行为），并且没有选项可以禁用它。

如何检查。 在您的项目中搜索 rg -w logUncaughtExceptions 或 rg -w ELASTIC_APM_LOG_UNCAUGHT_EXCEPTIONS 并移除任何用法。

对错误的 ELASTIC_SANITIZE_FIELD_NAMES 和 ELASTIC_IGNORE_MESSAGE_QUEUES 配置环境变量的支持已被移除。正确的环境变量分别是 ELASTIC_APM_SANITIZE_FIELD_NAMES 和 ELASTIC_APM_IGNORE_MESSAGE_QUEUES，并且自 v3.36.0 版本开始受支持。

如果代理尚未启动，apm.startTransaction() 方法已更改为返回一个什么也不做的空操作事务。返回类型已更改，不再包含 | null。这些更改的目的是允许用户使用 .startTransaction() 而无需担心代理是否已启动，也不需要处理可能的 null 返回值。

如何检查。 在您的项目中搜索 rg '\.startTransaction\b'。如果您的代码处理了此函数调用可能返回的 null 值，您可以移除该处理。

subtype 和 action 属性已从 Transaction 中移除。这也影响了 apm.startTransaction([name][, type][, options]) 和 transaction.setType(...)，两者现在都不再接受 subtype 和 action 参数。这两个属性在 v3.25.0 中被弃用。

如何检查。 在您的项目中搜索 rg '\.startTransaction\b'。如果您的代码传入 subtype 或 action 参数，例如 apm.startTransaction('a-name', 'a-type', 'a-subtype', 'an-action', { /* options */ })，则需要更新它们。还在您的项目中搜索 rg '\.subtype\b' 和 rg '\.action\b'。如果这些属性访问位于 APM Transaction 对象上，则应将其移除。（请注意，APM Span 对象上的 subtype 和 action 仍然存在于 API 中。）

span.toString() 和 transaction.toString() 方法已被移除作为已记录的 API。它们从未出现在 "index.d.ts" 类型中，并且在 v3.23.0 中被弃用。

自 v2.17.0 版本以来，它们将返回 trace.id=<hex id the trace> span.id=<hex id of the span> 形式的字符串，目的是将其用于纯文本日志记录器进行日志关联。.toString() 用于此目的在 v3.23.0 中被弃用，现在已在 v4 中移除。在 v4 中，.toString() 的输出未定义。

相反，最好使用 span.ids、transaction.ids 或 apm.currentTraceIds。v3 格式可以通过以下方式复制

const {stringify} = require('querystring');
console.log(stringify(span.ids, ' ', '='));

对于使用结构化日志的日志关联，请参阅 日志关联。

apm.destroy() 方法现在是异步的。几乎没有用户需要使用此方法。但是，如果使用，为了确保等待 APM 代理关闭完成，现在可以使用 await apm.destroy()。

{"log.level":"warn","@timestamp":"2023-08-04T16:54:03.116Z","log":{"logger":"elastic-apm-node"},"ecs":{"version":"1.6.0"},"message":"units missing in duration value \"5\" for \"metricsInterval\" config option: using default units \"s\""}

定义持续时间的配置选项，例如 metricsInterval 或 exitSpanMinDuration，需要在其值中指定其单位（例如 "10s"、"100ms"）。虽然当前的持续时间选项具有默认单位，但为了避免歧义，APM 代理现在会在未提供单位时发出警告。

像 apiRequestSize 这样的字节大小配置选项需要在其值中指定大小单位（例如 "10kb"、"1gb"）。如果值中没有单位，代理将对此发出警告并回退到字节 (b)。