🎯 今日核心问题

  1. 用户说「Agent 卡住了」,你在日志里能立刻定位到它卡在哪一步、卡在哪个工具、那一刻的 Prompt 长什么样吗?
  2. 一次 ReAct 循环会产生多少次模型调用、多少次工具调用,这些调用的父子关系怎么还原成一棵树?
  3. traceId 从网关进来,怎么保证它一路穿过 LLM SDK、HTTP 客户端、线程池、异步回调,不出现在某一段「断链」?

📖 精读提纲

【一】先画清楚:一次 Agent 调用到底经了什么

把「一次请求」当成黑盒是没法排查的。真实的一次 POST /api/agent/chat 会产生这样一条链路:网关鉴权 → 控制器 → 会话装配(读历史、裁剪上下文)→ ReAct 循环 N 轮 { 组装 Prompt → 模型调用(含重试/降级)→ 解析 tool_calls → 工具执行(含下游 HTTP)→ 结果回填 } → 幻觉校验 → 流式输出 → 落库。一个典型售后工单任务,ReAct 跑 3 轮、每轮 1 次模型调用、共 2 次工具调用,整条链路约有 14 个可观测节点。

关键认知:模型调用是唯一同时具备「高延迟、高成本、高失败率」的节点,它必须被单独埋点;工具调用是唯一会「产生副作用」的节点,它必须被单独审计;其余节点用 span 串起来就够。不要给每个方法都加 @Timed,指标会爆炸且没人看。

【二】三件套分工:Trace 查个案,Metric 看趋势,Log 看细节

三者不是冗余,是三种不同的查询方式。Trace 回答「这一次为什么慢」,数据量级是单次请求,保留 7 天且必须可拎出具体 traceId;Metric 回答「整体是不是变差了」,只存聚合值(count/sum/bucket),保留 13 个月,维度必须低基数;Log 回答「那一步到底传了什么」,是唯一能存原文的地方,但代价最高。

排查时的正确顺序是反过来的:告警(Metric)→ 找到异常 traceId(Trace)→ 翻那一段日志(Log)。很多团队做反了,一上来就 grep 日志,几百万行里捞一条,把排查做成了体力活。

【三】traceId 断链的四个高发点

Spring Boot 里 traceId 走 MDC,MDC 是 ThreadLocal,所以只要跨线程就断:① @Async 与线程池——必须包一层 TaskDecorator 把 MDC 带过去;② CompletableFuture 的回调——同一个问题,换 executor 参数即可;③ 响应式流——ThreadLocal 完全无效,要用 Reactor 的 contextWrite;④ 流式输出(SSE)——控制器返回后线程就换了,finally 里清 MDC 的时机要挪到 SseEmitter.onCompletion。

第四个最容易漏。Spring Boot 3 之后可以直接引入 micrometer-tracing-bridge-otel + zipkin-reporter,用 observation 自动埋点,RestTemplate/WebClient/Feign 的 W3C traceparent 头会自动传播。但如果你的 LLM SDK 是自研的 HTTP 调用,就得手动把 traceId 塞进 header 和 MDC。

【四】常见误区

💻 代码示例

用 Observation 手工包一层 ReAct 轮次,让每一轮成为独立 span,并把 step、轮次、模型名挂到标签上:

@Component
@RequiredArgsConstructor
public class TracedAgentLoop {

    private final ObservationRegistry registry;
    private final ChatClient chatClient;
    private final ToolRegistry tools;

    public AgentTrace run(AgentTrace trace) {
        return Observation.createNotStarted("agent.loop", registry)
                .lowCardinalityKeyValue("agent.name", trace.agentName())
                .highCardinalityKeyValue("agent.sessionId", trace.sessionId())
                .observe(() -> {
                    for (int step = 1; step <= trace.maxSteps(); step++) {
                        AgentTrace.Step s = doStep(trace, step);
                        trace = trace.append(s);
                        if (s.finished()) break;
                    }
                    return trace;
                });
    }

    private AgentTrace.Step doStep(AgentTrace trace, int step) {
        return Observation.createNotStarted("agent.step", registry)
                .lowCardinalityKeyValue("agent.step", String.valueOf(step))
                .observe(() -> {
                    ChatResponse resp = Observation
                            .createNotStarted("gen_ai.chat", registry)
                            .lowCardinalityKeyValue("gen_ai.request.model", trace.model())
                            .observe(() -> chatClient.call(trace.promptFor(step)));
                    if (resp.toolCalls().isEmpty()) {
                        return AgentTrace.Step.finalAnswer(step, resp.content());
                    }
                    String obs = Observation
                            .createNotStarted("agent.tool", registry)
                            .lowCardinalityKeyValue("tool.name", resp.toolCalls().get(0).name())
                            .observe(() -> tools.invoke(resp.toolCalls().get(0)));
                    return AgentTrace.Step.toolResult(step, obs);
                });
    }
}

线程池跨线程保 MDC(@Async 与工具并行执行都要用这个):

@Configuration
public class AsyncTraceConfig implements AsyncConfigurer {

    @Bean("agentExecutor")
    public ThreadPoolTaskExecutor agentExecutor() {
        ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor();
        ex.setCorePoolSize(8);
        ex.setMaxPoolSize(32);
        ex.setQueueCapacity(200);
        ex.setThreadNamePrefix("agent-");
        ex.setTaskDecorator(runnable -> {
            Map<String, String> ctx = MDC.getCopyOfContextMap();
            return () -> {
                if (ctx != null) MDC.setContextMap(ctx);
                try { runnable.run(); } finally { MDC.clear(); }
            };
        });
        return ex;
    }

    @Override
    public Executor getAsyncExecutor() { return agentExecutor(); }
}

给每个请求生成 traceId 并放进 MDC 与响应头,方便用户报障时直接报这串号:

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                    FilterChain chain) throws ServletException, IOException {
        String traceId = Optional.ofNullable(req.getHeader("X-Trace-Id"))
                .orElseGet(() -> UUID.randomUUID().toString().replace("-", ""));
        MDC.put("traceId", traceId);
        res.setHeader("X-Trace-Id", traceId);
        try {
            chain.doFilter(req, res);
        } finally {
            MDC.remove("traceId");
        }
    }
}

application.yml 里把 traceId 打进日志格式,之后任何一行日志都能反查整条链:

logging:
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level [%X{traceId:-}] [%X{step:-}] %logger{36} - %msg%n"

management:
  tracing:
    sampling:
      probability: 0.1
  zipkin:
    tracing:
      endpoint: http://zipkin:9411/api/v2/spans

✏️ 今日动手

给 W3 的工单 Agent 加三处埋点:① TraceIdFilter 落 MDC 并写响应头;② ReAct 每一轮包 agent.step span,标签带 step 与 tool.name;③ 线程池加 TaskDecorator。然后用 ab -n 200 -c 10 压一遍,在 Zipkin 里挑一张最慢的链路图,数一数它包含几个 span、最慢的那个 span 叫什么名字——如果最慢的不是 gen_ai.chat,说明你的瓶颈在工具或数据库,优化方向要改。

🔖 明日预告

trace 只能告诉你「这一次怎么了」,要回答「这个版本是不是更差了」,需要四个基准指标。明天定义成功率、平均步数、P95 延迟、单次成本,并给出它们的正确算法与分母——很多团队的口径错误,导致指标是好是坏看不出来。