升级到 v4.x
以下是关于将 Elastic APM Node.js 代理 (elastic-apm-node) 从 3.x 版本升级到 4.x 版本的指南。
elastic-apm-node 的 4.x 版本支持 Node.js v14.17.0 及更高版本。（以前的 3.x 主版本支持到 Node.js v8.6.0。）
已移除对以下 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。这意味着默认情况下不会再向发出的 HTTP 请求添加特定于供应商的 elastic-apm-traceparent 头部。APM 代理会添加 traceparent 头部（来自 W3C trace-context 标准）。如果您需要代理继续发送 elastic-apm-traceparent HTTP 头部，可以通过环境变量或启动选项将其设置为 true。
如何检查。 在项目中搜索 rg useElasticTraceparentHeader 或 rg ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER。
配置选项 contextManager 的值 "patch" 已被移除。这是一种有限的异步上下文管理方式，它出现于 Node.js 用于上下文跟踪的首选核心机制 AsyncLocalStorage 之前。同时，相关的已废弃配置选项 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() 方法已更改为返回一个不执行任何操作的 no-op Transaction。返回类型已更改为不再包含 | null。这些更改的目的是让用户无需担心代理是否已启动，也无需处理可能的 null 返回值，即可使用 .startTransaction()。
如何检查。 在项目中搜索 rg '\.startTransaction\b'。如果您的代码处理了此函数调用可能返回的 null 值，您可以移除相应的处理逻辑。
Transaction 中的 subtype 和 action 属性已被移除。这也会影响 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=<trace 的十六进制 ID> span.id=<span 的十六进制 ID> 的字符串，目的是在纯文本日志记录器中用于日志关联。在 v3.23.0 中，使用 .toString() 实现此功能被废弃，现在在 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()。
本节记录了 APM 代理的一些新的日志输出警告，以及如何避免它们。
{"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)。