可观测性与稳定性 / 系统课时
使用自动埋点采集服务请求
使用自动埋点采集服务请求
自动埋点适合先把“请求从哪里进、又调用到哪里去”采起来,而不必在每个路由里手写 Span。本节用 Node.js 服务验证入站 HTTP、出站 HTTP 与上下文传播,并明确哪些业务步骤仍需要手工埋点。
学习目标
- 使用 OpenTelemetry Node.js 自动埋点采集常见入站与出站请求。
- 验证同一次请求中的父子 Span 是否处于同一条 Trace。
- 判断自动埋点能覆盖的框架边界,以及需要手工补充的业务边界。
自动埋点实际替你做了什么
自动埋点通过 instrumentation 在受支持的库和框架调用点创建 Span,并在入站请求进入时提取上下文、在出站请求发起时注入上下文。初始化必须发生在应用模块加载之前,否则目标模块可能已经加载,instrumentation 就失去了正确的补丁时机。
它擅长回答“哪个 HTTP 请求慢”“下游调用耗时多少”,却不会理解“结算”“库存预占”这类业务语义。自动 Span 是技术调用边界,不等于完整的业务追踪模型。

搭一个可验证的请求链
准备一个空目录,并安装 Express 与 OpenTelemetry Node.js 自动埋点依赖:
npm init -y
npm install express @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-trace-node @opentelemetry/auto-instrumentations-node预期结果
npm 以退出码 0 完成安装;package.json 中出现 express 与上述 OpenTelemetry 依赖。具体安装日志和包数量会因 npm 版本而不同。下面是片段示例 instrumentation.mjs。它必须与随后给出的 app.mjs 配合使用,且通过 Node.js 的 --import 在应用代码之前加载:
import { NodeSDK } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
traceExporter: new ConsoleSpanExporter(),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();生效行为:SDK 启动后会注册自动 instrumentation,并把结束的 Span 输出到控制台;这个文件本身不是业务入口。
下面是片段示例 app.mjs。/gateway 会通过 Node.js HTTP 客户端再调用同一进程中的 /downstream,因此能同时观察入站与出站自动 Span:
import express from 'express';
import http from 'node:http';
const app = express();
app.get('/downstream', (_req, res) => {
res.json({ ok: true });
});
app.get('/gateway', (_req, res) => {
const upstream = http.get('http://127.0.0.1:3000/downstream', (response) => {
let body = '';
response.setEncoding('utf8');
response.on('data', (chunk) => {
body += chunk;
});
response.on('end', () => {
res.status(response.statusCode ?? 502).type('application/json').send(body);
});
});
upstream.on('error', () => {
res.status(502).json({ ok: false });
});
});
app.listen(3000, '127.0.0.1', () => {
console.log('listening on http://127.0.0.1:3000');
});先启动服务:
OTEL_SERVICE_NAME=auto-http-demo node --import ./instrumentation.mjs app.mjs预期输出
listening on http://127.0.0.1:3000保持该进程运行,在另一个终端发起请求:
curl -s http://127.0.0.1:3000/gateway预期输出
{"ok":true}随后第一个终端会出现 ConsoleSpanExporter 输出。具体 Span 名称与附加框架 Span 会随 instrumentation 版本和配置变化,但同一次调用中应能看到 gateway 入站、到 downstream 的 HTTP 客户端调用,以及 downstream 入站对应的 Span,并共享同一个 traceId。
看懂覆盖边界
自动埋点是否生效,先按“有没有 instrumentation、是否足够早加载、调用是否真的经过被支持的库”排查。只要其中一项不成立,就不能因为安装了自动埋点包而假定一定会有 Span。
- 常见 Web 框架、HTTP 客户端、数据库驱动等通常由对应 instrumentation 负责,实际覆盖范围取决于已启用的模块和兼容版本。
- 自己编写的普通业务函数不会自动变成有意义的业务 Span;要追踪“支付确认”“库存预占”等动作,应补手工埋点。
- 自动埋点初始化过晚时,应用模块可能已经被加载,最典型表现是服务能运行但看不到预期框架 Span。
- 自动 Span 过多时,应从禁用低价值 instrumentation、采样和后端查询三个层面治理,而不是在业务代码里逐个删除自动 Span。
自动埋点的目标不是“Span 越多越好”,而是先稳定获得协议与框架层的主干链路。只要入站、出站和上下文传播可靠,后续就可以把手工 Span 精确补在真正有业务诊断价值的位置。