17370845950

本教程深入探讨了在 opentelemetry java 中如何通过上下文传播机制，而非直接通过 span id 获取 span 对象，来实现父子 span 的正确关联。文章详细介绍了 `textmappropagator` 的 `inject` 和 `extract` 方法，并提供了实践代码示例，旨在帮助开发者在分布式系统中无缝传递追踪上下文，从而构建完整且准确的追踪链。

在分布式追踪中，正确关联父子 Span 是构建完整调用链的关键。开发者有时会遇到这样的场景：在一个方法中只接收到父 Span 的 ID，并希望以此来设置当前 Span 的父级。然而，OpenTelemetry 的设计哲学并非通过 Span ID 直接获取一个活跃的 Span 对象。相反，它依赖于“上下文传播”（Context Propagation）机制来传递追踪信息，包括 Trace ID 和 Span ID，从而在分布式服务或异步操作之间建立关联。

OpenTelemetry 上下文传播机制

OpenTelemetry 的核心概念之一是 Context（上下文）。Context 是一个不可变的、线程本地（ThreadLocal）的存储，可以携带各种值，其中就包括当前活跃的 Span。当一个操作需要与另一个操作关联时，OpenTelemetry 不会传递 Span 对象本身，而是传递包含 SpanContext（其中包含 Trace ID 和 Span ID）的 Context。

上下文传播主要通过 TextMapPropagator 接口实现，它定义了如何将 Context 信息注入（inject）到某个载体（如 HTTP 请求头、消息队列消息头）中，以及如何从载体中提取（extract）Context 信息。

实现跨进程上下文传播：inject 与 extract

为了在分布式系统中正确关联父子 Span，我们需要在发送方（调用方）将当前的追踪上下文注入到传输载体中，并在接收方（被调用方）从载体中提取上下文，然后基于此上下文创建新的 Span。

1. 发送方：注入上下文 (inject)

在服务 A 中，当需要调用服务 B 时，服务 A 会创建一个 Span，并将该 Span 的上下文信息注入到即将发送给服务 B 的请求中。

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.propagation.TextMapPropagator;
import io.opentelemetry.context.propagation.TextMapSetter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import io.opentelemetry.sdk.trace.export.SystemOutSpanExporter;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class OtelSpanPropagationTutorial {

    // 1. 初始化 OpenTelemetry SDK (在实际应用中通常在启动时完成)
    private static final SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
            .addSpanProcessor(SimpleSpanProcessor.create(SystemOutSpanExporter.create())) // 导出到控制台
            .build();
    private static final OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .buildAndRegisterGlobal(); // 注册为全局实例

    private static final Tracer tracer = openTelemetry.getTracer("my-tutorial-app", "1.0.0");
    private static final TextMapPropagator propagator = openTelemetry.getPropagators().getTextMapPropagator();

    // 模拟一个用于携带上下文信息的载体，例如 HTTP 请求头
    static class MyCarrier {
        private final Map headers = new HashMap<>();

        public void setHeader(String key, String value) {
            headers.put(key, value);
        }

        public String getHeader(String key) {
            return headers.get(key);
        }

        public Map getHeaders() {
            return Collections.unmodifiableMap(headers);
        }
    }

    // 定义如何将上下文注入到载体中
    static final TextMapSetter setter =