Midway 框架级分布式链路追踪(Tracing)实战指南:基于 OpenTelemetry 的内建实现
Midway 框架级分布式链路追踪(Tracing)实战指南:基于 OpenTelemetry 的内建实现
本文围绕 Midway(@midwayjs/core)从 v4 起内建的框架级 Tracing 能力展开,讲解 Trace/Span/Context Propagation 等核心概念、全局与组件级开关的配置方式、ctx.traceId、@Trace 装饰器与 MidwayTraceService 的使用方法,以及 meta 自定义属性、extractor/injector 上下文透传、自定义 Propagator 与自定义 traceId 等进阶玩法,并附上从 @midwayjs/otel 迁移的完整清单。读完本文,你将能够在不引入额外组件的前提下,为基于 Midway 的 Web、gRPC、消息队列等应用一键开启全链路追踪,并接入 Jaeger/Zipkin/OTLP 等观测后端。
概述:框架级 Tracing 已经内建于 @midwayjs/core
从 Midway v4 开始,框架级 Tracing 被直接内建到 @midwayjs/core 中,无需再安装或启用 @midwayjs/otel。这意味着任意一个基于 Midway 构建的应用(无论是 Koa/Express 风格的 Web 服务、gRPC 服务,还是 Kafka/MQTT/RabbitMQ 等消息消费端),都能以统一的配置方式获得端到端的链路追踪能力。
理解这套机制,先要把握几条核心设计原则:
- Midway 会在**入口(entry)和出口(exit)**自动创建并传播 Span,开发者通常无需手写埋点代码。
tracing.enable是全局开关,只控制 Tracing 是否整体启用;它本身不区分协议。- 各协议的具体行为由对应组件配置,例如
koa.tracing、grpc.tracing、kafka.tracing等;core自身不感知协议差异。 - 每个组件都可以配置
<component>.tracing下的enable、meta、extractor、injector四个维度。 - 要在 Jaeger/Zipkin/OTLP 等后端看到 Trace,仍需要自行初始化 OpenTelemetry SDK 并配置 Exporter,Midway 只负责生成与传播 Span,不负责上报。
这些默认行为可以在源码中得到印证:@midwayjs/core 的默认配置 packages/core/src/config/config.default.ts 中即声明了 tracing: { enable: true, onError: 'ignore', logOnError: false },对应的类型定义位于 packages/core/src/interface.ts 的 tracing?: { enable?; onError?: 'throw' | 'ignore'; logOnError?: boolean }。
OpenTelemetry 基础概念速览
在深入配置之前,先统一几个 OpenTelemetry(OTel)的核心术语,它们贯穿全文:
- Trace(链路):一次端到端的请求流转,由多个 Span 组成,一个 Trace 对应一个全局唯一的
traceId。 - Span(跨度):链路中的一个操作单元,包含起止时间、状态(
status)与属性(attributes)。 - Context Propagation(上下文传播):把上游的 Trace 上下文传递给下游调用,传播载体随协议而异——HTTP 头、MQTT properties、gRPC metadata、消息头等。
- Attributes(属性):Span 上的 key/value 字段,用于在观测后端过滤与检索。
- TraceId(链路 ID):一条 Trace 的全局 ID,通常以 32 位十六进制字符串表示。
从代码实现看,这些概念都落实在 MidwayTraceService(见 packages/core/src/service/traceService.ts)中:它通过 trace.getTracer(this.currentTracerName).startActiveSpan(...) 创建 Span,通过 propagation.extract / propagation.inject 完成上下文提取与注入,并内置了一套兼容多种载体形态的默认 TextMapGetter / TextMapSetter(兼容 carrier.get()、carrier.setHeader()、普通对象键值等多种写法)。
快速开始:四步开启 Tracing
第 1 步:开启框架级 Tracing(默认即开启)
在 src/config/config.default.ts 中配置全局开关:
// src/config/config.default.ts
export default {
tracing: {
enable: true, // 全局开关,默认即为 true
onError: 'ignore', // 传播/注入出错时的行为:'ignore' 或 'throw'
logOnError: false, // 出错时是否打印 warn 日志
},
};
三个配置项的语义如下:
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enable |
boolean |
true |
全局 Tracing 开关,false 时所有组件都不产生 Span |
onError |
'throw' | 'ignore' |
'ignore' |
Span 上下文 extract/inject 失败时的策略:throw 会向上抛出异常,ignore 则静默跳过 |
logOnError |
boolean |
false |
失败时是否通过 coreLogger 输出 [midway:trace] ... failed 警告日志 |
这三个默认值均能在 packages/core/src/config/config.default.ts 与 MidwayTraceService.init()(packages/core/src/service/traceService.ts)中看到:初始化时 tracingConfig 会把用户配置与 { enable: true, onError: 'ignore', logOnError: false } 合并,handleTraceError 则同时实现 logOnError 打日志与 onError === 'throw' 抛错两条分支。
第 2 步:配置组件级开关
全局开关只决定“是否整体启用”,每个组件还需要自己的 tracing.enable 来决定“该组件是否发射 Span”:
// src/config/config.default.ts
export default {
tracing: {
enable: true, // 全局开关
},
koa: {
tracing: {
enable: true, // 开启 koa 组件的 Span
},
},
kafka: {
tracing: {
enable: false, // 只关闭 kafka 组件的 Span
},
},
};
规则归纳为两条:
tracing.enable = false:全局关闭,任何组件都不产生 Span;tracing.enable = true:每个组件依据自身的tracing.enable决定是否发射 Span。
在实现层面,组件的入口 Span 会读取组件配置中的 tracing.enable,并以 options.enable 传给 runWithEntrySpan;MidwayTraceService 在 isProtocolEnabled() 或 options.enable === false 时直接跳过 Span 创建(见 packages/core/src/service/traceService.ts)。
第 3 步:导出到控制台(最小可运行示例)
先安装最精简的依赖:
$ npm install --save @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
{
"dependencies": {
"@opentelemetry/api": "latest",
"@opentelemetry/sdk-trace-node": "latest",
"@opentelemetry/sdk-trace-base": "latest"
}
}
在 bootstrap.js 中初始化 TracerProvider,并注册 ConsoleSpanExporter:
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const {
ConsoleSpanExporter,
SimpleSpanProcessor,
} = require('@opentelemetry/sdk-trace-base');
const { Bootstrap } = require('@midwayjs/bootstrap');
const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();
Bootstrap.configure().run();
启动后,只有真正处理了请求/消息时才会打印 Span。一个典型的输出如下:
Span: {
name: 'GET /api/user',
kind: 1,
traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
parentId: undefined,
attributes: { 'midway.protocol': 'http' },
status: { code: 1 }
}
排查时请优先核对三个字段:
traceId:存在且为 32 位十六进制字符串;name:与你的请求/任务对应(例如GET /api/user、grpc UserService.GetUser);attributes['midway.protocol']:标明协议,如http/grpc/kafka。
如果看不到 Span,检查两点:一是 provider.register() 必须在 Bootstrap.configure().run() 之前执行;二是流量确实经过了被埋点的入口(例如 Web 中间件、gRPC 拦截器、消息消费回调)。
:::tip
在 dev 模式下,Span 不会出现在主进程控制台——dev 模式不走 bootstrap.js 的初始化路径,因此 OTel SDK 未被加载。
:::
关于协议属性的来源,可以从源码中得到印证:Koa 组件在 packages/web-koa/src/framework.ts 中通过 runWithEntrySpan 创建入口 Span,并注入 attributes: { 'midway.protocol': 'http' };gRPC Provider 侧则在 packages/grpc/src/provider/framework.ts 中创建名为 grpc ${serviceName}.${method} 的 Span,并注入 'midway.protocol': 'grpc' 与 'midway.grpc.method': method。
第 4 步:接入观测后端(可选)
常见 Exporter 一览:
- OTLP/HTTP:
@opentelemetry/exporter-trace-otlp-http - OTLP/gRPC:
@opentelemetry/exporter-trace-otlp-grpc - Jaeger:
@opentelemetry/exporter-jaeger - Zipkin:
@opentelemetry/exporter-zipkin
以 Jaeger 为例:
1. 安装 Jaeger Exporter
$ npm install --save @opentelemetry/exporter-jaeger
{
"dependencies": {
"@opentelemetry/exporter-jaeger": "latest"
}
}
2. 更新 bootstrap.js
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
const { Bootstrap } = require('@midwayjs/bootstrap');
const exporter = new JaegerExporter({
host: process.env.JAEGER_AGENT_HOST || '127.0.0.1',
port: Number(process.env.JAEGER_AGENT_PORT || 6832),
});
const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();
Bootstrap.configure().run();
3. 验证
- 启动应用并触发请求;
- 打开 Jaeger UI(通常为
http://127.0.0.1:16686); - 按服务名搜索,确认 Span 已出现。
框架级能力:ctx.traceId、@Trace 与 MidwayTraceService
ctx.traceId
@midwayjs/core 为所有基于 Context 的框架(web/koa/express/ws/grpc/faas 等)统一提供了 ctx.traceId:
ctx.traceId => '4bf92f3577b34da6a3ce929d0e0e4736'
其实现位于 packages/core/src/baseFramework.ts:框架在 ctx 上通过 Object.defineProperty 挂载只读的 traceId 属性,读取时从容器中获取 MidwayTraceService 并调用其 getTraceId()。而 getTraceId() 的实现是 trace.getSpan(context.active())?.spanContext().traceId——即从当前异步上下文的活动 Span 中取出 traceId(见 packages/core/src/service/traceService.ts)。
@Trace 装饰器
要为任意业务方法手动埋点,可直接使用 @Trace(spanName):
import { Trace } from '@midwayjs/core';
export class UserService {
@Trace('user.get')
async getUser() {
// ...
}
}
底层原理:Trace 通过 DecoratorManager.createCustomMethodDecorator(TRACE_KEY, { spanName }) 注册方法级装饰器(见 packages/core/src/decorator/common/tracer.ts),TRACE_KEY 为 'decorator:open_telemetry_key'。MidwayTraceService.init() 会注册对应的 around 方法处理器:进入方法时调用 createSpan(spanName, ...) 创建客户端 Span(SpanKind.CLIENT),方法成功则 span.setStatus({ code: OK }),抛出异常则标记 ERROR 并调用 span.recordException(err) 后重新抛出(见 packages/core/src/service/traceService.ts)。
MidwayTraceService
需要编程式控制 Span 时,注入 MidwayTraceService 即可:
import { Inject, MidwayTraceService } from '@midwayjs/core';
export class UserService {
@Inject()
traceService: MidwayTraceService;
}
MidwayTraceService 是单例(@Scope(ScopeEnum.Singleton)),主要 API 包括:
getTraceId():读取当前活动 Span 的 traceId;createSpan(name, callback):创建一个子 Span 并执行回调;runWithEntrySpan(name, options, callback):创建入口 Span(默认SpanKind.SERVER),可选地先从carrier提取上游上下文(propagation.extract),回调结束后再把上下文注入responseCarrier(propagation.inject);runWithExitSpan(name, options, callback):创建出口 Span(默认SpanKind.CLIENT),在发起下游调用之前把上下文注入carrier;injectContext(carrier, setter?):向指定载体注入当前上下文。
入口/出口 Span 都会自动合并 meta 解析出的业务属性到 Span attributes,并在异常时记录错误状态与异常对象,完整实现见 packages/core/src/service/traceService.ts。组件(Koa、gRPC、Kafka、MQTT、Redis 等)的框架层埋点正是通过这两个方法完成的,例如 packages/web-koa/src/framework.ts 与 packages/grpc/src/provider/framework.ts。
进阶:自定义 meta 业务属性
你可以把业务字段(用户 ID、租户 ID、队列名等)挂到 Span 上,方便后续检索与告警。meta 支持三种常见写法:
1. 静态对象
meta: {
'biz.app': 'user-center',
}
2. 函数(动态计算)
meta: ({ protocol, direction }) => ({
'biz.protocol': protocol,
'biz.direction': direction,
})
3. 方向化对象(common + entry + exit)
meta: {
common: { 'biz.app': 'user-center' },
entry: { 'biz.side': 'in' },
exit: { 'biz.side': 'out' },
}
回调参数一览:
direction:entry或exit;protocol:协议名(http、grpc、kafka、redis等);ctx:当前上下文;request/response:当前请求/响应对象;custom:组件相关信息(queueName、eventName、clientName等)。
需要说明的是,最终只有 string/number/boolean 类型的值会被保留到 Span 属性中。这一约束在 MidwayTraceService.pickTraceMetaValue() 中实现:遍历 meta 对象,仅收集字符串、数字、布尔值,null/undefined 及对象等复杂类型都会被丢弃;resolveTraceMeta() 则负责把“函数式”“静态对象”“方向化对象”三种形态统一解析,方向化对象会先合并 common,再按 direction 合并 entry 或 exit(见 packages/core/src/service/traceService.ts 与 packages/core/src/interface.ts 中的 TraceMetaResolver 类型定义)。
组件级 meta 示例:
// src/config/config.default.ts
export default {
koa: {
tracing: {
meta: {
common: ({ ctx }) => ({
'biz.app': 'user-center',
'biz.userId': (ctx as any)?.user?.id ?? 'anonymous',
}),
entry: ({ spanName }) => ({
'biz.entry.span': spanName,
}),
exit: ({ spanName }) => ({
'biz.exit.span': spanName,
}),
},
},
},
redis: {
tracing: {
meta: ({ custom }) => ({
'biz.redis.client': (custom as any)?.clientName ?? 'default',
}),
},
},
};
进阶:自定义入口/出口上下文位置(extractor / injector)
extractor 与 injector 服务于上下文传播(Context Propagation):
extractor:入口侧读取,在创建入口 Span 之前调用,用于从请求/消息中提取上游 Trace 上下文;injector:出口侧写入,在下游请求/消息发出之前调用,把当前上下文写入对方能识别的载体。
什么时候需要配置它们:
- 默认行为已满足需求时,什么都不用做;
- 你的传输层/头结构是自定义的;
- 不同协议需要不同的字段位置。
回调通用参数:request、response、ctx、carrier、custom。
返回值规则:
- 返回一个可写的 key/value 载体(普通对象、headers 对象、metadata 容器等);
- 若返回
undefined,组件回退到自身的默认载体。
从源码看,Koa 组件在 packages/web-koa/src/framework.ts 中正是先调用 traceExtractor({ ctx, request: ctx.request, response: ctx.response }),未配置时默认以 ctx.headers 作为请求载体、以 ctx.response.res 作为响应载体;gRPC Provider 侧(packages/grpc/src/provider/framework.ts)则默认以 call.metadata?.getMap?.() ?? {} 作为入口载体。
默认映射(当前实现)
入口优先(extractor,读取):默认情况下 Midway 使用 OpenTelemetry 全局 Propagator,未自定义时通常为 W3C,涉及三个字段:
traceparenttracestatebaggage
实际读取时,即从各协议载体中读取同名 key:
| 组件 | 读取位置 | 默认 key |
|---|---|---|
web-koa |
ctx.headers |
traceparent / tracestate / baggage |
web-express |
req.headers |
traceparent / tracestate / baggage |
ws |
request.headers |
traceparent / tracestate / baggage |
socketio |
socket.handshake.headers |
traceparent / tracestate / baggage |
grpc provider |
call.metadata.getMap() |
traceparent / tracestate / baggage(metadata key) |
kafka consumer |
payload.message.headers |
traceparent / tracestate / baggage(消息头 key) |
mqtt consumer |
packet.properties.userProperties |
traceparent / tracestate / baggage(userProperties key) |
rabbitmq consumer |
message.properties.headers |
traceparent / tracestate / baggage(AMQP 头 key) |
bull/bullmq consumer |
job.data.__midwayTraceCarrier |
traceparent / tracestate / baggage(内部载体 key) |
cron/commander/faas/one-shot/piscina/mcp |
内部默认载体 | 通常无上游协议头;若载体存在则读取 traceparent / tracestate / baggage |
然后是出口(injector,写入):
| 组件 | 写入位置 |
|---|---|
web-koa |
ctx.response |
web-express |
res |
ws |
事件 payload 对象 |
socketio |
事件 payload 对象 |
grpc consumer |
clientOptions.metadata(默认 new Metadata()) |
kafka producer |
message.headers |
mqtt producer |
publishOptions.properties.userProperties |
rabbitmq producer |
options.headers |
bull/bullmq producer |
jobData.__midwayTraceCarrier |
axios |
requestConfig.headers |
redis/cache-manager/oss/cos/etcd/consul/tablestore |
默认 {}(可用 injector 覆盖) |
组件配置示例
// src/config/config.default.ts
export default {
koa: {
tracing: {
extractor: ({ request }) => (request as any)?.headers || {},
injector: ({ response }) => response as any,
},
},
grpc: {
tracing: {
extractor: ({ request }) =>
(request as any)?.metadata?.getMap?.() || {},
},
},
kafka: {
tracing: {
extractor: ({ request }) => (request as any)?.message?.headers || {},
injector: ({ request }) => (request as any)?.headers || {},
},
},
ws: {
tracing: {
extractor: ({ request }) => (request as any)?.headers || {},
injector: ({ request }) => (request as any)?.headers || {},
},
},
};
常见 HTTP 自定义场景
例如希望兼容上游自定义的 x-traceparent 请求头,可以在 extractor 中做归一化:
export default {
koa: {
tracing: {
extractor: ({ request }) => {
const headers = (request as any)?.headers || {};
if (headers['x-traceparent'] && !headers.traceparent) {
headers.traceparent = headers['x-traceparent'];
}
return headers;
},
injector: ({ response }) => response as any,
},
},
};
进阶:自定义 Propagator(可选)
Midway 使用 OpenTelemetry 全局 Propagator,因此你可以在 bootstrap.js 中替换为任意自定义 Propagator(例如 B3)。
安装:
$ npm install --save @opentelemetry/propagator-b3
{
"dependencies": {
"@opentelemetry/propagator-b3": "latest"
}
}
在 Midway 启动前设置:
const { Bootstrap } = require('@midwayjs/bootstrap');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { propagation } = require('@opentelemetry/api');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
const provider = new NodeTracerProvider();
provider.register();
propagation.setGlobalPropagator(new B3Propagator());
Bootstrap.configure().run();
注意事项:
- 这会改变
extractor/injector使用的默认 key(不再是traceparent/tracestate,而是 B3 的x-b3-traceid、x-b3-spanid、b3等); - 请确保上下游服务使用同一种 Propagator 格式,否则链路会断掉。
进阶:自定义 traceId
方案一(推荐):由上游传入标准 traceparent 头,Midway 会直接继承其中的 TraceId:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
方案二(高级):配置 OpenTelemetry SDK 的 IdGenerator(注意这是 OTel SDK 的配置项,不是 Midway 的配置项):
const crypto = require('crypto');
const { Bootstrap } = require('@midwayjs/bootstrap');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const {
SimpleSpanProcessor,
ConsoleSpanExporter,
} = require('@opentelemetry/sdk-trace-base');
class CustomIdGenerator {
generateTraceId() {
return crypto.randomBytes(16).toString('hex');
}
generateSpanId() {
return crypto.randomBytes(8).toString('hex');
}
}
const provider = new NodeTracerProvider({
idGenerator: new CustomIdGenerator(),
});
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();
Bootstrap.configure().run();
注意事项:
- 该方案只影响本服务内创建的 ID;
- 若上游已传入
traceparent,将优先沿用上游的 traceId。
从 @midwayjs/otel 迁移
迁移关系一览:
- 包:
@midwayjs/otel→@midwayjs/core - 配置:移除
imports: [otel] - 用法:
ctx.traceId保持不变 - 兼容性:
@Trace和MidwayTraceService继续可用
迁移检查清单:
- 移除依赖:
npm uninstall @midwayjs/otel - 移除配置:把
Configuration.imports中的otel删掉 - 更新导入
import { Trace } from '@midwayjs/otel'→import { Trace } from '@midwayjs/core'import { TraceService } from '@midwayjs/otel'→import { MidwayTraceService } from '@midwayjs/core'
进一步阅读
- 想深入了解 Span、Propagator、Exporter 等底层标准,可参阅 OpenTelemetry 官方文档;
- 在仓库中可继续阅读 MidwayTraceService 完整实现、Tracing 配置类型定义、
@Trace装饰器实现; - 想看各协议组件如何接入,可对照 Koa 框架入口埋点、gRPC Provider 入口埋点,以及
packages/kafka、packages/mqtt、packages/rabbitmq、packages/redis、packages/bull等组件源码中的runWithEntrySpan/runWithExitSpan调用; - 各组件对应的 Trace 测试用例(如
packages/core/test/trace.test.ts、packages/web-koa/test、packages/grpc/test/index.test.ts)可用于验证默认行为与自定义配置的实际效果。