OpenTelemetryJava：分布式Span上下文传播详解

本篇文章主要是结合我之前面试的各种经历和实战开发中遇到的问题解决经验整理的，希望这篇《OpenTelemetry Java：上下文传播构建分布式 Span》对你有很大帮助！欢迎收藏，分享给更多的需要的朋友学习~

本文详细阐述了在 OpenTelemetry Java 中如何基于 Span ID 实现分布式追踪的上下文传播。重点介绍了 OpenTelemetry 不直接通过 Span ID 获取 Span 对象的设计理念，而是通过注入（inject）和提取（extract）操作，将追踪上下文（包括父 Span ID 和 Trace ID）在服务间传递，从而正确建立父子 Span 关系，确保分布式系统中追踪链的完整性。

在分布式系统中，服务间的调用链路追踪是实现可观测性的关键。OpenTelemetry 提供了一套强大的 API 和 SDK 来实现这一目标。开发者在使用 OpenTelemetry Java 进行追踪时，有时会遇到一个常见问题：如何在一个服务中，仅凭父 Span 的 ID 来“获取”或“引用”该父 Span，以便为当前操作设置正确的父子关系？

OpenTelemetry 的设计哲学是，Span 对象是特定执行上下文的瞬时表示。它不提供一个全局注册表或方法，允许用户通过 Span ID 直接检索一个 Span 对象。这是因为 Span 的生命周期通常与它所代表的操作绑定，并且在操作完成后即结束。当涉及到跨进程或跨服务边界的追踪时，OpenTelemetry 依赖于上下文传播（Context Propagation）机制来传递追踪信息，而非直接传递 Span 对象本身。

核心概念：上下文传播 (Context Propagation)

上下文传播是 OpenTelemetry 中处理分布式追踪父子关系的核心机制。它允许追踪上下文（SpanContext，其中包含 Trace ID 和 Span ID）在不同的服务或进程之间传递。这个过程通常分为两个主要步骤：

1. 注入 (Inject)：在调用方服务中，将当前 Span 的 SpanContext 序列化并注入到一个传输载体（如 HTTP 请求头、消息队列的元数据）中。
2. 提取 (Extract)：在被调用方服务中，从接收到的传输载体中反序列化出 SpanContext，并基于此上下文创建新的子 Span。

通过这种方式，即使父 Span 对象在调用方已经结束，其关键的追踪信息（Trace ID 和 Span ID）也能被传递到下游服务，从而在下游服务中正确地建立起与上游服务的父子关系，形成完整的分布式追踪链。

OpenTelemetry Java 中的上下文传播实现

OpenTelemetry Java SDK 提供了 TextMapPropagator 接口来处理上下文的注入和提取。W3C Trace Context 是推荐的跨服务追踪上下文传播标准，OpenTelemetry 默认支持并推荐使用 W3CTraceContextPropagator。

1. 注入（Injection）：在调用方服务中传递上下文

在调用方服务中，您需要获取当前活跃的 Span 的上下文，并将其注入到即将发送的请求中。

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.Scope;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.TextMapSetter;
import java.util.HashMap;
import java.util.Map;

public class CallerService {

    private final Tracer tracer;
    private final OpenTelemetry openTelemetry;

    public CallerService(OpenTelemetry openTelemetry) {
        this.openTelemetry = openTelemetry;
        this.tracer = openTelemetry.getTracer("my-caller-service");
    }

    /**
     * 模拟一个远程调用，并将当前 Span 的上下文注入到传输载体中。
     * @return 包含追踪上下文的 Map，模拟 HTTP Headers。
     */
    public Map<String, String> makeRemoteCall() {
        Span parentSpan = tracer.spanBuilder("parentSpanInCaller")
            .startSpan();
        Map<String, String> carrier = new HashMap<>(); // 模拟 HTTP Headers 或消息队列元数据

        try (Scope scope = parentSpan.makeCurrent()) {
            // 获取当前上下文，并使用 W3CTraceContextPropagator 将其注入到 carrier 中
            W3CTraceContextPropagator.getInstance().inject(
                Context.current(), // 获取当前活跃的 Span 所在的上下文
                carrier,           // 传输载体，例如一个 Map 来模拟 HTTP Headers
                new TextMapSetter<Map<String, String>>() {
                    @Override
                    public void set(Map<String, String> carrier, String key, String value) {
                        carrier.put(key, value);
                    }
                });
            System.out.println("调用方 Span ID: " + parentSpan.getSpanContext().getSpanId());
            System.out.println("注入的追踪上下文: " + carrier);
        } finally {
            parentSpan.end();
        }
        return carrier;
    }
}

在上述代码中：

• 我们创建了一个名为 parentSpanInCaller 的 Span，并将其设置为当前活跃 Span。
• W3CTraceContextPropagator.getInstance().inject() 方法负责从 Context.current() 中提取 SpanContext 信息，并将其写入到 carrier（这里是一个 Map）中。TextMapSetter 接口定义了如何将键值对写入到载体中。
• carrier 随后会被发送到被调用方服务。

