简介

    saa是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅可以指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一) 架构  完成
系列(三) 调用 
     I 工具  完成 
     II MCP
       1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置  完成
       2 分布式 MCP  
       3 MCP security
     III skills  完成
系列(四) RAG  完成
     I 知识库，文档读取，分块；嵌入，向量store 
     II 检索，增强生成，模块化；混合检索，融合重排
系列(二) 模型 model模型 完成
         chat模型，消息，提示词，结构化输出，记忆
         chat client，advisor组件
系列(五) graph  
        I 图结构，节点和边；StateGraph；外部介入 完成
          推理框架  graph映射: ReAct，relection，CoT，Plan-And-Execute 
        II 图编译 CompiledGraph，扁平化图结构，邻接表结构 完成
        III 图执行，检查点，回溯/回放，中断和恢复，容错
系列(六) agent及组件 ReactAgent，AgentLlmNode，AgentToolNode，钩子和拦截器，记忆，结构化输出 完成
系列(七) MAS
        I MAS模式 flow模式 编排器-子智能体，智能体团队；简单了解 agentic模式 消息总线，共享状态；数据交接
        II 分布式MAS，远程通讯，负载均衡，注册发现，容错
系列(八) I 观测  观测组件(micrometer-observation), langfuse
           II spring ai观测，观测组件，ChatClient，ChatModel
           III spring ai alibaba观测  图观测
系列(九) 评估 langfuse

系列(八) 本文分析观测组件

based spring ai v1.1.1.2

关键词

低基数（Low-Cardinality） 标签值组合有限且数量可控的指标数据，如， HTTP 方法 (GET/POST/DELETE)、状态码 (200/404) 等。

高基数（High-Cardinality） 标签值可能无限多的数据，比如 请求ID (requestId)、用户ID (userId) 等

缩写

spring ai 缩写sa

spring 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，嵌入，audio，image等类型，其中chat模型包括，advisor组件，提示词，记忆等

agent/graph  agent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph底层api直接构建graph，使用agent获得既定的图形，简化agent的开发

外部调用(calling)  工具，MCP，skills

RAG  检索增强生成

MAS  MAS模式 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和meter

chatclient观测/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：观测的注册中心，以本地线程变量持有Observation，提供获取当前线程的 Observation。该类通过ObservationConfig注册和持有多个 ObservationHandler。

观测上下文和处理

• ObservationHandler：观测handler有两类，tracer和meter，Observation通知注册的 ObservationHandler  start, stop, event.error等观测生命周期点，ObservationHandler处理 Observation 生命周期中的各种事件（如开始、停止、错误等）。常见的实现包括：MetricsHandler（生成指标）、TracingHandler（生成链路追踪 Span）、LoggingHandler（打印日志）。
• Observation.Context：观测的上下文对象，观测继承Observation.Context实现自己的上下文类型，类型增加所需的业务对象，Observation observe方法的被观测业务代码通常向上下文注入所需的业务对象，供ObservationHandler使用

观测点key和约定

• ObservationConvention ：观测约定，通过ObservationDocumentation 中的观测key获取观测度量(meter)，度量值有两种来源，一是定义的常量，包括枚举；二是Observation.Context业务对象计算的

• ObservationDocumentation：定义观测点的元数据（Metadata），规定某个观测的名称、描述，以及包含哪些低基数（Low Cardinality）和高基数（High Cardinality）的 Key，该类通常以enum实现单例

总结： Observation 作为门面观测（Facade），将业务代码与具体的监控后端（指标、追踪）解耦。ObservationContext 和 ObservationConvention 的组合使用，使业务数据可以以标准化的方式透传给各个处理链，实现了高度灵活和可配置的观测能力，Observation 的observe方法，业务代码注入业务对象到ObservationContext ，handler使用业务对象计算观测指标，构建span。

观测技术架构

上节分析了micrometer的观测组件，输出到观测平台需要观测平台支持的桥接组件，本节以集成OpenTelemetry为实例，分析完整的观测技术架构

tracing部分

本部分分析观测tracing相关的观测组件

上图完整观测组合，spring boot actuator(粘合剂)，OpenTelemetry(langfuse支持的标准)，micrometer实现完整的，面向langfuse的可观测的技术架构，为了降低图复杂性，meter部分放到下面的meter技术架构图

自动配置与粘合-Spring Boot Actuator

• ObservationAutoConfiguration: 观测核心自动配置类，实例多个观测组件，ObservationRegistryPostProcessor ，ObservationRegistry，TracingAwareMeterObservationHandler(meter部分)
• ObservationRegistryPostProcessor  spring 的bean后处理机制(PostProcessor)，为ObservationRegistry注入观测handler，注入ObjectProvider<ObservationHandler<?>>，也就是收集所有ObservationHandler实例

            ObservationHandlerGrouping  在ObservationRegistryPostProcessor对注入的观测handlers分类整合， meter handlers和tracing handlers两类，但实际大多handler直接继承ObservationHandler，不受分类影响

• MicrometerTracingAutoConfiguration:  actuator micrometer-tracing包的的自动配置类，主要实例观测处理器DefaultTracingObservationHandler，注入OpenTelemetryTracingAutoConfiguration构建的Tracer实现类
• DefaultTracingObservationHandler  收到onStart 创建并start span；收到onStop 结束span
• OpenTelemetryTracingAutoConfiguration:  OpenTelemetry 与 Micrometer 桥接的自动配置类，在MicrometerTracingAutoConfiguration之前，实例化 OTel 特有的组件OtelTracer

观测组件：上节分析的Micrometer Observation组件，面向开发者的抽奖接口

• ObservationRegistry: 核心注册中心
• Observation: 观测
• ObservationConfig: 配置中心，管理处理器
• ObservationHandler: 观测处理器接口

Micrometer Tracing 与 OpenTelemetry 桥接

     抽象的“观测”转化为具体的“链路追踪”数据

• Tracer：Micrometer组件定义的追踪器接口
• OtelTracer：Tracer 接口的 OpenTelemetry 实现类，操作 OpenTelemetry 的原生 API 来生成 Trace 和 Span
• TracingObservationHandler：tracer观测处理器，实现 ObservationHandler 接口，内部持有Tracer，接收到 Observation 的信号时，会调用 Tracer 来创建 Span
• opentelemetry：OpenTelemetry SDK，负责最终的数据导出和上报

meter部分

上图meter部分类图

• TracingAwareMeterObservationHandler  该类是ObservationAutoConfiguration构建，在有Tracer  bean的条件下构建，注入Tracer，包装DefaultMeterObservationHandler，DefaultMeterObservationHandler是计算时长指标，tracer控制 start/stop，也就是实际是计算span的时长

互动实现观测

• 业务代码通过 Observation.createNotStarted(...) 创建一个 Observation 实例
• 业务代码调用 observation.start() ，Observation查询 ObservationRegistry中注册的观测handlers，包括meter和tracing的
• 观测Handler的onStart方法触发

       tracer handler的tracer（OtelTracer）调用底层的 opentelemetry 组件创建一个 Span

      metere handler使用Observation的业务对象计算meter

• 业务代码结束，调用 observation.stop() ，Handler 再次被触发，通知 OtelTracer 结束 Span，完成一次完整的链路记录

桥接架构确保从OpenTelemetry切换到其他追踪系统，只需更换底层的 Tracer 实现，上层的业务代码和 Observation 逻辑完全无需修改。

总结：观测组件设计理念是“API 与实现分离”，引入micrometer-observation 作为通用抽象层，统一的门面，业务代码不再直接依赖具体的追踪系统（如OpenTelemetry或Brave），而是面向标准的 Observation组件编程。Spring Boot Actuator 作为自动配置和粘合剂，协调各个标准组件和特定观测平台的组件，micrometer-tracing 及其桥接器则负责将通用的观测转化为特定观测平台(opentelemetry)，使用指定平台的exporter输出到langfuse

NEXT

II spring ai 观测分析，chatclient，chatmodel(侧重meter)，实例@langfuse

III spring ai alibabab观测分析，图，实例