升级到 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 中被弃用。

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

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 事务对象上，则应移除它们。（请注意，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)。