Spring Boot LLM Agent可观测性实践：从黑盒到思维链追踪

1. 从一次失败的排查说起：Agent答错问题，为何我们束手无策？

最近在调试一个基于大语言模型（LLM）的智能客服Agent时，遇到了一个典型问题：用户反馈回答错误，但当我试图复现和定位时，却像一拳打在了棉花上。我手头只有用户的几句模糊描述——“它说错了”、“答案不对”，至于Agent当时到底接收了什么输入、内部经过了哪些思考步骤、调用了哪个工具、最终基于什么逻辑输出了这个错误答案，我一无所知。日志里只有简单的“请求开始”、“请求结束”记录，中间的黑盒过程完全不可见。这让我意识到，对于现代AI应用，尤其是Agent这类具备自主决策和工具调用能力的复杂系统，传统的、粗粒度的日志监控已经彻底失效了。问题的核心不再是“服务是否崩溃”，而是“推理过程是否合理”。如果无法透视Agent内部的“思维链”，那么当它犯错时，开发者就变成了盲人摸象，排查效率极低，甚至无从下手。

这不仅仅是智能客服场景的困境。无论是自动化编程助手、数据分析Agent，还是游戏内的NPC，只要系统具备了基于LLM的复杂决策能力，都会面临同样的可观测性挑战。Agent的“错误”往往不是代码异常（Exception），而是逻辑谬误、事实错误或决策偏差，这些“软错误”隐藏在看似正常的程序执行流程中。因此，构建一套能够完整追踪Agent内部状态、决策路径和工具调用序列的“思维日志”体系，不再是锦上添花，而是保障其可靠性、可调试性的生死线。本文将结合Spring Boot这一广泛使用的后端框架，深入探讨如何为LLM Agent构建深度可观测性方案，让你在Agent“答错问题”时，能快速、精准地定位到根因。

2. 传统日志的“失明”：为何它无法应对Agent的复杂性

在单体应用或简单微服务时代，我们的日志系统主要关注几个维度：请求的输入输出、关键业务状态变更、系统异常和性能指标。我们通过日志级别（INFO, WARN, ERROR）来过滤信息，通过搜索关键字来定位问题。然而，这套体系在LLM Agent面前几乎完全失灵。我们需要先理解Agent工作流的特殊性，才能明白传统工具的不足。

一个典型的LLM Agent工作流，远不止一次简单的API调用。它可能包含以下阶段：

1. 用户输入解析与意图识别：Agent需要理解用户的自然语言指令。
2. 规划（Planning）：Agent决定需要执行哪些步骤来达成目标，例如“先搜索知识库，再调用计算工具”。
3. 工具调用（Tool Calling）：根据规划，顺序或并行地调用外部工具或API（如搜索引擎、数据库、代码执行器）。
4. 观察与反思（Observation & Reflection）：获取工具执行结果，并评估结果是否足够好，是否需要重试或调整策略。
5. 合成与输出（Synthesis & Output）：整合所有中间结果，生成最终的自然语言回复给用户。

在这个过程中，每一个环节都可能出错：意图识别偏差、规划逻辑有缺陷、工具调用参数错误、工具返回结果解析失败、合成时引入幻觉等。传统的“请求-响应”日志，只能记录这个漫长管道的起点和终点，中间丰富的、有价值的中间状态全部丢失了。

更具体地说，传统日志方案存在以下致命缺陷：

• 状态丢失：无法记录Agent在每一步的“思考”内容，即LLM的提示词（Prompt）和响应（Completion）。这是理解其决策逻辑的核心。
• 关联性断裂：一次用户对话可能触发多次LLM调用和工具调用。如果没有一个唯一的标识符（Trace ID）将这些离散的事件串联起来，我们根本无法重建完整的会话脉络。
• 缺乏结构化：LLM的输入输出、工具调用的参数和结果，本质上是半结构化或结构化的数据（JSON）。将其压缩成一行文本日志，不仅可读性差，也无法进行有效的查询和分析（例如，“找出所有调用了‘计算器’工具但输入参数非数字的请求”）。
• 维度单一：传统日志侧重于“是否出错”，而Agent调试更需要关注“为什么这样决策”。这需要记录决策时的上下文、被拒绝的备选方案、置信度分数等更丰富的维度。

因此，当用户报告“答错问题”时，如果你只有类似2024-05-27 INFO: Request to /chat completed in 1250ms这样的日志，那么排查根本无法开始。你需要的是能够回答以下问题的数据：

