支持的技术
Elastic APM Node.js 代理会自动对 Node.js 核心以及第三方框架和包中的各种 API 进行埋点。此页面列出了所有支持的技术和版本范围。
Elastic 支持 OpenTelemetry，它允许对其中的许多技术进行日志、指标和追踪信号收集。建议使用 EDOT Node.js SDK 来获取可观测性数据，以便持续享受 Elastic 平台的全部强大功能。
对 Elastic APM Node.js 代理的支持遵循 Node.js 自身的支持计划，直至每个版本维护期结束后的生命周期终止（EOL）期。不支持已过生命周期日期的 Node.js 版本。
APM 代理 4.x 版本适用于 Node.js 14.17.0 及更高版本。APM 代理 3.x 维护版本适用于 Node.js 8.6 及更高版本。我们仅在发布 APM 代理的主版本时才会停止支持较旧的 Node.js 版本。
从 v3.48.0 版本开始，Elastic APM Node.js 代理包含对埋点 ECMAScript 模块导入的有限且实验性支持，即通过 import ... 语句和 import('...')（动态导入）加载的模块。有关详细信息，请参阅 ECMAScript 模块支持文档。
注意：如果您使用的是通过 Babel、Webpack、esbuild 等工具编译/转换/转译为使用 CommonJS 的 JavaScript 的 TypeScript 或 JavaScript，则在源代码中使用 import ... 是没有问题的。为确保您的编译器生成使用 CommonJS 导入的 JS，请使用以下设置：
- 对于 TypeScript，请在 "tsconfig.json" 中使用
"module": "commonjs"（参见 完整的 tsconfig.json 示例）。 - 对于 Babel，请在 Babel 配置中使用
"modules": "commonjs"（例如）。 - 对于 Webpack，请在 "webpack.config.js" 中使用
target: 'node', externalsPresets: { node: true }。 - 对于 esbuild，请向
esbuild传递--platform=node --target=node...选项（例如）。
此代理与 APM Server v6.6 及更高版本兼容。
尽管您可以将 Elastic APM 与 任何 Node.js 框架一起使用，但我们为最受欢迎的 Node.js 模块提供了一些自动化支持。以下是我们官方支持的框架：
| 框架 | 版本 | 注意 |
|---|---|---|
| AWS Lambda | 不适用 | |
| Azure Functions | v3, v4 | Node.js 编程模型 v3 和 v4 |
| Express | >=4.0.0 <6.0.0 | |
| Fastify | >=2.0.0 <6 | 另请参阅 Fastify 官方的 LTS 文档 |
| @hapi/hapi | >=17.9.0 <22.0.0 | |
| 通过 koa-router 或 @koa/router 使用 Koa | >=5.2.0 <14.0.0 | Koa 没有内置的路由器，因此由于我们依赖路由器信息来实现全面支持，我们无法直接支持 Koa。我们目前支持最受欢迎的 Koa 路由器 koa-router。 |
| Restify | >=5.2.0 <12.0.0 | Restify 不再进行维护，因此不再对该埋点进行测试。 |
Node.js Elastic APM 代理通过其 OpenTelemetry 桥接器支持使用 OpenTelemetry 追踪 API。此外，它还对 OpenTelemetry 指标 API 和指标 SDK 进行埋点，以允许 使用 OpenTelemetry 指标 API。
| 框架 | 版本 |
|---|---|
| @opentelemetry/api | >=1.0.0 <1.10.0 |
| @opentelemetry/sdk-metrics | >=1.11.0 <2 |
如果使用的框架在上文列出，默认情况下，事务会根据其匹配的 HTTP 路由进行命名。这些模块会覆盖该行为，以便更好地深入了解专用的 HTTP 服务器
| 模块 | 版本 | 注意 |
|---|---|---|
| express-graphql | >=0.6.1 <0.13.0 | 将根据 GraphQL 查询名称命名所有事务。node <10.4 存在已知问题。该模块已被弃用且不再受测试。 |
| apollo-server-express | >=2.0.4 <4 | 将根据 GraphQL 查询名称命名所有事务。不再对 2.9.6 之前的版本进行测试。 |
| @apollo/server | >=4.0.0 <5 | 将根据 GraphQL 查询名称命名所有事务 |
Node.js 代理将自动对以下模块进行埋点，为您提供详细的性能指标
| 模块 | 版本 | 注意 |
|---|---|---|
| aws-sdk | >=2.858.0 <3 | 将对 SQS 发送/接收/删除消息、所有 S3 方法、所有 DynamoDB 方法以及 SNS 发布方法进行埋点 |
| @aws-sdk/client-s3 | >=3.15.0 <4 | 将对所有 S3 方法进行埋点 |
| @aws-sdk/client-sns | >=3.15.0 <4 | 将对 SNS 发布方法进行埋点 |
| @aws-sdk/client-sqs | >=3.15.0 <4 | 将对 SQS 发送/接收/删除消息进行埋点 |
| @aws-sdk/client-dynamodb | >=3.15.0 <4 | 将对所有 DynamoDB 方法进行埋点 |
| cassandra-driver | >=3.0.0 <5 | 将对所有查询进行埋点 |
| elasticsearch | >=8.0.0 <17 | 将对所有查询进行埋点 |
| @elastic/elasticsearch | >=7.0.0 <10.0.0 | 将对所有查询进行埋点 |
| graphql | >=0.7.0 <17 | 将对所有查询进行埋点 |
| handlebars | >=1 <5 | 将对编译和渲染调用进行埋点 |
| jade | >=0.5.6 <2 | 将对编译和渲染调用进行埋点；已弃用。不再受测试。请使用 pug。 |
| pug | >=0.1.0 <4 | 将对编译和渲染调用进行埋点 |
| ioredis | >=2.0.0 <6.0.0 | 将对所有查询进行埋点 |
| memcached | >=2.2.0 <3 | 将对所有命令进行埋点。 |
| mongodb-core | >=1.2.19 <4 | 将对所有查询进行埋点。许多高级 MongoDB 模块都使用了 mongodb-core，因此这些模块也应该受到支持。 |
| mongodb | >=2.0.0 <3.3.0 | 通过 mongodb-core 支持 |
| mongodb | >=3.3.0 <7 | 将对所有查询进行埋点 |
| mongojs | >=1.0.0 <2.7.0 | 通过 mongodb-core 支持 |
| mongoose | >=4.0.0 <5.7.0 | 通过 mongodb-core 支持 |
| mongoose | >=5.7.0 <8 | 通过 mongodb 支持 |
| mysql | >=2.0.0 <3 | 将对所有查询进行埋点 |
| mysql2 | >=1.0.0 <4.0.0 | 将对所有查询进行埋点 |
| pg | >=4.0.0 <9.0.0 | 将对所有查询进行埋点 |
| redis | >=2.0.0 <5.0.0 | 将对所有查询进行埋点 |
| tedious | >=1.9 <20.0.0 | （不包括 v4.0.0。）将对所有查询进行埋点 |
| undici | >=4.7.1 <8 | 将对 undici HTTP 请求（HTTP CONNECT 除外）进行埋点。要求 Node.js v14.17.0 或更高版本，或者用户已安装 diagnostics_channel polyfill。 |
| ws | >=1.0.0 <8.0.0 | 将对传出的 WebSocket 消息进行埋点 |
| kafkajs | >=2.0.0 <3.0.0 | 将对生产者的所有发送方法以及消费者的消息和批量处理进行埋点。 |
可以将 APM 代理配置为捕获跨度堆栈追踪，以显示代码中是在何处发起某个跨度（例如数据库查询）的。
鉴于 Node.js 的异步特性，APM 代理无法追溯到最后一个异步边界之前的内容。如果在您的应用代码调用与导致 APM 跨度的操作之间恰好存在异步边界，相关模块将限制这些跨度堆栈追踪的实用性。
下面列出的模块是启用后由 APM 代理进行埋点的模块，旨在提供更有用的跨度堆栈追踪（即指向您的应用代码的堆栈追踪）。
如果您在跨度中看不到自己的代码，请在 Elastic APM 讨论论坛中创建一个新主题，并附上有关您的依赖项的信息。
| 模块 | 版本 | 注意 |
|---|---|---|
| knex | >=0.10.0 <4.0.0 | 为 pg 和 mysql 跨度提供更好的跨度堆栈追踪。 |
Elastic APM 代理会监视 Node.js 应用程序中的异步操作，以随时了解哪个请求在任何给定时间处于活动状态。如果处理不当，某些模块可能会干扰此监控。
以下是已知会在此监控中引发问题的模块列表。列出的版本是我们支持的版本。如果您使用的是不受支持的版本，可能会遇到缺少跨度的情况。这绝不会影响应用程序的稳定性——只会影响收集到的指标。
如果您的性能指标中确实遇到了缺少跨度的情况，请在 Elastic APM 讨论论坛中创建一个新主题，并包含有关您的依赖项以及丢失了哪些数据的信息。
| 模块 | 版本 | 注意 |
|---|---|---|
| bluebird | >=2.0.0 <4.0.0 | |
| generic-pool | ^2.0.0 || ^3.1.0 | 被许多数据库模块使用，例如 "pg" |
| express-queue | >=0.0.11 <1.0.0 |