基于 OpenTelemetry 的 Node.js 服务链路追踪接入指南

前阵子线上有个下单接口偶尔慢到七八秒，把几个服务的日志翻了个遍，单看每个服务都挺正常，最后才发现是订单服务调库存服务，库存服务里又同步调了一次优惠券服务，优惠券那边躺着一个没加索引的慢查询。这种问题光靠日志是真排查不动，所以决定把几个 Node.js 服务统一接上 OpenTelemetry。过程踩了不少坑，官方文档散得到处都是，JS 这边光入门就要看好几个页面，为什么不能给个一页式的接入文档呢？可能是我瞎没找到吧...

下面是实测能跑通的接入方式，以 express + mysql 的服务为例，别的框架大同小异，照着抄改改就行，省得你自己一点点啃文档。

先把几个概念捋清楚，不然容易懵

OpenTelemetry JS 这边的包是真的多，@opentelemetry/api、@opentelemetry/sdk-node、还有一大堆 @opentelemetry/instrumentation-*，第一次看很容易不知道从哪儿下手。简单说：api 只定义接口，真正干活的是 sdk-node，自动埋点靠那一堆 instrumentation 插件，数据往哪儿发由 exporter 决定。手动埋点不是不行，就是工作量大还容易漏，我这里直接走自动埋点，业务关键的地方再补几个自定义 span。

Collector 可装可不装，本地调试直接把 span 发到 Jaeger 就够了，生产环境建议中间垫一层，后面想换后端的时候应用侧一行代码都不用改。

安装依赖

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http

auto-instrumentations-node 把常用的插件都打包好了，http、express、redis、mysql、pg 这些主流库都能自动埋，省得一个一个装。副作用是装多了启动会慢一点，介意的话就只装自己用到的，比如单独装 @opentelemetry/instrumentation-express。

初始化代码

项目根目录新建一个 instrumentation.ts，js 项目把后缀换掉就行，内容如下：

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  serviceName: