升级至 v4.x

以下是将 Elastic APM Node.js 代理（elastic-apm-node）的使用版本从 3.x 升级到 4.x 的指南。

Node.js 版本

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`

filterHttpHeaders 配置选项的支持已被移除。HTTP 标头和请求 Cookie 的脱敏由现有的配置选项 sanitizeFieldNames 控制。

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

`useElasticTraceparentHeader`

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

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

`contextManager: "patch"`

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`

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_SANITIZE_FIELD_NAMES 和 ELASTIC_IGNORE_MESSAGE_QUEUES 的支持已被移除。正确的环境变量分别为 ELASTIC_APM_SANITIZE_FIELD_NAMES 和 ELASTIC_APM_IGNORE_MESSAGE_QUEUES，它们从 v3.36.0 开始获得支持。

API 变更

`apm.startTransaction(...)`

如果代理尚未启动，apm.startTransaction() 方法已被更改为返回一个什么都不做的空操作（no-op）Transaction。返回类型已更改为不再包含 | null。这些更改的目的是允许用户使用 .startTransaction()，而不必担心代理是否已经启动，也不必处理可能返回的 null 值。

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

`transaction.subtype` 和 `transaction.action`

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()`

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

日志警告

本节记录了来自 APM 代理的一些新日志输出警告以及如何避免它们。

"units missing in duration value"

		{"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 代理现在会发出警告。

"units missing in size value"

字节大小配置选项（如 apiRequestSize）期望在值中指定大小单位（例如 "10kb"、"1gb"）。如果值中不包含单位，代理将发出警告并回退到字节（b）。