• 用户到底问了什么？（原始输入）
• Agent是如何理解这个问题的？（解析后的意图/指令）
• 它决定分几步走？每一步打算做什么？（规划步骤）
• 它调用了哪个工具？调用时的具体参数是什么？（工具调用详情）
• 工具返回了什么结果？这个结果正常吗？（工具观察）
• 它基于这些结果，最终“思考”出了什么答案？（LLM的完整响应）
• 整个过程的耗时分布如何？瓶颈在哪？（性能剖析）

没有这些信息，排查Agent的错误就如同侦探在没有监控录像、没有指纹证据的情况下破案，全靠猜测。

3. 构建Agent可观测性的三大支柱：Trace、Logs、Metrics

为了解决上述问题，我们需要引入现代可观测性（Observability）的理念，并将其适配到Agent场景。可观测性的三大支柱——追踪（Tracing）、日志（Logging）、指标（Metrics）——在这里有了新的内涵。

3.1 追踪（Tracing）：绘制Agent的“思维导图”

追踪的核心是记录一个请求在分布式系统中的调用链。对于Agent，我们需要记录的是其“思维链”。每一个用户会话（Session）或请求（Request）应该生成一个唯一的Trace ID。这个Trace ID将贯穿Agent执行的整个生命周期。

在这个Trace下，我们需要创建更细粒度的Span，来代表每一个有意义的执行单元：

• 一个总Span：代表整个Agent处理请求的过程。
• 子Span 1：输入解析与意图识别。属性应包含原始用户输入、解析后的结构化指令。
• 子Span 2：任务规划。属性应包含生成的计划步骤列表（如[“search_knowledge_base”, “calculate”]）。
• 子Span 3：工具调用search_knowledge_base。属性应包含搜索关键词、调用的API端点、请求参数。
• 子Span 4：工具调用calculate。属性应包含计算公式、参数。
• 子Span 5：结果合成与输出。属性应包含所有中间观察结果、LLM生成最终答案所用的提示词、以及最终回复。

每个Span都应记录开始时间、结束时间、状态（成功/失败）、以及关键的自定义属性。这样，当出现错误时，我们可以通过Trace ID快速检索到完整的可视化调用链，一眼就能看出是在“规划”阶段出了错，还是在某个“工具调用”阶段得到了异常结果。

实操建议：可以使用 OpenTelemetry 这样的开源标准来集成追踪。在Spring Boot应用中，你可以通过@WithSpan注解或手动创建Span的API，轻松地将Agent的各个组件接入追踪体系。Trace ID可以通过HTTP请求头（如X-Trace-Id）从前端传递过来，也可以在网关处生成。

3.2 日志（Logs）：从文本行到结构化事件

日志需要从简单的文本行升级为结构化的、包含丰富上下文的事件。每一条日志都应该是一个JSON对象，并且必须包含Trace ID和Span ID，以便与追踪数据关联。

对于Agent，关键的结构化日志事件包括：

• Agent启动：记录会话ID、用户ID、初始消息。
• LLM调用：这是最关键的日志之一。需要记录：

  { “timestamp”: “2024-05-27T10:00:00Z”, “level”: “INFO”, “traceId”: “abc123”, “spanId”: “def456”, “event”: “llm_invocation”, “component”: “planning_agent”, “details”: { “provider”: “OpenAI”, “model”: “gpt-4”, “prompt”: “{完整提示词}”, “response”: “{完整响应}”, “token_usage”: {“prompt”: 100, “completion”: 50}, “latency_ms”: 1200 } }

  注意：记录完整的Prompt和Response可能涉及隐私和成本（存储、Token计费）。在生产环境中，需要制定策略，例如只对错误请求或抽样记录完整内容，或对敏感信息进行脱敏。

• 工具调用：记录工具名称、输入参数、执行结果、耗时和状态。
• 决策点：记录Agent在多个选项间做出的选择及其理由（例如，为什么选择工具A而非工具B）。
• 错误与重试：记录任何异常、工具调用失败、以及系统的重试行为。

使用像ELK Stack（Elasticsearch, Logstash, Kibana）或Loki这样的日志聚合系统，可以方便地存储和查询这些结构化日志。你可以通过traceId=“abc123”轻松过滤出某次会话的所有相关日志。

3.3 指标（Metrics）：量化Agent的健康与性能

指标帮助我们宏观把握系统的状态。对于Agent，除了常规的QPS、延迟、错误率之外，还应关注一些领域特定指标：

