ai-agent框架spring ai/alibaba原理源码分析(八)观测I 观测组件，观测技术架构

简介saa是java的ai agent框架本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理不仅可以指导agent的开发更可以改造框架增加新特性系列内容系列(一) 架构 完成系列(三) 调用I 工具 完成II MCP1 MCP MCP能力工具资源Promptssampling。。。springboot自动配置 完成2 分布式 MCP3 MCP securityIII skills 完成系列(四) RAG 完成I 知识库文档读取分块嵌入向量storeII 检索增强生成模块化混合检索融合重排系列(二) 模型 model模型 完成chat模型消息提示词结构化输出记忆chat clientadvisor组件系列(五) graphI 图结构节点和边StateGraph外部介入 完成推理框架 graph映射: ReActrelectionCoTPlan-And-ExecuteII 图编译 CompiledGraph扁平化图结构邻接表结构 完成III 图执行检查点回溯/回放中断和恢复容错系列(六) agent及组件 ReactAgentAgentLlmNodeAgentToolNode钩子和拦截器记忆结构化输出 完成系列(七) MASI MAS模式 flow模式 编排器-子智能体智能体团队简单了解 agentic模式 消息总线共享状态数据交接II 分布式MAS远程通讯负载均衡注册发现容错系列(八) I 观测 观测组件(micrometer-observation), langfuseII spring ai观测观测组件ChatClientChatModelIII spring ai alibaba观测 图观测系列(九) 评估 I spring ai 评估组件II spring ai alibaba admin可视化管理、数据集构建、线上链路数据复用III langfuse评估系列(八) 本文分析观测组件based spring ai v1.1.1.2关键词低基数Low-Cardinality标签值组合有限且数量可控的指标数据如HTTP方法(GET/POST/DELETE)、状态码(200/404)等。高基数High-Cardinality标签值可能无限多的数据比如请求ID (requestId)、用户ID (userId)等缩写spring ai缩写saspring ai alibaba本文缩写saa参考资料概览 | Spring AI Alibaba spring ai alibaba官网文档https://docs.spring.io/spring-ai/reference/index.html spring ai官方文档SA/SAA概览上图是saa原理源码分析场景视图每个包对应着saa/sa组件或特性是本文分析的目录上图是saa原理源码分析场景视图每个包对应着saa/sa组件或特性是本文分析的目录model大模型的封装模型包括Chat嵌入audioimage等类型其中chat模型包括advisor组件提示词记忆等agent/graphagent和图紧密相关可以认为agent是一种既定的”图”形开发人员可以使用graph底层api直接构建graph使用agent获得既定的图形简化agent的开发外部调用(calling)工具MCPskillsRAG检索增强生成MASMAS模式 flow模式 编排器-子智能体智能体团队数据交接studio简易的agent管理工具嵌入到agent带有agent面板列表agent提供chat界面用于调试agent是开发agent的便利工具admin管理台 agent的发布列表管理执行提示词工程评估和数据集观测观测微服务监控常用Prometheus Zipkin/SkyWalking微服务与AI Agent的可观测性相同的核心3要素, 日志指标和链路跟踪但ai agent的监控有其特性langfuse 在监控维度、数据结构和工程闭环上对agent有着深度的定制与扩展微服务监控优化的是性能与可用性系统跑得更快、更稳。langfuse优化效率与智能不仅要看Agent“慢不慢”更关心它“好不好”质量和“贵不贵”成本最终目的是让这个AI系统变得越来越“聪明” 关注agent的思考过程决策逻辑和token消耗上图观测组件的场景视图本文使用langfuse作为观测平台集成opentelemetry观测技术架构分析观测组件(micrometer-observation)观测的技术架构包括tracing和meterchatclient观测/chatmodel观测/graph观测本文深入分析3个观测其中chatmodel观测侧重meter观测opentelemetry组件本文示例集成spring boot actuator和桥接组件micrometer-tracing-bridge-otel。micrometer组件定义观测的通用抽象层组件不包括输出到具体观测平台协议实现需要引入相应的组件langfuse支持opentelemetry标准其他advisor观测/toolcalling观测与chatclient类似本文不深入分析观测组件本节分析观测组件上图观测组件互动类图观测Observation模型的核心类它代表了一个被观测的操作例如一次 model请求、一个方法调用或一个 AI Agent的步骤定义了观测的生命周期方法 start, stop, event.error, scope等ObservationRegistry/ObservationConfig观测的注册中心以本地线程变量持有Observation提供获取当前线程的 Observation。该类通过ObservationConfig注册和持有多个 ObservationHandler。观测上下文和处理ObservationHandler观测handler分3类tracermeter和直接继承ObservationHandler Observation通知注册的 ObservationHandler start, stop, event.error等观测生命周期点ObservationHandler处理 Observation 生命周期中的各种事件如开始、停止、错误等。常见的实现包括MetricsHandler生成指标、TracingHandler生成链路追踪 Span、LoggingHandler打印日志。Observation.Context观测的上下文对象各观测点继承Observation.Context实现自己的上下文类型类型增加所需的业务对象Observationobserve方法的被观测业务代码通常向上下文注入所需的业务对象供ObservationHandler使用观测点key和约定ObservationConvention观测约定通过ObservationDocumentation 中的观测key获取观测度量(meter)度量值有两种来源一是定义的常量包括枚举二是Observation.Context业务对象计算的ObservationDocumentation定义观测点的元数据Metadata规定某个观测的名称、描述以及包含哪些低基数Low Cardinality和高基数High Cardinality的 Key该类通常以enum实现单例总结Observation 作为门面观测Facade将业务代码与具体的监控后端指标、追踪解耦。ObservationContext和ObservationConvention的组合使用使业务数据可以以标准化的方式透传给各个处理链实现了高度灵活和可配置的观测能力Observation 的observe方法业务代码注入业务对象到ObservationContexthandler使用业务对象计算观测指标构建span。观测技术架构上节分析了micrometer的观测组件输出到观测平台需要观测平台支持的桥接组件本节以集成OpenTelemetry为实例分析完整的观测技术架构tracing部分本部分分析观测tracing相关的观测组件上图完整观测组合spring boot actuator(粘合剂)OpenTelemetry(langfuse支持的标准)micrometer实现完整的面向langfuse的可观测的技术架构为了降低图复杂性meter部分放到下面的meter技术架构图自动配置与粘合-Spring Boot ActuatorObservationAutoConfiguration: 观测核心自动配置类实例多个观测组件ObservationRegistryPostProcessor ObservationRegistryTracingAwareMeterObservationHandler(meter部分)ObservationRegistryPostProcessorspring 的bean后处理机制(PostProcessor)为ObservationRegistry注入观测handler注入ObjectProviderObservationHandler?也就是收集所有ObservationHandler实例ObservationHandlerGrouping在ObservationRegistryPostProcessor对注入的观测handlers分类整合 meter handlers和tracing handlers两类但实际大多handler直接继承ObservationHandler不受分类影响MicrometerTracingAutoConfiguration: actuator micrometer-tracing包的的自动配置类主要实例观测处理器DefaultTracingObservationHandler注入OpenTelemetryTracingAutoConfiguration构建的Tracer实现类DefaultTracingObservationHandler收到onStart创建并start span收到onStop结束spanOpenTelemetryTracingAutoConfiguration: OpenTelemetry 与 Micrometer 桥接的自动配置类在MicrometerTracingAutoConfiguration之前实例化 OTel 特有的组件OtelTracer观测组件上节分析的Micrometer Observation组件面向开发者的抽奖接口ObservationRegistry: 核心注册中心Observation: 观测ObservationConfig: 配置中心管理处理器ObservationHandler: 观测处理器接口Micrometer Tracing与 OpenTelemetry桥接抽象的“观测”转化为具体的“链路追踪”数据TracerMicrometer组件定义的追踪器接口OtelTracerTracer 接口的 OpenTelemetry 实现类操作 OpenTelemetry 的原生 API 来生成 Trace 和 SpanTracingObservationHandlertracer观测处理器实现 ObservationHandler 接口内部持有Tracer接收到 Observation 的信号时会调用 Tracer 来创建 SpanopentelemetryOpenTelemetry SDK负责最终的数据导出和上报meter部分上图meter部分类图TracingAwareMeterObservationHandler该类是ObservationAutoConfiguration构建在有Tracer bean的条件下构建注入Tracer包装DefaultMeterObservationHandlerDefaultMeterObservationHandler是计算时长指标tracer控制 start/stop也就是实际是计算span的时长互动实现观测业务代码通过 Observation.createNotStarted(...)创建一个 Observation实例业务代码调用 observation.start()Observation查询 ObservationRegistry中注册的观测handlers观测Handler的onStart方法触发tracer handler的tracerOtelTracer调用底层的 opentelemetry 组件创建一个 Spanmetere handler使用Observation的业务对象计算meter还有直接继承ObservationHandler例如写日志写error业务代码结束调用 observation.stop()Handler再次被触发通知 OtelTracer结束 Span完成一次完整的链路记录桥接架构确保从OpenTelemetry切换到其他追踪系统只需更换底层的 Tracer 实现上层的业务代码和 Observation 逻辑完全无需修改。总结观测组件设计理念是“API 与实现分离”引入micrometer-observation 作为通用抽象层统一的门面业务代码不再直接依赖具体的追踪系统如OpenTelemetry或Brave而是面向标准的 Observation组件编程。Spring Boot Actuator 作为自动配置和粘合剂协调各个标准组件和特定观测平台的组件micrometer-tracing 及其桥接器则负责将通用的观测转化为特定观测平台(opentelemetry)使用指定平台的exporter输出到langfuseNEXTII spring ai 观测分析chatclientchatmodel(侧重meter)实例langfuseIII spring ai alibabab观测分析图实例