如何快速上手 opentracing-javascript:10分钟完成安装、配置并跑出第一条 Trace

原创2026-11-11 17:40:431,353 阅读

如何快速上手 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 实现了。

登录后查看全文
opentracing-javascript