为 Java 应用传递 GenAI 业务属性

方案架构

方案由两条互补的染色路径组成，共同覆盖入口 Span 与其之后的所有 Span：

• 入口 Span 直接染色：由业务代码调用 Span.current().setAttribute(...)，把 gen_ai.user.id、gen_ai.session.id 等属性写入探针已经创建的当前 HTTP/RPC 入口 Span。入口 Span 在 Controller 方法执行前就已经启动，Baggage 处理只在 Span 启动时生效，不会追溯修改已启动的入口 Span，因此必须显式 setAttribute。

• 后续 Span 通过 Baggage 染色：把相同属性写入当前 Context 的 Baggage，并为 Java 探针配置待采集 Baggage Key。此后创建的每一个子 Span 在启动时都会读取 Baggage，并写入同名 Span 属性。

  两条路径合力后，链路层级保持原样、不额外增加 GenAI 入口 Span，同时让 GenAI、HTTP、RPC、数据库等后续 Span 都携带业务属性。

前提条件

开始前请确认以下条件全部满足。跨服务场景涉及下游应用与中间链路，尤其需要按最后一行整体确认。

步骤一：配置待采集 Baggage Key

在控制台进入目标应用，选择应用配置 > 自定义配置，在探针采集配置区域找到待采集 baggage 列表，填入需要染色的 Key，多个 Key 使用英文逗号分隔：

gen_ai.user.id,gen_ai.session.id

也可以通过 JVM 启动参数配置：

-Dapsara.apm.trace.capture_baggage_keys=gen_ai.user.id,gen_ai.session.id

探针只复制明确配置的 Key，Key 大小写敏感。配置项对应的内部键为 apsara.apm.trace.capture_baggage_keys。

步骤二：在请求入口设置属性和 Baggage

业务代码需要在活动入口 Span 已存在、后续子 Span 尚未创建的窗口内完成设置。以下示例演示一个 REST API 的完整写法：

import io.opentelemetry.api.baggage.Baggage;
import io.opentelemetry.api.baggage.BaggageBuilder;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import java.util.HashMap;
import java.util.Map;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GenerateController {

  private static final String USER_ID = "gen_ai.user.id";
  private static final String SESSION_ID = "gen_ai.session.id";

  @PostMapping("/api/v1/generate")
  public Map<String, String> generate(@RequestBody Map<String, String> request) {
    String userId = request.get("userId");
    String sessionId = request.get("sessionId");
    String prompt = request.get("prompt");

    Span currentSpan = Span.current();
    BaggageBuilder baggageBuilder = Baggage.current().toBuilder();

    putAttributeAndBaggage(currentSpan, baggageBuilder, USER_ID, userId);
    putAttributeAndBaggage(currentSpan, baggageBuilder, SESSION_ID, sessionId);

    Context baggageContext =
        baggageBuilder.build().storeInContext(Context.current());

    try (Scope ignored = baggageContext.makeCurrent()) {
      // 在此作用域中调用 LangGraph4j、LangChain4j 或其他业务逻辑。
      // 后续创建的 GenAI、HTTP、RPC、数据库等 Span 会继承 Baggage。
      String result = doBusiness(prompt);

      Map<String, String> response = new HashMap<>();
      response.put("result", result);
      return response;
    }
  }

  private static void putAttributeAndBaggage(
      Span span, BaggageBuilder builder, String key, String value) {
    if (value == null || value.trim().isEmpty()) {
      return;
    }
    span.setAttribute(key, value);
    builder.put(key, value);
  }

  private String doBusiness(String prompt) {
    // 替换为实际的模型或 Agent 调用。
    return "response for: " + prompt;
  }
}

使用以下命令发起测试请求：

curl -X POST http://localhost:8080/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-001","sessionId":"session-001","prompt":"什么是 OpenTelemetry？"}'

步骤三：处理异步和跨服务调用

try (Scope ignored = baggageContext.makeCurrent()) {
  // 此处仍在请求线程中，Context.current() 包含 userId 和 sessionId。
  Context contextWithBaggage = Context.current();

  executor.execute(contextWithBaggage.wrap(() -> {
    // 任务实际在线程池工作线程中执行。
    // wrap 会在任务执行期间恢复提交任务时捕获的 Context。
    doAsyncBusiness();
  }));
}

executor.execute(() -> doAsyncBusiness());

预期效果

配置生效并产生新请求后：

• 当前 HTTP/RPC 入口 Span 包含 gen_ai.user.id、gen_ai.session.id 等属性。

• Scope 中创建的 GenAI、HTTP、RPC、数据库等子 Span 包含相同属性。

• 跨服务调用时，下游服务产生的新 Span 也包含配置的业务属性。

• 链路不会额外增加一层 GenAI Entry Span，原有父子关系保持不变。

验证方法

1. 使用固定测试值发起一次新请求，例如 gen_ai.user.id=test-user-001。

2. 在控制台按时间范围找到对应 Trace。

3. 检查 HTTP/RPC 入口 Span 是否包含该属性。

4. 检查入口之后创建的 GenAI、HTTP、RPC 或数据库 Span 是否包含该属性。

5. 若包含跨服务调用，继续检查下游应用 Span。

6. 使用该属性作为筛选条件，确认可以定位到完整调用链。

常见问题