• LLM相关：各模型的平均响应延迟、Token消耗速率（区分Prompt/Completion）、调用失败率、速率限制触发次数。
• 工具相关：各个工具的平均调用耗时、成功率、超时率。
• 会话相关：平均会话轮次、会话超时率、用户主动中断率。
• 质量相关：这是一个高级但至关重要的领域。可以定义一些启发式指标，例如“幻觉检测得分”（通过内部校验机制判断回答是否可能包含虚构内容）、“工具使用相关性得分”（工具调用是否与问题真正相关）。这些指标可以通过抽样评估或规则引擎来计算。

这些指标可以通过Micrometer集成到Spring Boot中，并暴露给Prometheus进行抓取，最终在Grafana中绘制成仪表盘。一个突然升高的工具失败率或LLM延迟，可能就是Agent集体“犯傻”的先行指标。

将这三大支柱的数据（Trace, Logs, Metrics）在同一个平台（如Grafana，它既能看指标仪表盘，也能通过Tempo查Trace，通过Loki查日志）上关联起来，就形成了强大的调试能力。例如，当仪表盘显示“计算器工具错误率飙升”时，你可以直接点击关联的Trace，查看错误的具体工具调用Span，再通过Trace ID跳转到对应的结构化日志，看到失败时的具体输入参数和错误信息，从而迅速定位是参数格式问题还是下游服务故障。

4. 在Spring Boot中落地：从配置到代码的实践

理论需要落地。下面我们以一个基于Spring Boot的简单LLM Agent服务为例，看看如何具体实现上述可观测性方案。假设我们使用LangChain4j作为Agent框架。

4.1 基础设施搭建：集成OpenTelemetry与日志框架

首先，在pom.xml中引入必要的依赖：

<!-- OpenTelemetry for Spring Boot --> <dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-spring-boot-starter</artifactId> <version>2.5.0</version> <!-- 使用最新稳定版 --> </dependency> <!-- Micrometer for Metrics --> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-core</artifactId> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> </dependency> <!-- 结构化日志，以Logback+Logstash编码器为例 --> <dependency> <groupId>net.logstash.logback</groupId> <artifactId>logstash-logback-encoder</artifactId> <version>7.4</version> </dependency>

在application.yml中配置OpenTelemetry导出器（这里以控制台和Jaeger为例）：

spring: application: name: llm-agent-service management: tracing: sampling: probability: 1.0 # 生产环境可调低采样率 endpoints: web: exposure: include: prometheus,health,info opentelemetry: traces: exporter: jaeger, logging logs: exporter: logging metrics: exporter: prometheus logging: pattern: level: “%5p [${spring.application.name},%X{traceId:-},%X{spanId:-}]” config: classpath:logback-spring.xml

配置logback-spring.xml以输出JSON格式的结构化日志：

<configuration> <appender name=“JSON” class=“ch.qos.logback.core.ConsoleAppender”> <encoder class=“net.logstash.logback.encoder.LogstashEncoder”> <includeContext>false</includeContext> <includeCallerData>false</includeCallerData> <fieldNames> <timestamp>timestamp</timestamp> <message>message</message> <level>level</level> <logger>logger</logger> <thread>thread</thread> <version>[ignore]</version> </fieldNames> <customFields>{“service”:“${spring.application.name}”}</customFields> </encoder> </appender> <root level=“INFO”> <appender-ref ref=“JSON”/> </root> </configuration>

4.2 核心代码：为Agent组件注入可观测性

现在，我们需要在关键的Agent处理逻辑中手动创建Span和记录结构化日志。

