Elastic APM Node.js Agent 快速入门指南：3步为 Express 应用接入错误监控与分布式链路追踪

Elastic APM Node.js Agent 快速入门指南：3步为 Express 应用接入错误监控与分布式链路追踪

【免费下载链接】apm-agent-nodejsElastic APM Node.js Agent项目地址: https://gitcode.com/gh_mirrors/ap/apm-agent-nodejs

Elastic APM Node.js Agent是 Elastic 官方的 Node.js 应用性能监控（APM）代理，它能自动捕获 Express 应用的错误、链路追踪（Tracing）数据与性能指标，并发送到 Elastic Stack（APM Server + Elasticsearch + Kibana），帮你快速定位慢请求和服务问题的根因。对于新手来说，接入过程非常友好：只需 3 步，就能让错误监控和分布式链路追踪在你的 Express 应用中跑起来。

接入前准备：确认你的环境

在开始之前，请确认两件事：

1. 已部署一套 Elastic Stack（包含 APM Server、Elasticsearch、Kibana），并拿到两个关键信息：
   • APM Server 的serverUrl
   • 访问凭证secretToken（或apiKey）
2. Node.js 版本满足 Agent 要求。Agent 默认会自动插桩（instrument）最常见的模块，如 Express、HTTP/HTTPS、数据库驱动、消息队列等，完整清单见 supported-technologies.md。

💡 一个重要的前提认知：Agent 必须在require(...)加载任何其他模块之前启动，这样它才能在模块加载时"插入"自己的监控代码。这是后面第 2 步的核心原因。

第 1 步：一键安装 APM Agent 包

在你的 Express 项目根目录执行一条命令，把elastic-apm-node安装为依赖：

npm install elastic-apm-node --save

这就是官方文档 README.md 中给出的标准安装方式，几秒即可完成。

第 2 步：在入口文件最顶部启动 Agent

在应用的主入口文件（通常是index.js、server.js或app.js）最顶部加入启动代码：

// 放在文件最顶部，先于其他 require / import const apm = require('elastic-apm-node').start({ serverUrl: '<你的 APM Server 地址>', secretToken: '<你的 secretToken>', serviceName: 'my-express-app', environment: 'production', }) const app = require('express')() app.get('/', (req, res) => res.send('Hello World!')) app.listen(3000)

关键点拆解：

⚠️ 为什么必须在最顶部？如果express、http等模块先于 Agent 被加载，Agent 就无法对它们插桩，监控会失效（表现为 Kibana 里出现 "unknown route" 事务）。更多启动方式（例如不改代码的node -r elastic-apm-node/start.js方式）见 starting-agent.md。

不喜欢改代码？也可以用环境变量完成同样的配置，然后只写一行require('elastic-apm-node').start()：

export ELASTIC_APM_SERVICE_NAME=my-express-app export ELASTIC_APM_SECRET_TOKEN=<token> export ELASTIC_APM_SERVER_URL=<url>

第 3 步：运行并验证错误监控与链路追踪

启动你的 Express 应用后，Agent 会立即开始工作：

• 性能与链路追踪：每个入站 HTTP 请求都会生成一个 Transaction（事务），其中的数据库查询、外部 HTTP 调用等会被记录为 Span（跨度），自动串成完整的调用链路。
• 错误监控：未捕获的异常（uncaught exceptions）会被自动捕获并上报，无需任何额外代码。

对于通过回调返回、Promise 捕获或手动构造的错误，可以一行代码手动上报：

apm.captureError(new Error('Ups, something broke!'))

在 Kibana 中查看监控效果

数据发送到 Elastic Stack 后，打开 Kibana 的 Observability → APM，选择你的serviceName，就能看到：

• Transactions（事务）：按路由查看每个接口的耗时、吞吐量和错误率；
• Spans（跨度）：单个请求内部的数据库、外部调用明细，形成可视化链路图；
• Errors（错误）：错误详情、堆栈和触发该错误的具体请求上下文。

下面是一个典型的 APM 指标时间序列视图示例（按 5 秒聚合的请求量中位数），可以直观看到服务负载的变化曲线：

进阶玩法：让追踪数据更丰富

接入完成后，还可以按需扩展：

• 自定义 Span：为非自动插桩的代码段手动计时，参考 custom-spans.md；
• 自定义 Transaction：为定时任务等非 HTTP 场景创建事务，参考 custom-transactions.md；
• 附加业务上下文：用apm.setUserContext()、apm.setLabel()给错误和事务打上用户信息、标签；
• 过滤敏感信息：Agent 默认会过滤 HTTP Body 和敏感 Header，可用captureBody、sanitizeFieldNames按需调整；
• 完整 API：所有方法见 agent-api.md，Express 专题指南见 express.md。

常见注意事项

小结

通过本文的 3 步——安装elastic-apm-node、在入口文件顶部调用start()、运行验证——你就为 Express 应用接入了完整的错误监控与分布式链路追踪能力。Elastic APM Node.js Agent 的自动插桩机制意味着无需侵入业务代码，即可获得事务、跨度、错误和性能指标四大类可观测性数据，是 Node.js 开发者排查线上问题的利器。

【免费下载链接】apm-agent-nodejsElastic APM Node.js Agent项目地址: https://gitcode.com/gh_mirrors/ap/apm-agent-nodejs