1. 项目概述当 SpringBootAI 遇见观测云 MCP最近在折腾一个基于 SpringBoot 的 AI 应用随着功能越来越复杂一个老问题又浮出水面我怎么才能清晰地知道我的 AI 服务在线上跑得到底怎么样每次用户反馈说“回答慢了”或者“结果不对”排查起来都像大海捞针。日志是散的指标是缺的链路是断的。直到我把目光投向了观测云并且尝试通过其 MCP模型上下文协议将两者深度集成才算真正找到了一个优雅的解决方案。这不仅仅是接个 SDK 那么简单而是一套从代码埋点、数据采集到可视化分析、智能告警的完整可观测性实践。今天我就来详细拆解一下如何将你的 SpringBootAI 项目无缝接入观测云 MCP打造一个“看得见、理得清、管得住”的智能服务。简单来说这个实践的核心目标是为你的 SpringBootAI 应用装上“全景仪表盘”和“智能诊断系统”。通过观测云 MCP你可以将 AI 模型调用耗时、Token 消耗、请求成功率、用户意图分布乃至具体的请求与响应内容都转化为结构化的指标、日志和链路数据。无论是想优化大模型 API 的调用成本还是定位某次生成结果偏差的根因或是评估不同提示词模板的效果都有了坚实的数据支撑。这尤其适合那些已经将 AI 能力作为核心功能模块的中大型应用或者是任何对服务稳定性和用户体验有高要求的团队。2. 核心思路与架构设计拆解在动手写代码之前我们先得把整个方案的思路理清楚。为什么是观测云 MCP它和我们平时在 SpringBoot 里用的 Micrometer、Logback 有什么不同2.1 为什么选择观测云 MCP 而非传统监控传统的监控方案比如用 Micrometer 收集指标到 Prometheus用 Logback 写日志到 ELK再用 Sleuth 做链路追踪当然也能用。但面对 AI 应用有几个独特的痛点数据维度复杂一次 AI 调用我们关心的不仅仅是 HTTP 请求的耗时和状态码。我们更关心调用了哪个模型gpt-4o 还是 claude-3.5本次消耗了多少 Prompt Tokens 和 Completion Tokens本次请求的提示词Prompt模板是哪个版本生成的回答是否触发了内容过滤Flag这些高度定制化的字段传统监控的通用模型很难优雅承载。上下文关联困难当用户投诉“刚才那个回答不对”时你需要快速定位到那次具体的请求看到当时输入的完整问题、系统给出的上下文、以及模型返回的原始内容。这要求日志、链路和具体的业务数据请求/响应体能通过一个唯一的标识比如trace_id强关联起来。传统方案需要自己费力打通。开箱即用的 AI 视角观测云 MCP 协议及其配套的仪表盘某种程度上是为 AI 应用场景“量身定制”的。它预置了对 LLM 调用、Token 消耗、会话等概念的模型支持接入后很快就能看到针对性的可视化图表省去了大量自己配置 Grafana 面板的功夫。观测云的 MCP 协议本质上定义了一套标准让任何应用比如我们的 SpringBootAI都能以结构化的方式向观测云的后台发送丰富的可观测性数据。它兼容 OpenTelemetry 的标准但提供了更贴近其自身平台特性的扩展能力。2.2 整体架构与数据流设计我们的架构目标很明确无侵入或低侵入地采集数据并通过一个高效稳定的客户端将数据发送到观测云。[SpringBootAI 应用] | | (通过 Java Agent 或 SDK 埋点) v [观测云 DataKit (数据采集器)] - 可选用于丰富主机指标 | | (通过 HTTP/gRPC 上报) v [观测云 MCP 服务端] | v [观测云平台指标、日志、链路、用户访问监测(RUM)、安全巡检(CI)等]具体到代码层面我们有两种主要的集成方式基于 OpenTelemetry Java Agent 的自动埋点推荐这是侵入性最低的方式。通过一个独立的 Java AgentJAR 包在应用启动时通过-javaagent参数加载它可以自动拦截常见的 HTTP 框架如 Spring MVC、数据库驱动如 JDBC、消息队列如 Kafka以及HTTP 客户端如 OkHttp、Apache HttpClient的调用。这对于监控我们 SpringBootAI 调用外部大模型 API如 OpenAI、通义千问的请求来说是零代码改造的。基于观测云 SDK 的手动埋点这种方式更灵活可以采集任何你关心的业务数据。例如在调用 AI 模型的代码前后手动记录开始和结束时间、记录请求和响应的内容、计算 Token 数量等然后通过 SDK 的 API 发送自定义指标和日志。在实际项目中我通常会混合使用这两种方式用 Agent 自动采集基础设施HTTP、DB的遥测数据保证基线再用 SDK 在关键的 AI 业务逻辑处手动埋点记录那些 Agent 无法自动获取的、富含业务语义的信息。3. 环境准备与依赖配置理论清楚了我们开始动手。首先得把“原材料”准备好。3.1 观测云平台侧准备工作注册与工作空间创建如果你还没有观测云账号需要先注册。登录后创建一个新的工作空间Workspace这将是所有数据的容器。获取接入点Gateway地址与令牌Token这是客户端向观测云发送数据的“门牌号”和“钥匙”。在观测云控制台通常可以在“集成”或“数据采集”相关页面找到。你需要获取DataWay 地址形如https://openway.guance.com?tokenYOUR_TOKEN。YOUR_TOKEN需要替换成你的实际令牌。应用性能监测APM接入点如果你使用 Agent 进行链路追踪可能需要一个单独的 APM 接入点格式类似https://apm-guance.com。可选安装 DataKit如果你需要采集 SpringBootAI 应用所在服务器的系统指标CPU、内存、磁盘、进程信息或容器信息需要在服务器上安装并配置 DataKit。观测云提供了详细的安装脚本。这对于全面监控应用运行环境很有帮助。3.2 SpringBootAI 项目侧依赖引入假设你的 SpringBootAI 项目使用 Maven 管理依赖。我们需要引入观测云的核心 SDK。核心依赖观测云 Java SDK这个 SDK 包含了发送指标Metric、日志Log、对象Object等数据的基础能力。!-- 在 pom.xml 中添加 -- dependency groupIdcom.guance/groupId artifactIddataflux-sdk-java/artifactId version最新版本/version !-- 请查阅观测云官方文档获取最新版本号例如 1.x.x -- /dependency可选但推荐OpenTelemetry 依赖如果你计划使用自动埋点或者希望手动创建分布式链路还需要引入 OpenTelemetry 的相关依赖。观测云的 SDK 通常与 OpenTelemetry 兼容。dependency groupIdio.opentelemetry/groupId artifactIdopentelemetry-api/artifactId version1.35.0/version !-- 使用与观测云 Agent 兼容的版本 -- /dependency dependency groupIdio.opentelemetry/groupId artifactIdopentelemetry-sdk/artifactId version1.35.0/version /dependency dependency groupIdio.opentelemetry/groupId artifactIdopentelemetry-exporter-otlp/artifactId version1.35.0/version /dependency注意版本兼容性这是最容易踩坑的地方。观测云的 Java Agent、SDK 以及 OpenTelemetry 的各组件版本之间存在严格的兼容性要求。强烈建议你直接查阅观测云官方文档中提供的“推荐依赖版本”或“快速开始”示例照搬其中的版本号可以避免 90% 的启动和上报问题。4. 核心集成与代码实现详解配置好依赖我们进入核心的代码集成环节。我将分“自动埋点”和“手动埋点”两部分来讲解。4.1 方案一使用 Java Agent 实现自动埋点无侵入这是最快让应用具备基础可观测能力的方法。下载 Agent从观测云官方文档的下载页面获取对应版本的dd-java-agent.jar。启动参数配置在启动你的 SpringBootAI 应用时添加 JVM 参数。java -javaagent:/path/to/dd-java-agent.jar \ -Ddd.service.nameyour-springbootai-service \ # 服务名重要 -Ddd.envprod \ # 环境标识如 prod, staging, test -Ddd.version1.0.0 \ # 应用版本 -Ddd.logs.injectiontrue \ # 启用日志链路关联推荐 -Ddd.trace.sample.rate1.0 \ # 采样率1.0表示100%采样生产环境可调低 -Ddd.profiling.enabledfalse \ # 性能剖析按需开启 -Ddd.agent.hostlocalhost \ # DataKit 地址如果 DataKit 装在本机 -Ddd.agent.port9529 \ # DataKit 默认端口 -jar your-springbootai-app.jar关键参数解析dd.service.name这是最重要的标签之一。在观测云界面上所有数据都会按这个服务名进行聚合。请起一个有意义的名字如ai-content-generator。dd.env和dd.version用于区分不同环境和版本的数据。当你在灰度发布或排查某个版本特有的问题时这个标签价值连城。dd.logs.injection开启后Agent 会自动将trace_id和span_id注入到 MDCMapped Diagnostic Context中。如果你使用 Logback 或 Log4j2并配置了相应的布局PatternLayout来输出这些 ID那么你的应用日志就能和链路追踪数据关联起来。验证自动埋点启动应用发起几次 AI 接口调用。然后登录观测云平台进入“应用性能监测APM”模块。你应该能看到以dd.service.name命名的服务。点击进入可以看到服务接口的调用拓扑、请求速率、延迟和错误率。如果调用了外部 HTTP 服务如大模型 API在链路详情里也能看到这次调用的耗时。实操心得Agent 方式虽然省事但采集的数据粒度较粗。它知道“调用了某个 HTTP 接口”但不知道这次调用是“向 GPT-4 请求生成文章”。因此它更适合监控基础设施层面的健康度。要深入洞察 AI 业务必须结合手动埋点。4.2 方案二使用 SDK 进行关键业务手动埋点现在我们来给 AI 的核心逻辑加上“显微镜”。假设我们有一个AIService里面封装了调用大模型的方法。第一步初始化观测云 SDK Client我们需要一个全局的客户端来发送数据。可以将其配置为 Spring Bean。import com.guance.sdk.client.DataFluxClient; import com.guance.sdk.client.config.ClientConfig; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class ObservabilityConfig { Value(${guance.dataway.url}) private String datawayUrl; // 配置在 application.yml 中 Bean public DataFluxClient dataFluxClient() { ClientConfig config ClientConfig.builder() .datawayUrl(datawayUrl) // 例如: https://openway.guance.com?tokenyour_token_here .build(); return new DataFluxClient(config); } }第二步在 AI 调用关键点埋点我们将在调用大模型前后记录一条自定义的“AI 调用”指标和详细的日志。import com.guance.sdk.client.DataFluxClient; import com.guance.sdk.client.model.Metric; import com.guance.sdk.client.model.Log; import io.opentelemetry.api.trace.Span; import io.opentelemetry.context.Scope; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.HashMap; import java.util.Map; Service public class AIService { Autowired private DataFluxClient dataFluxClient; Autowired private Tracer tracer; // 需要配置 OpenTelemetry Tracer Bean public String generateContent(String userPrompt, String model) { // 1. 创建自定义 Span丰富链路信息 Span aiSpan tracer.spanBuilder(ai.model.invoke) .setAttribute(ai.model, model) .setAttribute(ai.prompt.length, userPrompt.length()) .startSpan(); String traceId aiSpan.getSpanContext().getTraceId(); // 获取 traceId 用于关联 long startTime System.currentTimeMillis(); MapString, String tags new HashMap(); tags.put(service, springbootai-demo); tags.put(env, prod); tags.put(model, model); // 关键业务标签 tags.put(operation, generate); try (Scope scope aiSpan.makeCurrent()) { // 模拟调用大模型 API // String response callOpenAI(userPrompt, model); String response 这是模拟的AI生成内容。; long endTime System.currentTimeMillis(); long duration endTime - startTime; // 2. 发送自定义指标AI调用耗时、Token数模拟 Metric metric Metric.builder(ai.invocation.duration, duration) // 指标名值 .tags(tags) // 标签集 .field(prompt_tokens, userPrompt.length() * 0.75) // 模拟计算 .field(completion_tokens, response.length() * 0.25) .field(success, 1.0) // 成功为1 .build(); dataFluxClient.sendMetric(metric); // 3. 发送结构化日志记录请求详情关联traceId Log requestLog Log.builder() .message(AI Model Request) .tags(tags) .field(trace_id, traceId) // 关键关联链路 .field(full_prompt, userPrompt) // 记录完整提示词 .field(model, model) .timestamp(System.currentTimeMillis()) .build(); dataFluxClient.sendLog(requestLog); // 同样可以发送一条响应日志 Log responseLog Log.builder() .message(AI Model Response) .tags(tags) .field(trace_id, traceId) .field(response_snippet, response.substring(0, Math.min(100, response.length()))) // 记录片段避免过长 .field(total_tokens, userPrompt.length() response.length()) .timestamp(System.currentTimeMillis()) .build(); dataFluxClient.sendLog(responseLog); aiSpan.end(); // 结束 Span return response; } catch (Exception e) { long endTime System.currentTimeMillis(); // 4. 调用失败时发送错误指标和日志 tags.put(error, true); Metric errorMetric Metric.builder(ai.invocation.duration, endTime - startTime) .tags(tags) .field(success, 0.0) // 失败为0 .build(); dataFluxClient.sendMetric(errorMetric); Log errorLog Log.builder() .message(AI Model Invocation Failed) .tags(tags) .field(trace_id, traceId) .field(error, e.getMessage()) .timestamp(System.currentTimeMillis()) .build(); dataFluxClient.sendLog(errorLog); aiSpan.recordException(e); // 在 Span 上记录异常 aiSpan.end(); throw new RuntimeException(AI调用失败, e); } } }代码关键点解析标签Tags与字段Fields的区分这是观测云数据模型的核心。tags是用于筛选和分组的维度通常是字符串类型且值域相对固定如envprod,modelgpt-4。fields是用于计算和聚合的指标值通常是数值类型如耗时、Token数。在后台配置仪表盘时你可以按tags进行分组例如按model查看各模型的平均耗时对fields进行聚合计算如求和、求平均。关联性通过手动将trace_id放入日志的field中我们成功地将一次具体的 AI 调用业务日志与由 Agent 自动生成的 HTTP 请求链路关联了起来。在观测云平台你可以从一条慢速的链路直接跳转到查看这次调用当时的详细请求和响应日志。数据安全注意我们记录用户提示词full_prompt和响应片段时需要考虑到隐私和安全。在生产环境中可能需要对敏感信息进行脱敏处理或者只记录经过哈希处理的提示词模板 ID。5. 观测云平台配置与仪表盘搭建数据上报上去了我们得在观测云平台上把它们“用起来”变成直观的图表和警报。5.1 数据验证与查看日志查看器Logs在观测云平台进入“日志”模块在查询框里输入service:springbootai-demo你自定义的标签应该能看到你通过 SDK 发送的“AI Model Request”和“AI Model Response”日志。点击一条日志可以看到详情包括我们自定义的trace_id,model,full_prompt等字段。指标浏览器Metrics进入“指标”模块输入ai.invocation.duration应该能看到我们上报的耗时指标。你可以选择不同的聚合方式avg, max, p95等和分组维度按model,env等 tag。应用性能监测APM这里展示的是由 Java Agent 自动生成的链路数据。你应该能看到服务接口的调用情况。如果手动埋点的 Span 也上报了需要正确配置 OTLP 导出器它们也会出现在链路详情中。5.2 创建自定义 AI 监控仪表盘仪表盘是监控的“作战指挥中心”。我们创建一个专属的“SpringBootAI 服务监控”看板。新建仪表盘在观测云平台进入“仪表板”模块点击“新建”。添加图表 - AI 调用量趋势选择“时序图”。指标选择ai.invocation.duration实际上我们更关心调用次数但 duration 指标每个点都有值。更佳实践是上报一个ai.invocation.count的计数指标。聚合方式选择count计数。这样就能看到每秒/每分钟的调用次数。分组选择按model可以清晰对比不同模型的调用频率。添加图表 - AI 调用平均耗时与错误率添加两个“时序图”或“排行榜图”。第一个指标选ai.invocation.duration聚合选avg分组选model。这是平均响应时间。第二个指标选ai.invocation.duration但我们需要利用success这个 field。可以创建一个“查询变量”或使用高级查询avg:(ai.invocation.duration{success0}) / count:(ai.invocation.duration) * 100来近似计算错误率更规范的做法是上报独立的错误计数指标。添加图表 - Token 消耗统计选择“饼图”或“累计柱状图”。指标选择ai.invocation.duration因为 Token 数据在 field 里。观测云支持对 field 进行聚合。你需要编写查询对prompt_tokens和completion_tokens字段分别求和。例如sum:(ai.invocation.duration{prompt_tokens})。这可能需要你在图表配置的“高级”模式中编写查询语句。添加日志查询组件直接添加一个“日志”组件查询条件设为service:springbootai-demo并设置按时间倒序排列。这样最新的 AI 调用日志就实时显示在仪表盘上了方便随时查看。5.3 配置智能告警监控的最终目的是为了及时发现问题。观测云的监控器功能很强大。创建告警策略进入“监控器” - “新建监控器”。设置触发条件例如我们想监控“AI 调用平均耗时突增”。监控类型指标。指标ai.invocation.duration。检测规则avg(最近5分钟) avg(前10分钟至前5分钟) * 1.5。意思是如果最近5分钟的平均耗时比再往前5分钟的平均耗时高了50%就触发告警。这是一个简单的同比突增检测。触发条件持续 2 个检测周期。设置告警通知配置当告警触发时通过哪些渠道通知如钉钉、企业微信、飞书、短信、邮件等。可以设置不同的通知级别和接收人。高级设置 AI 调用失败告警再创建一个监控器检测success字段。例如sum(最近5分钟 success0) 10即5分钟内失败次数超过10次就告警。6. 生产环境进阶实践与避坑指南将这套方案应用到生产环境还有一些细节需要打磨。6.1 性能与稳定性优化SDK 异步发送与批量提交确保DataFluxClient配置为异步发送模式默认通常是。观测云 SDK 内部会有队列和批量发送机制避免同步网络 I/O 阻塞业务线程。你需要关注 SDK 的缓冲区状态避免队列积压。采样率控制对于超高流量的服务100%采集所有链路的详细日志尤其是包含长文本的 Prompt 和 Response可能带来巨大的存储成本和网络开销。需要在精细度和成本间权衡。链路采样通过-Ddd.trace.sample.rate0.1只采样10%的请求进行全链路追踪。日志采样在代码中可以设计逻辑例如只对错误请求、或每N次成功请求记录一次详细日志。Agent 与 SDK 的协同确保 Agent 和手动 SDK 埋点使用的service.name、env等核心标签一致否则数据会在平台上分散无法有效关联。6.2 数据模型设计最佳实践设计清晰的指标和标签体系在项目初期就规划好。例如指标名ai.operation.duration,ai.token.consumption,ai.request.count核心标签project项目,module模块,model模型,provider供应商,api_operation具体操作如chat,embedding,moderation字段duration_ms,prompt_tokens,completion_tokens,total_tokens,cost估算成本避免标签值爆炸不要将用户ID、会话ID这种高基数的值作为标签Tag否则会导致后端索引爆炸查询性能急剧下降。这些高基数维度应该作为日志的字段Field进行存储和查询。6.3 常见问题排查FAQQ数据没有在观测云平台显示A首先检查网络连通性确保应用服务器能访问 DataWay 地址。其次检查 SDK 初始化日志或 Agent 日志通常有-Ddd.logstrue参数开启看是否有连接错误或认证失败Token 错误的信息。最后在观测云平台检查数据是否有延迟通常有几秒到一分钟的延迟是正常的。Q手动埋点的日志和自动生成的链路无法关联A确保在手动埋点代码中正确获取并传递了trace_id。检查 OpenTelemetry 的上下文传播是否正常。在 Spring Boot 中如果通过 Agent 自动管理链路你需要通过io.opentelemetry.api.GlobalOpenTelemetry.getTracer()获取与 Agent 同一上下文的 Tracer而不是自己新建一个。Q上报数据导致应用 CPU 或内存使用率升高A这是异步队列处理不当的典型表现。检查观测云 SDK 的配置确认其工作线程数、队列大小是否合理。对于超高吞吐场景可以考虑将数据先写入本地文件然后由独立的 Agent如 DataKit进行读取和转发实现与业务进程的完全解耦。Q仪表盘查询速度很慢A可能是查询了过大的时间范围或者对高基数字段进行了分组。优化查询缩小时间范围避免对user_id这类字段做group by考虑将需要频繁聚合的指标通过观测云的“数据预处理”或“聚合规则”功能预先计算成更粗粒度的汇总指标。我个人在多个生产级 AI 项目中实践下来的体会是接入观测云 MCP 不是一个一蹴而就的动作而是一个持续迭代的过程。初期可以先通过 Agent 实现基础监控快速看到效果。随着业务复杂化再逐步增加关键业务的手动埋点丰富数据维度。最终你会形成一个覆盖从基础设施到业务逻辑、从实时监控到历史分析、从被动告警到主动洞察的完整可观测性体系。这套体系不仅能帮你快速定位线上问题更能通过数据驱动的方式反向优化你的提示词工程、模型选型和资源调度策略让 AI 服务真正跑得又稳又好。