如何快速上手 opentracing-javascript:10分钟完成安装、配置并跑出第一条 Trace
如何快速上手 opentracing-javascript:10分钟完成安装、配置并跑出第一条 Trace
opentracing-javascript 是 OpenTracing 规范在 JavaScript 生态(Node.js 与浏览器端)的官方 API 实现,通过统一的 Tracer / Span 接口,帮开发者给自己的服务加上分布式追踪(Distributed Tracing)。本文带你 10 分钟完成 npm 安装、跑通官方 MockTracer 示例并查看第一条 Trace 输出,最后掌握 startSpan、setTag、finish 等核心 API。
⚠️ 温馨提示:根据项目自身描述,该库已被标记为 DEPRECATED(停止维护)。用它来学习分布式追踪的 API 概念与思路仍然很有价值,但生产环境建议改用仍在积极维护的替代方案(如 OpenTelemetry)。
为什么需要 OpenTracing JavaScript
分布式系统里,一次用户请求往往要穿过多个服务、多个数据库。OpenTracing 用 Span(跨度) 表示一个「逻辑工作单元」,用 Trace(链路) 把多个 Span 串成一条调用链。
opentracing-javascript 的价值在于提供一套稳定的抽象 API:你只面向接口写埋点代码,底层可以随意切换具体的 Tracer 厂商,无需重写业务逻辑。核心概念三件套:
| 概念 | 作用 | 源码位置 |
|---|---|---|
Tracer |
埋点入口,负责创建 Span | src/tracer.ts |
Span |
表示一个逻辑工作单元 | src/span.ts |
SpanContext |
Span 中可跨进程传播的「上下文」 | src/span_context.ts |
环境准备:确认 Node.js 版本
查看 package.json 可知,该库对运行环境几乎零门槛:
- 运行支持:
node >= 0.10 - 开发构建:建议
node >= 6
只要你能跑 npm,就能直接开始。
第一步:一条命令完成 opentracing-javascript 安装
在项目根目录执行:
npm install --save opentracing
安装完成后,require('opentracing') 即可拿到 API 命名空间。得益于 TypeScript 重写的 src/index.ts,如果你用 TypeScript,类型定义会开箱即用,无需额外安装 .d.ts。
第二步:跑通官方示例,生成第一条 Trace
仓库自带一个基于 MockTracer 的演示程序,位于 src/examples/demo/demo.ts。直接运行:
npm run example
它会依次创建一个 parent_span,延迟 1 秒后再创建它的子 child_span,最后打印报告。控制台输出大致如下:
Spans:
parent_span - 1521ms
tag 'custom':'tag value'
tag 'alpha':'1000'
child_span - 503ms
tag 'alpha':'200'
tag 'beta':'50'
读懂输出:parent_span 与 child_span 的关系
对照 demo.ts 的逻辑,这段输出其实就是一棵 Span 树:
parent_span - 1521ms:根 Span,整个链路耗时约 1.5 秒。child_span - 503ms:子 Span,通过tracer.startSpan('child_span', { childOf: parent })挂到父节点下。tag 'alpha':'1000':由span.setTag('alpha', '1000')写上的键值标签。durationMs():MockSpan自带的耗时计算方法,返回_finishMs - _startMs,见 mock_span.ts。
💡 注意:
report()方法是MockTracer特有的辅助功能,不属于 OpenTracing 标准 API,仅用于本地演示与单元测试断言。
核心 API 速览:Tracer、Span、SpanContext
上手阶段只需要记住下面这几个高频方法:
Tracer 侧(src/tracer.ts)
startSpan(name, options?):创建 Span;options.childOf可指定父 Span,options.tags可批量打标签。inject(spanContext, format, carrier):把上下文写入载体,用于跨进程传播。extract(format, carrier):从载体中还原出SpanContext。
Span 侧(src/span.ts)
setTag(key, value)/addTags(map):给 Span 打标签。log(keyValuePairs, timestamp?):记录一条键值对日志。setBaggageItem/getBaggageItem:存取可跨子级传播的行李数据。finish(finishTime?):结束 Span,必须是 Span 的最后一个调用。context():拿到对应的SpanContext。
常用的标准标签(如 error、http.method、http.status_code)都集中在 src/ext/tags.ts 中,方便你按规范统一命名。
三种 Tracer 的初始化方式
这是新手最容易踩的坑——默认 Tracer 什么都不记录。
1)默认 no-op(不记录)
const tracer = new opentracing.Tracer(); // 空操作,仅占位
2)全局 tracer(推荐在应用入口设置一次)
opentracing.initGlobalTracer(new MyTracer());
const tracer = opentracing.globalTracer(); // 始终返回非空对象
实现见 src/global_tracer.ts,它通过「代理」机制解决了初始化顺序问题,即使在初始化前调用也不会报错。
3)MockTracer(演示 / 单元测试专用)
const tracer = new MockTracer();
MockTracer 会把所有 Span 缓存在内存里,再用 report() 一次性取出做断言,实现见 src/mock_tracer/mock_tracer.ts。
🎯 一句话总结:默认 Tracer 是空壳,想真正拿到追踪数据,必须把它替换成你选择的 Tracer 实现(或用于测试的
MockTracer)。
给请求埋点:一个最小 HTTP 追踪片段
把埋点套在关键操作前后即可,核心就三步:startSpan → setTag/log → finish。
const opentracing = require('opentracing');
const tracer = opentracing.globalTracer();
const span = tracer.startSpan('http_request');
span.setTag('http.method', 'GET');
// ... 处理请求 ...
span.setTag('http.status_code', 200);
span.finish(); // 必须是最后一步
完整可参考 README.md 中「Code snippet」一节的 HTTP 请求示例。
常见问题快速排查
- 为什么我的 Tracer 什么都没记录?
默认
new opentracing.Tracer()是 no-op 实现。请换成具体 Tracer,或测试时用MockTracer。 - TypeScript 用户要额外装类型包吗?
不用,源码即 TypeScript,
npm install后类型自动生效。 - 浏览器端怎么用?
仓库用 webpack 打包了两个 bundle:
dist/opentracing-browser.min.js(压缩版)和dist/opentracing-browser.js(含运行时检查的调试版),通过<script>引入后全局可用opentracing命名空间。 - 想验证自己写的 Tracer 是否合规? 可用 src/test/api_compatibility.ts 提供的兼容性检查,传入一个返回新 Tracer 实例的函数即可。
关键源码文件导航
| 文件 | 说明 |
|---|---|
| src/index.ts | 库的总入口,导出全部 API |
| src/tracer.ts | Tracer 基类与 SpanOptions |
| src/span.ts | Span 基类定义 |
| src/global_tracer.ts | 全局 tracer 的初始化与代理 |
| src/mock_tracer/ | 演示 / 测试用的 MockTracer 全家桶 |
| src/examples/demo/demo.ts | 官方快速示例源码 |
| package.json | 脚本与依赖定义(npm run example 等) |
✅ 小结:npm install --save opentracing → npm run example 看到 Span 树输出 → 用 startSpan / setTag / finish 给自己的业务埋点,三步就能跑通第一条 Trace。理解 Tracer、Span、SpanContext 这套抽象后,你就能灵活对接任意 OpenTracing 实现了。