Midway 框架级分布式链路追踪(Tracing)实战指南:基于 OpenTelemetry 的内建实现

原创2026-10-08 20:22:342,260 阅读
文章标签:后端微服务云原生

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,涉及三个字段:

  • traceparent
  • tracestate
  • baggage

实际读取时,即从各协议载体中读取同名 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 继续可用

迁移检查清单:

  1. 移除依赖:npm uninstall @midwayjs/otel
  2. 移除配置:把 Configuration.imports 中的 otel 删掉
  3. 更新导入
    • import { Trace } from '@midwayjs/otel' → import { Trace } from '@midwayjs/core'
    • import { TraceService } from '@midwayjs/otel' → import { MidwayTraceService } from '@midwayjs/core'

进一步阅读

登录后查看全文
midway