2. 提取（Extraction）：在被调用方服务中重建上下文

在被调用方服务中，您需要从接收到的请求中提取追踪上下文，并用它来作为新创建 Span 的父级。

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.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.TextMapGetter;
import java.util.Collections;
import java.util.Map;

public class CalleeService {

    private final Tracer tracer;
    private final OpenTelemetry openTelemetry;

    public CalleeService(OpenTelemetry openTelemetry) {
        this.openTelemetry = openTelemetry;
        this.tracer = openTelemetry.getTracer("my-callee-service");
    }

    /**
     * 模拟处理远程调用，从传输载体中提取上下文，并创建子 Span。
     * @param carrier 包含追踪上下文的 Map，模拟 HTTP Headers。
     */
    public void processRemoteCall(Map<String, String> carrier) {
        // 从 carrier 中提取追踪上下文
        Context extractedContext = W3CTraceContextPropagator.getInstance().extract(
            Context.current(), // 默认上下文，如果 carrier 中没有追踪信息，则使用此上下文
            carrier,           // 传输载体
            new TextMapGetter<Map<String, String>>() {
                @Override
                public Iterable<String> keys(Map<String, String> carrier) {
                    return carrier.keySet();
                }

                @Override
                public String get(Map<String, String> carrier, String key) {
                    return carrier.get(key);
                }
            });

        // 使用提取到的上下文作为新 Span 的父级
        Span childSpan = tracer.spanBuilder("childSpanInCallee")
            .setParent(extractedContext) // 将提取到的上下文设置为父级
            .startSpan();

        try {
            System.out.println("被调用方 Span ID: " + childSpan.getSpanContext().getSpanId());
            System.out.println("被调用方父 Span ID: " + childSpan.getParentSpanContext().getSpanId());
            // 模拟一些工作
            Thread.sleep(100);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        } finally {
            childSpan.end();
        }
    }
}

在上述代码中：

• W3CTraceContextPropagator.getInstance().extract() 方法从 carrier 中读取追踪上下文信息，并返回一个 Context 对象。TextMapGetter 接口定义了如何从载体中读取键值对。
• 这个 extractedContext 对象包含了上游服务 Span 的 SpanContext。
• 通过 tracer.spanBuilder("childSpanInCallee").setParent(extractedContext).startSpan()，我们创建了一个新的 Span，并明确指定其父级为 extractedContext 中携带的 Span。这样就成功建立了跨服务的父子关系。

完整的端到端示例

为了演示上述过程，我们需要一个主程序来初始化 OpenTelemetry SDK，并协调调用方和被调用方服务。

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.ConsoleSpanExporter;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.semconv.ResourceAttributes;

import java.util.Map;

public class Main {
    public static void main(String[] args) {
        // 1. 配置 OpenTelemetry SDK
        // 定义服务资源，例如服务名称
        Resource serviceResource = Resource.getDefault()
            .toBuilder()
            .put(ResourceAttributes.SERVICE_NAME, "my-distributed-app")
            .build();

        // 配置 TracerProvider，使用 ConsoleSpanExporter 将 Span 输出到控制台
        // 并设置采样器为始终采样
        SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
            .addSpanProcessor(SimpleSpanProcessor.create(ConsoleSpanExporter.create()))
            .setResource(serviceResource)
            .setSampler(Sampler.alwaysOn())
            .build();

        // 构建并注册全局的 OpenTelemetry 实例
        OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            // OpenTelemetry SDK 会自动注册 W3CTraceContextPropagator 作为默认的传播器
            // .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance())) // 显式设置传播器
            .buildAndRegisterGlobal();

        // 2. 初始化调用方和被调用方服务
        CallerService caller = new CallerService(openTelemetry);
        CalleeService callee = new CalleeService(openTelemetry);

        // 3. 模拟一次分布式调用
        System.out.println("--- 模拟远程调用开始 ---");
        Map<String, String> propagatedContext = caller.makeRemoteCall(); // 调用方注入上下文
        callee.processRemoteCall(propagatedContext); // 被调用方提取上下文并创建子 Span
        System.out.println("--- 远程调用模拟结束 ---");

        // 4. 关闭 TracerProvider 以确保所有 Span 都被导出
        tracerProvider.shutdown();
    }
}

运行此 Main 类，您将在控制台看到类似以下的输出（具体 Span ID 和 Trace ID 会有所不同）：

--- 模拟远程调用开始 ---
调用方 Span ID: 6b3c...
注入的追踪上下文: {traceparent=00-d8b4...-6b3c...-01}
被调用方 Span ID: 7a8b...
被调用方父 Span ID: 6b3c...
--- 远程调用模拟结束 ---

并且，ConsoleSpanExporter 会将完整的 Span 数据打印出来，显示 childSpanInCallee 的 parentSpanId 正是 parentSpanInCaller 的 spanId，证明父子关系已成功建立。

注意事项与最佳实践

1. 理解 SpanContext 与 Span 对象的区别

以上就是《OpenTelemetryJava：分布式Span上下文传播详解》的详细内容，更多关于的资料请关注golang学习网公众号！