import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.Tracer; import io.opentelemetry.context.Scope; import org.springframework.stereotype.Service; import lombok.extern.slf4j.Slf4j; @Service @Slf4j public class ChatAgentService { private final Tracer tracer; // 通过依赖注入 private final PlanningAgent planningAgent; private final ToolExecutor toolExecutor; public ChatAgentService(Tracer tracer, PlanningAgent planningAgent, ToolExecutor toolExecutor) { this.tracer = tracer; this.planningAgent = planningAgent; this.toolExecutor = toolExecutor; } public AgentResponse process(UserRequest request) { // 1. 为整个处理过程创建一个根Span Span agentSpan = tracer.spanBuilder(“agent.process”) .setAttribute(“user.id”, request.getUserId()) .setAttribute(“session.id”, request.getSessionId()) .startSpan(); try (Scope scope = agentSpan.makeCurrent()) { // 自动将TraceId注入到MDC，方便日志记录 String traceId = Span.current().getSpanContext().getTraceId(); log.info(“Agent processing started”, “requestId”, request.getRequestId(), “input”, request.getQuery()); // 2. 意图识别与规划 Span Span planningSpan = tracer.spanBuilder(“agent.plan”) .setAttribute(“input.text”, request.getQuery()) .startSpan(); Plan plan; try (Scope planningScope = planningSpan.makeCurrent()) { plan = planningAgent.createPlan(request.getQuery()); // 记录关键的规划日志 log.info(“Planning completed”, “plan.steps”, plan.getSteps(), “llm.model”, plan.getModelUsed(), // 假设记录了使用的模型 “llm.prompt_snippet”, plan.getPrompt().substring(0, Math.min(100, plan.getPrompt().length())) // 记录提示词片段 ); } finally { planningSpan.end(); } // 3. 执行计划中的每个工具调用 List<Observation> observations = new ArrayList<>(); for (int i = 0; i < plan.getSteps().size(); i++) { Step step = plan.getSteps().get(i); Span toolSpan = tracer.spanBuilder(“tool.execute”) .setAttribute(“tool.name”, step.getToolName()) .setAttribute(“tool.parameters”, step.getParameters().toString()) .setAttribute(“step.index”, i) .startSpan(); Observation obs; try (Scope toolScope = toolSpan.makeCurrent()) { log.info(“Tool execution started”, “tool”, step.getToolName(), “params”, step.getParameters()); obs = toolExecutor.execute(step); // 记录工具执行结果（注意脱敏） log.info(“Tool execution completed”, “tool”, step.getToolName(), “success”, obs.isSuccess(), “result_snippet”, obs.getResult().substring(0, Math.min(200, obs.getResult().length())) ); } catch (Exception e) { toolSpan.recordException(e); toolSpan.setAttribute(“error”, true); log.error(“Tool execution failed”, “tool”, step.getToolName(), “error”, e.getMessage()); throw e; // 或进行错误处理 } finally { toolSpan.end(); } observations.add(obs); } // 4. 结果合成 Span Span synthesisSpan = tracer.spanBuilder(“agent.synthesize”) .setAttribute(“observations.count”, observations.size()) .startSpan(); String finalAnswer; try (Scope synthesisScope = synthesisSpan.makeCurrent()) { finalAnswer = synthesisAgent.synthesize(plan, observations); log.info(“Synthesis completed”, “answer_length”, finalAnswer.length()); } finally { synthesisSpan.end(); } log.info(“Agent processing finished successfully”, “total_latency_ms”, System.currentTimeMillis() - startTime); return new AgentResponse(finalAnswer, traceId); // 将TraceId返回给前端，便于用户反馈时提供 } catch (Exception e) { agentSpan.recordException(e); agentSpan.setAttribute(“error”, true); log.error(“Agent processing failed”, “error”, e.getMessage(), “request”, request); throw new AgentProcessingException(“Processing failed”, e); } finally { agentSpan.end(); } } }

关键点解析：

1. Span的嵌套：通过makeCurrent()方法，我们建立了Span之间的父子关系，最终在Jaeger或Zipkin中会呈现为树状调用链。
2. 日志关联：由于Trace上下文被设置为当前上下文，Logback的MDC（Mapped Diagnostic Context）会自动捕获traceId和spanId，这样每一条日志都会自动带上这些字段，无需手动添加。
3. 结构化日志：我们使用SLF4J的占位符语法（log.info(“message”, key1, value1, key2, value2)），配合Logstash编码器，最终输出为JSON。这比字符串拼接更清晰，且易于解析。
4. 信息脱敏：在记录LLM提示词和工具结果时，我们使用了substring进行截断。在生产环境中，你需要更完善的脱敏策略，例如对特定字段（如手机号、邮箱）进行正则匹配和替换。

4.3 前端与反馈闭环：让Trace ID发挥价值

可观测性数据不仅用于内部调试，还能改善用户体验和问题反馈流程。在返回给前端的响应中，可以包含本次会话的traceId。

{ “answer”: “根据查询，今天的天气是...”， “traceId”: “0af7651916cd43dd8448eb211c80319c”， “sessionId”: “sess_abc123” }

当用户觉得回答有误时，可以鼓励他们提供这个traceId（例如，在反馈按钮旁自动填充）。支持人员或开发者拿到这个ID后，可以直接在Grafana或Jaeger的搜索框中输入，瞬间拉取到这次对话的所有相关追踪、日志和指标，精准复现问题现场，极大提升了排查效率。

5. 高级调试与优化：利用可观测性数据驱动迭代

拥有了完整的可观测性数据后，我们的工作就从“救火”转向了“预防”和“优化”。以下是一些进阶场景：

5.1 慢查询与性能瓶颈分析在Grafana中，你可以轻松创建一个仪表盘，展示Agent处理各阶段的P95/P99延迟。如果你发现“工具调用”阶段的延迟异常高，可以进一步下钻：

• 查看是哪个具体工具慢（通过tool.name属性过滤）。
• 查看该工具慢的时候，输入参数是否有共性（例如，是否是某个特定参数导致下游API响应慢）。
• 关联查看该时间段内该下游服务的自身指标（如数据库CPU、第三方API响应时间）。

5.2 错误模式归因与告警通过结构化日志中的error字段和Span状态，可以配置告警规则。例如：

• 规则1：如果5分钟内，tool.name=”calculator”且error=true的日志超过10条，触发告警。这可能意味着计算服务挂了。
• 规则2：如果LLM调用的平均Token消耗量突增50%，触发告警。这可能提示提示词构造出现了问题，或者遇到了异常的输入。

5.3 基于Trace的自动化测试与回归你可以将一些典型的错误会话的Trace ID保存下来，作为“黄金数据集”。在对Agent逻辑或提示词进行迭代后，重新运行这些Trace对应的输入，对比新的执行链和结果与旧的有何不同，自动化地评估改动是否修复了旧问题或引入了新问题。

5.4 理解Agent的“思维”模式通过对大量成功Trace的分析，你可以发现一些模式：对于某类问题，高效的Agent通常会采用怎样的规划步骤？它更偏爱使用哪些工具？这些洞察可以帮助你优化提示词设计，甚至调整工具集的配置，引导Agent做出更优的决策。

6. 避坑指南：实践中必须注意的细节

在实施过程中，我踩过不少坑，这里分享几个关键经验：

6.1 采样策略与成本控制记录所有请求的完整Prompt和Response，数据量和成本会非常惊人。务必实施采样：

• 错误采样：100%记录所有失败请求的完整数据。
• 随机采样：对成功请求按1%或0.1%的比例进行采样，用于监控和优化。
• 重要用户/会话采样：对VIP用户或关键业务会话进行全量记录。 可以在OpenTelemetry的Sampler中或应用层逻辑里实现这些策略。

6.2 数据脱敏与合规日志和追踪数据可能包含个人身份信息（PII）、密钥等敏感数据。必须在记录前进行脱敏处理。不要依赖日志聚合系统的事后脱敏。在代码层面，对于已知的敏感字段（如user.email,query.password），在放入Span属性或日志参数前就将其替换为哈希值或[REDACTED]。可以考虑使用注解或AOP实现统一的脱敏逻辑。

6.3 保持上下文传递在异步或多线程环境中（例如，使用@Async或消息队列处理Agent请求），Trace上下文会丢失。你必须手动进行上下文的传播。OpenTelemetry提供了Context和Scope对象，你可以将它们与任务一起传递。对于Spring的@Async，可以配置一个AsyncConfigurer来包装任务执行器，自动传播上下文。

6.4 工具元数据的丰富化在记录工具调用时，除了名称和参数，尽量记录更多元数据，例如工具的描述、版本、所属类别。这能让你在分析时进行更精细的聚合，比如“所有查询类工具的成功率”、“所有外部API调用的延迟”。

6.5 避免过度日志导致的性能损耗虽然可观测性很重要，但每个日志事件、每个Span属性的记录都有开销。特别是在高频调用的工具函数内部，要避免记录过大的对象（如完整的网页HTML）。只记录诊断问题所必需的最小信息集。可以通过日志级别动态控制详细程度，在开发环境开启DEBUG，在生产环境仅保留INFO和WARN。

构建LLM Agent的可观测性体系是一个持续的过程，它始于基础的Trace ID和结构化日志，逐步扩展到丰富的指标、智能的告警和深度的分析。其回报是巨大的：它不仅能让你在Agent“答错问题”时快速定位根因，更能让你深入理解Agent的行为模式，从而持续地优化和提升其智能与可靠性。从“黑盒”到“白盒”，这是开发现代AI应用的必经之路。