🎯 今日核心问题
- 用户说「Agent 卡住了」,你在日志里能立刻定位到它卡在哪一步、卡在哪个工具、那一刻的 Prompt 长什么样吗?
- 一次 ReAct 循环会产生多少次模型调用、多少次工具调用,这些调用的父子关系怎么还原成一棵树?
- 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。
【四】常见误区
- ❌ 用
userId或orderId当 traceId。一次会话有多次请求,一个用户有多次会话,粒度全错,还容易把用户 ID 泄露到第三方链路追踪系统里。 - ❌ 只记录模型调用的耗时,不记录
step序号。看到 P95 是 12 秒,但不知道是首轮慢(Prompt 太长)还是末轮慢(上下文膨胀)。 - ❌ trace 里塞完整 Prompt。单条 trace 几 MB,存储费比模型费还高,而且 Prompt 里通常有用户手机号。做法是 trace 只存 hash 与长度,原文落日志并对敏感字段脱敏。
- ❌ 采样率设 100% 还抱怨存储贵。生产按 10% 采样 + 「错误/慢请求全采」的尾部采样策略,成本降一个量级而排障能力几乎不降。
💻 代码示例
用 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 延迟、单次成本,并给出它们的正确算法与分母——很多团队的口径错误,导致指标是好是坏看不出来。