多阶段引导的单页应用中OpenTelemetry自动链路追踪关联晚创建根Span的方案咨询

我完全理解你遇到的这个头疼问题——在多阶段加载的SPA里，OpenTelemetry的自动链路追踪总是赶在根Span创建前就启动了，导致后续的请求都没法关联到正确的父Span，最后拆成了好几个独立的Trace。结合你的场景，我分享几个经过实践验证的方案，应该能帮你搞定这个问题：

方案1：延迟自动Instrumentation的激活时机 #

既然自动instrumentation启动太早，那不如等根Span创建好之后再注册它们？你可以把Telemetry初始化拆成两步：

第一步，在telemetry-init-early.ts里只初始化TracerProvider，先不注册自动instrumentations：

// telemetry-init-early.ts
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import { ZoneContextManager } from "@opentelemetry/context-zone";

// 全局导出provider，供后续使用
export const provider = new WebTracerProvider();
provider.register({ contextManager: new ZoneContextManager() });

// 这里先不注册任何instrumentations

第二步，在main-app-init.ts里，等创建好根navigationSpan并设置好上下文后，再注册自动instrumentations：

// main-app-init.ts
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { getWebAutoInstrumentations } from "@opentelemetry/auto-instrumentations-web";
import { provider } from "./telemetry-init-early";
import { context, trace } from "@opentelemetry/api";

function initializeApplication() {
  const tracer = trace.getTracer("my-app-tracer");
  // 创建根Span
  const navigationSpan = tracer.startSpan("navigation");
  // 将根Span注入当前上下文
  const rootCtx = trace.setSpan(context.active(), navigationSpan);

  // 在根上下文环境中注册自动instrumentations
  context.with(rootCtx, () => {
    registerInstrumentations({
      tracerProvider: provider,
      instrumentations: [getWebAutoInstrumentations()]
    });
  });

  // 手动创建的子Span正常关联
  const childSpan = tracer.startSpan("my-custom-span", undefined, rootCtx);
  childSpan.end();

  // 记得在应用卸载时结束根Span
  window.addEventListener('beforeunload', () => {
    navigationSpan.end();
  });
}

initializeApplication();

这个方案的优点是简单直接，确保所有自动生成的Span都能拿到正确的父上下文。唯一需要注意的是：如果在main-app-init加载前有依赖加载的fetch/XHR请求，这些请求会被漏掉追踪，你需要评估是否可以接受这个情况。

方案2：自定义ContextManager实现动态上下文查找 #

你已经尝试了手动维护上下文栈，那可以基于这个思路，自定义一个ContextManager，让它优先从你的手动栈中获取活跃Span，回退到Zone的默认上下文。这样不管自动instrumentation什么时候启动，都会动态查找当前的根Span：

首先实现自定义ContextManager：

// MyCustomContextManager.ts
import { ContextManager, Context, trace } from "@opentelemetry/api";
import { ZoneContextManager } from "@opentelemetry/context-zone";
import { manualContextStack } from "./MyManualContext";

export class CustomContextManager implements ContextManager {
  // 基于ZoneContextManager做封装
  private _zoneManager = new ZoneContextManager();

  active(): Context {
    // 先检查手动栈有没有活跃的根Span
    const activeRootSpan = manualContextStack.peek();
    if (activeRootSpan) {
      // 将根Span注入到Zone的当前上下文中
      return trace.setSpan(this._zoneManager.active(), activeRootSpan);
    }
    // 没有根Span时，使用Zone的默认上下文
    return this._zoneManager.active();
  }

  // 其他方法直接委托给ZoneContextManager
  with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
    context: Context,
    fn: F,
    thisArg?: ThisParameterType<F>,
    ...args: A
  ): ReturnType<F> {
    return this._zoneManager.with(context, fn, thisArg, ...args);
  }

  enable(): void {
    this._zoneManager.enable();
  }

  disable(): void {
    this._zoneManager.disable();
  }
}

然后在telemetry-init-early.ts里使用这个自定义的ContextManager：

// telemetry-init-early.ts
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { getWebAutoInstrumentations } from "@opentelemetry/auto-instrumentations-web";
import { CustomContextManager } from "./MyCustomContextManager";

const provider = new WebTracerProvider();
// 替换成自定义的ContextManager
provider.register({ contextManager: new CustomContextManager() });

// 正常注册自动instrumentations
registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [getWebAutoInstrumentations()]
});

这样，当自动instrumentations需要获取当前上下文时，会先检查你的manualContextStack。只要你在创建navigationSpan后push进去，后续所有自动生成的Span都会自动关联它作为父Span。这个方案不会漏掉任何请求的追踪，同时能让后续请求正确关联根Span，是比较均衡的选择。

方案3：给自动Instrumentation注入自定义父Span逻辑 #

有些自动instrumentations支持自定义钩子，你可以针对每个instrumentation（比如fetch、XHR）添加钩子，在创建Span时手动设置父Span：

以FetchInstrumentation为例：

// telemetry-init-early.ts
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import { ZoneContextManager } from "@opentelemetry/context-zone";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
import { XMLHttpRequestInstrumentation } from "@opentelemetry/instrumentation-xml-http-request";
import { manualContextStack } from "./MyManualContext";
import { context, trace } from "@opentelemetry/api";

const provider = new WebTracerProvider();
provider.register({ contextManager: new ZoneContextManager() });

registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [
    new FetchInstrumentation({
      // 在Span创建后，手动关联父Span
      applyCustomAttributesOnSpan: (span) => {
        const parentSpan = manualContextStack.peek();
        if (parentSpan) {
          const parentCtx = trace.setSpan(context.active(), parentSpan);
          // 将父Span的上下文关联到当前Span
          span.setSpanContext(trace.getSpan(parentCtx)?.spanContext() || span.spanContext());
        }
      }
    }),
    // XHR instrumentation也可以类似配置
    new XMLHttpRequestInstrumentation({
      applyCustomAttributesOnSpan: (span) => {
        const parentSpan = manualContextStack.peek();
        if (parentSpan) {
          const parentCtx = trace.setSpan(context.active(), parentSpan);
          span.setSpanContext(trace.getSpan(parentCtx)?.spanContext() || span.spanContext());
        }
      }
    })
  ]
});

这个方案需要逐个配置每个instrumentation，相对繁琐，但灵活性很高，适合需要精细控制某些请求追踪规则的场景。

总结 #

如果你的应用在根Span创建前没有需要追踪的请求，优先选方案1；如果需要追踪所有请求，同时关联后续的根Span，选方案2；如果需要针对特定instrumentation做定制，选方案3。

内容来源于stack exchange