Spring AI Alibaba 1.x 系列【79】图执行生命周期的可观测性基础设施

文章目录

[1. 概述](#1. 概述)
- [1.2 包结构](#1.2 包结构)
- [1.3 类关系图](#1.3 类关系图)
- [1.4 四层模式](#1.4 四层模式)
- [1.5 生命周期监听器模式](#1.5 生命周期监听器模式)
- [1.6 数据流全景](#1.6 数据流全景)
[2. 顶层核心类](#2. 顶层核心类)
- [2.1 SpringAiAlibabaKind](#2.1 SpringAiAlibabaKind)
- [2.2 GraphMetricsGenerator](#2.2 GraphMetricsGenerator)
- [2.3 GraphObservationLifecycleListener](#2.3 GraphObservationLifecycleListener)
[3. metric](#3. metric)
- [3.1 SpringAiAlibabaObservationMetricNames](#3.1 SpringAiAlibabaObservationMetricNames)
- [3.2 SpringAiAlibabaObservationMetricAttributes](#3.2 SpringAiAlibabaObservationMetricAttributes)
[4. graph](#4. graph)
- [4.1 GraphObservationContext](#4.1 GraphObservationContext)
- [4.2 GraphObservationConvention](#4.2 GraphObservationConvention)
- [4.3 DefaultGraphObservationConvention](#4.3 DefaultGraphObservationConvention)
- [4.4 GraphObservationDocumentation](#4.4 GraphObservationDocumentation)
- [4.5 GraphObservationHandler](#4.5 GraphObservationHandler)
[5. node](#5. node)
- [5.1 GraphNodeObservationContext](#5.1 GraphNodeObservationContext)
- [5.2 GraphNodeObservationConvention](#5.2 GraphNodeObservationConvention)
- [5.3 DefaultGraphNodeObservationConvention](#5.3 DefaultGraphNodeObservationConvention)
- [5.4 GraphNodeObservationDocumentation](#5.4 GraphNodeObservationDocumentation)
- [5.5 GraphNodeObservationHandler](#5.5 GraphNodeObservationHandler)
[6. edge](#6. edge)
- [6.1 GraphEdgeObservationContext](#6.1 GraphEdgeObservationContext)
- [6.2 GraphEdgeObservationConvention](#6.2 GraphEdgeObservationConvention)
- [6.3 DefaultGraphEdgeObservationConvention](#6.3 DefaultGraphEdgeObservationConvention)
- [6.4 GraphEdgeObservationDocumentation](#6.4 GraphEdgeObservationDocumentation)
- [6.5 GraphEdgeObservationHandler](#6.5 GraphEdgeObservationHandler)
[7. 总结](#7. 总结)
附录：核心类速查表

1. 概述

Spring AI Alibaba 可观测性 基于 Micrometer Observation API 构建。它为 StateGraph 的执行提供了分布式追踪（tracing）、指标收集（metrics）和生命周期事件处理能力。

com.alibaba.cloud.ai.graph.observation 包：

位置：spring-ai-alibaba-graph-core 模块内
定位：图执行生命周期的可观测性基础设施------在 Graph / Node / Edge 三个粒度上埋点。
职责：定义"观测什么"------Context、Convention、Handler，但不负责如何导出（不依赖 Micrometer/OTLP）

spring-ai-alibaba-starter-graph-observation 模块：

职责：通过 Spring Boot Starter 自动装配 GraphObservationLifecycleListener 等 bean，让 graph-core 中的 observation 包在 Spring Boot 应用中自动生效

1.2 包结构

com.alibaba.cloud.ai.graph.observation 包结构：

bash 复制代码

com.alibaba.cloud.ai.graph.observation
├── SpringAiAlibabaKind.java                  # 操作类型枚举
├── GraphMetricsGenerator.java                # 指标生成工具类
├── GraphObservationLifecycleListener.java    # 图生命周期可观测监听器
├── metric/
│   ├── SpringAiAlibabaObservationMetricNames.java       # 指标名称枚举
│   └── SpringAiAlibabaObservationMetricAttributes.java  # 指标属性枚举
├── graph/
│   ├── GraphObservationContext.java          # Graph 级别观测上下文
│   ├── GraphObservationConvention.java       # Graph 观测约定接口
│   ├── DefaultGraphObservationConvention.java # Graph 默认观测约定
│   ├── GraphObservationDocumentation.java    # Graph 观测文档/Key 定义
│   └── GraphObservationHandler.java          # Graph 观测事件处理器
├── node/
│   ├── GraphNodeObservationContext.java      # Node 级别观测上下文
│   ├── GraphNodeObservationConvention.java   # Node 观测约定接口
│   ├── DefaultGraphNodeObservationConvention.java # Node 默认观测约定
│   ├── GraphNodeObservationDocumentation.java # Node 观测文档/Key 定义
│   └── GraphNodeObservationHandler.java      # Node 观测事件处理器
└── edge/
    ├── GraphEdgeObservationContext.java      # Edge 级别观测上下文
    ├── GraphEdgeObservationConvention.java   # Edge 观测约定接口
    ├── DefaultGraphEdgeObservationConvention.java # Edge 默认观测约定
    ├── GraphEdgeObservationDocumentation.java # Edge 观测文档/Key 定义
    └── GraphEdgeObservationHandler.java      # Edge 观测事件处理器

源码截图：

该模块沿着 Graph 的三个核心维度------整体 Graph 执行 、Node 节点执行 、Edge 边路由 ------建立了完整的可观测体系，每个维度都遵循统一的 Context → Convention → Documentation → Handler 四层设计模式。

1.3 类关系图

复制代码

                              ┌───────────────────────────────┐
                              │  GraphObservationLifecycle     │
                              │        Listener                 │
                              │  (impl GraphLifecycleListener) │
                              └─────┬──────────────┬──────────┘
                                    │ 创建          │ 创建
                       ┌────────────▼──┐    ┌───────▼─────────────┐
                       │ Observation   │    │ Observation (Node)   │
                       │ (Graph)       │    │ 作为子 Observation   │
                       └──────┬────────┘    └───────┬─────────────┘
                              │                     │
              ┌───────────────┼─────────────┐       │
              │               │             │       │
    ┌─────────▼────┐  ┌──────▼──────┐ ┌───▼───────▼──┐
    │GraphHandler  │  │EdgeHandler  │ │ NodeHandler   │
    │(onStop/Error)│  │(onStop/Err) │ │ (onStop/Error)│
    └──────┬───────┘  └──────┬──────┘ └──────┬────────┘
           │                 │               │
           └─────────────────▼───────────────┘
                             │
                    ┌────────▼─────────┐
                    │GraphMetrics      │
                    │Generator         │
                    │(generate Counter)│
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │  MeterRegistry   │
                    │  (Micrometer)    │
                    └──────────────────┘

1.4 四层模式

每个观测维度（Graph / Node / Edge）都遵循相同的四层抽象：

复制代码

┌──────────────────────────────────────────────────────┐
│                   ObservationDocumentation            │
│  定义 Key 名称常量，声明低基数/高基数维度            │
│  实现 ObservationDocumentation 接口                  │
└──────────────────────┬───────────────────────────────┘
                       │ 引用
┌──────────────────────▼───────────────────────────────┐
│              Context (Observation.Context)            │
│  封装观测数据（name, state, output/event 等）        │
│  提供 Builder 模式构造                              │
└──────────────────────┬───────────────────────────────┘
                       │ 关联
┌──────────────────────▼───────────────────────────────┐
│              Convention (ObservationConvention)       │
│  定义如何将 Context 转换为 KeyValue                  │
│  提供低基数和高基数 KeyValue 生成                    │
└──────────────────────┬───────────────────────────────┘
                       │ 使用
┌──────────────────────▼───────────────────────────────┐
│              Handler (ObservationHandler)             │
│  处理 Observation 生命周期事件（onStop/onError）     │
│  调用 GraphMetricsGenerator 生成指标                 │
└──────────────────────────────────────────────────────┘

1.5 生命周期监听器模式

GraphObservationLifecycleListener 通过实现 GraphLifecycleListener 接口，将 Graph 执行引擎的生命周期回调转换为 Micrometer Observation 事件：

复制代码

Graph 执行引擎                          可观测层
─────────────                         ─────────
START 节点触发    →  onStart()       → 创建并启动 Graph Observation
每个节点 before    →  before()       → 创建并启动 Node Observation，打开 Scope
每个节点 after     →  after()        → 关闭 Scope，停止 Node Observation
每个节点 error     →  onError()      → 标记失败，停止 Node/Graph Observation
END 节点触发      →  onComplete()   → 停止 Graph Observation

1.6 数据流全景

复制代码

1. Graph 执行开始
   │
   ▼
2. onStart(START) 
   → GraphObservationLifecycleListener.startGraphObservation()
   → 创建父 Observation("spring.ai.alibaba.graph.graph-execution")
   → 设置 langfuse/gen_ai 输入属性
   → 注册到 CONTEXTS Map
   │
   ▼
3. 每个 Node 执行前
   → before(nodeId) 
   → GraphObservationLifecycleListener.startNodeObservation()
   → 创建子 Observation("spring.ai.alibaba.graph.node.<id>")
   → 以父 Observation 为 parent
   → 打开 Scope 传播上下文
   │
   ▼
4. Node 执行完成
   → after(nodeId)
   → GraphObservationLifecycleListener.stopNodeObservation()
   → 设置 langfuse/gen_ai 输出属性
   → 关闭 Scope，停止子 Observation
   │
   ▼
5. (当存在 Handler 时)
   → GraphNodeObservationHandler.onStop()
   → GraphMetricsGenerator.generate(context, meterRegistry, true)
   → 递增 Counter("spring.ai.alibaba.graph.node")
   │
   ▼
6. Graph 执行结束
   → onComplete(END) / onError()
   → stopGraphObservation()
   → 停止父 Observation
   → 注销 CONTEXTS
   │
   ▼
7. (当存在 Handler 时)
   → GraphObservationHandler.onStop()
   → GraphMetricsGenerator.generate(context, meterRegistry, true)
   → 递增 Counter("spring.ai.alibaba.graph")

2. 顶层核心类

2.1 SpringAiAlibabaKind

定义了 Spring AI Alibaba 中 Graph 操作类型的标准化标识符，用于对观测指标和追踪数据进行分类和过滤。

枚举值	字符串值	含义
`GRAPH`	`"graph"`	整体图操作
`GRAPH_NODE`	`"graph_node"`	图节点操作
`GRAPH_EDGE`	`"graph_edge"`	图边操作

java 复制代码

public enum SpringAiAlibabaKind {
    GRAPH("graph"),
    GRAPH_NODE("graph_node"),
    GRAPH_EDGE("graph_edge");
}

2.2 GraphMetricsGenerator

GraphMetricsGenerator 作为工具类，统一处理指标生成逻辑。负责从观测上下文中生成 Micrometer Counter 指标。为三种级别的上下文（Node、Graph、Edge）分别提供了重载的 generate() 方法，每个方法都会：

创建带有对应指标名称的 Counter
设置成功/失败状态 Tag
从上下文的低基数 KeyValue 中提取并添加自定义 Tag
注册到 MeterRegistry 并递增计数

核心方法签名：

java 复制代码

// 生成 Node 级别指标
public static void generate(GraphNodeObservationContext context, MeterRegistry meterRegistry, boolean isSuccess)

// 生成 Graph 级别指标
public static void generate(GraphObservationContext context, MeterRegistry meterRegistry, boolean isSuccess)

// 生成 Edge 级别指标
public static void generate(GraphEdgeObservationContext context, MeterRegistry meterRegistry, boolean isSuccess)

指标命名规则：

维度	Counter 名称	Tag Key
Graph	`spring.ai.alibaba.graph`	`spring.ai.alibaba.graph.name`, `spring.ai.alibaba.graph.success`
Node	`spring.ai.alibaba.graph.node`	`spring.ai.alibaba.graph.node.name`, `spring.ai.alibaba.graph.node.success`
Edge	`spring.ai.alibaba.graph.edge`	`spring.ai.alibaba.graph.edge.name`, `spring.ai.alibaba.graph.edge.success`

2.3 GraphObservationLifecycleListener

这是整个可观测模块的核心控制器 ，实现了 GraphLifecycleListener 接口，将 Graph 执行的生命周期事件与 Micrometer Observation API 桥接起来。

设计特点：

父子观测模型 : Graph 整体执行为父 Observation，每个 Node 节点执行为子 Observation，形成完整的调用链
线程安全 : 使用 ConcurrentHashMap 存储上下文，确保多线程环境下的安全性
状态截断 : 在 dumpState() 中对状态值进行截断（超过 1000 字符），避免高基数数据爆炸
内部 Key 过滤 : 跳过以 _ 开头的内部 Key 和 logs Key

生命周期方法：

bash 复制代码

onStart()    → 检测到 START 节点 → startGraphObservation()  → 创建父 Observation，注册上下文
  │
before()     → 每个节点执行前     → startNodeObservation()   → 创建子 Observation，打开 Scope
  │
after()      → 每个节点执行后     → stopNodeObservation()    → 关闭 Scope，停止子 Observation
  │
onError()    → 节点或图出错       → handleError()            → 标记失败，记录异常
  │                                   stopGraphObservation()
onComplete() → 检测到 END 节点   → stopGraphObservation()   → 停止父 Observation，注销上下文

关键属性设置：

属性	低基数/高基数	说明
`gen_ai.prompt`	高基数	Graph/Node 输入（状态 dump）
`gen_ai.completion`	高基数	Graph/Node 输出
`langfuse.observation.input`	高基数	Langfuse 兼容的输入
`langfuse.observation.output`	高基数	Langfuse 兼容的输出
`spring.ai.alibaba.graph.success`	低基数	Graph 执行成功/失败
`spring.ai.alibaba.graph.node.success`	低基数	Node 执行成功/失败

内部上下文管理：

java 复制代码

// 静态 Map 存储 Graph 执行上下文，key 为 executionId
private static final Map<String, GraphObservationContext> CONTEXTS = new ConcurrentHashMap<>();

// 内部上下文类
public static class GraphObservationContext {
    final Observation graphObservation;                       // 父 Observation
    final Map<String, Observation> nodeObservations;          // nodeId → 子 Observation
    final Map<String, Observation.Scope> nodeScopes;          // nodeId → Scope
}

注册/注销机制：

register(executionId, graphObservation) --- 将 Graph Observation 注册到全局 Map
unregister(executionId) --- 关闭所有 Node Scope，清除并移除上下文

3. metric

3.1 SpringAiAlibabaObservationMetricNames

定义标准化指标名称，用于标识不同类型的观测指标。

枚举值	字符串值	用途
`GRAPH`	`"spring.ai.alibaba.graph"`	图级别操作指标
`GRAPH_NODE`	`"spring.ai.alibaba.graph.node"`	节点级别操作指标
`GRAPH_EDGE`	`"spring.ai.alibaba.graph.edge"`	边级别操作指标

3.2 SpringAiAlibabaObservationMetricAttributes

定义标准化指标属性名称，用作 Metric Tag 和 Observation KeyValue 的键。

Graph 相关属性：

枚举值	字符串值	说明
`GRAPH_NAME`	`"spring.ai.alibaba.graph.name"`	图名称
`GRAPH_SUCCESS`	`"spring.ai.alibaba.graph.success"`	图执行是否成功

Node 相关属性：

枚举值	字符串值	说明
`GRAPH_NODE_NAME`	`"spring.ai.alibaba.graph.node.name"`	节点名称
`GRAPH_NODE_SUCCESS`	`"spring.ai.alibaba.graph.node.success"`	节点执行是否成功

Edge 相关属性：

枚举值	字符串值	说明
`GRAPH_EDGE_NAME`	`"spring.ai.alibaba.graph.edge.name"`	边名称
`GRAPH_EDGE_SUCCESS`	`"spring.ai.alibaba.graph.edge.success"`	边路由是否成功

Gen AI / Langfuse 兼容属性：

枚举值	字符串值	说明
`GEN_AI_PROMPT`	`"gen_ai.prompt"`	Gen AI Prompt 输入
`GEN_AI_COMPLETION`	`"gen_ai.completion"`	Gen AI Completion 输出
`LANGFUSE_INPUT`	`"langfuse.observation.input"`	Langfuse 追踪输入
`LANGFUSE_OUTPUT`	`"langfuse.observation.output"`	Langfuse 追踪输出

4. graph

Graph 子包负责整体图执行 的可观测性，包含 Context、Convention、DefaultConvention、Documentation、Handler 五个组件。

4.1 GraphObservationContext

继承自 Observation.Context，封装 Graph 执行级别的观测数据。

字段	类型	说明
`graphName`	`String`	图名称
`state`	`Map<String, Object>`	图执行的状态
`output`	`Object`	图执行的输出

4.2 GraphObservationConvention

定义了 Graph 级别观测约定的契约。提供默认的 supportsContext() 实现，通过 instanceof 判断是否支持给定上下文。

java 复制代码

public interface GraphObservationConvention extends ObservationConvention<GraphObservationContext> {
    default boolean supportsContext(Observation.Context context) {
        return context instanceof GraphObservationContext;
    }
}

4.3 DefaultGraphObservationConvention

GraphObservationConvention 的默认实现，提供标准的命名和 Key-Value 生成逻辑。

默认操作名 : "spring.ai.alibaba.graph"
上下文化命名 : 若 Context 有名称，拼接为 "spring.ai.alibaba.graph.<name>"
低基数 Key :
- spring.ai.alibaba.kind = "graph"
- spring.ai.alibaba.graph.name = 图的名称
高基数 Key :
- spring.ai.alibaba.graph.state = 状态字符串
- spring.ai.alibaba.graph.output = 输出字符串（仅在非 null 时添加）

4.4 GraphObservationDocumentation

定义 Graph 观测的 Key 名称常量，区分低基数和高基数维度。

低基数 Key（适合分组和过滤）：

Key 名称	字符串值
`SPRING_AI_ALIBABA_KIND`	`"spring.ai.alibaba.kind"`
`GRAPH_NAME`	`"spring.ai.alibaba.graph.name"`

高基数 Key（适合详细分析）：

Key 名称	字符串值
`GRAPH_NODE_STATE`	`"spring.ai.alibaba.graph.state"`
`GRAPH_NODE_OUTPUT`	`"spring.ai.alibaba.graph.output"`

4.5 GraphObservationHandler

处理 Graph 级别的 Observation 生命周期事件。

onStop() : 日志记录 → 调用 GraphMetricsGenerator.generate() 生成成功指标
onError() : 日志记录 → 调用 GraphMetricsGenerator.generate() 生成失败指标
supportsContext() : 仅处理 GraphObservationContext 类型的上下文

5. node

Node 子包负责图中单个节点执行 的可观测性，结构与 Graph 子包镜像。

5.1 GraphNodeObservationContext

封装单个节点执行的观测数据。

字段	类型	说明
`nodeName`	`String`	节点名称
`event`	`String`	节点事件类型

5.2 GraphNodeObservationConvention

定义 Node 级别观测约定的契约。

5.3 DefaultGraphNodeObservationConvention

GraphNodeObservationConvention 的默认实现。

默认操作名 : "spring.ai.alibaba.graph.node"
上下文化命名 : "spring.ai.alibaba.graph.node.<name>"
低基数 Key :
- spring.ai.alibaba.kind = "graph_node"
- spring.ai.alibaba.graph.node.name = 节点名称
- spring.ai.alibaba.graph.event = 事件类型
高基数 Key : 返回空（KeyValues.empty()）--- 高基数数据由 GraphObservationLifecycleListener 动态注入

注意 : 与 Graph/Edge 的 Convention 不同，Node Convention 的高基数返回为空。Node 的高基数数据（如 node.before.state、node.after.state）是由 GraphObservationLifecycleListener 在运行时通过 highCardinalityKeyValue() 动态注入的，而非由 Convention 静态定义。

5.4 GraphNodeObservationDocumentation

低基数 Key：

Key 名称	字符串值	说明
`SPRING_AI_ALIBABA_KIND`	`"spring.ai.alibaba.kind"`	操作类型
`GRAPH_NODE_NAME`	`"spring.ai.alibaba.graph.node.name"`	节点名称
`GRAPH_EVENT`	`"spring.ai.alibaba.graph.event"`	事件类型

高基数 Key：

Key 名称	字符串值	说明
`NODE_BEFOR_STATE`	`"node.before.state"`	节点执行前的输入状态
`NODE_AFTER_STATE`	`"node.after.state"`	节点执行后的输出状态

注意 : NODE_BEFOR_STATE 和 NODE_AFTER_STATE 的高基数 Key 不由 Convention 添加，而是在 GraphObservationLifecycleListener 中动态注入。

5.5 GraphNodeObservationHandler

onStop() : 调用 GraphMetricsGenerator.generate() 生成成功指标
onError() : 调用 GraphMetricsGenerator.generate() 生成失败指标
supportsContext() : 仅处理 GraphNodeObservationContext 类型的上下文

6. edge

Edge 子包负责图中边（路由）执行的可观测性。

6.1 GraphEdgeObservationContext

封装边路由执行的观测数据。

字段	类型	说明
`graphEdgeName`	`String`	边名称
`state`	`Map<String, Object>`	边执行时的状态
`nextNode`	`String`	路由指向的下一个节点

6.2 GraphEdgeObservationConvention

定义 Edge 级别观测约定的契约。

6.3 DefaultGraphEdgeObservationConvention

默认操作名 : "spring.ai.alibaba.graph.edge"
上下文化命名 : "spring.ai.alibaba.graph.edge.<name>"
低基数 Key :
- spring.ai.alibaba.kind = "graph"
- spring.ai.alibaba.graph.edge.name = 边名称
高基数 Key :
- spring.ai.alibaba.graph.edge.state = 状态字符串
- spring.ai.alibaba.graph.edge.output = 下一节点（仅在非 null 时添加）

注意 : Edge Convention 的低基数 Kind 值是 "graph" 而非 "graph_edge"，这与 SpringAiAlibabaKind 枚举中定义的对应关系有所不同。

6.4 GraphEdgeObservationDocumentation

低基数 Key：

Key 名称	字符串值
`SPRING_AI_ALIBABA_KIND`	`"spring.ai.alibaba.kind"`
`GRAPH_NAME`	`"spring.ai.alibaba.graph.edge.name"`

高基数 Key：

Key 名称	字符串值
`GRAPH_NODE_STATE`	`"spring.ai.alibaba.graph.edge.state"`
`GRAPH_NODE_OUTPUT`	`"spring.ai.alibaba.graph.edge.output"`

6.5 GraphEdgeObservationHandler

onStop() : 日志记录（含 graphName、state、nextNode）→ 调用 GraphMetricsGenerator.generate() 生成成功指标
onError() : 日志记录 → 调用 GraphMetricsGenerator.generate() 生成失败指标
supportsContext() : 仅处理 GraphEdgeObservationContext 类型的上下文

7. 总结

com.alibaba.cloud.ai.graph.observation 包通过 Micrometer Observation API 为 Spring AI Alibaba Graph 引擎提供了完整的可观测性支持：

三层观测维度 ：Graph（整体）、Node（节点）、Edge（边），覆盖 Graph 执行的全部粒度
统一设计模式 ：每个维度都遵循 Context → Convention → Documentation → Handler 四层抽象
生命周期驱动 ：GraphObservationLifecycleListener 将 Graph 执行器的生命周期事件转化为观测事件
多框架兼容 ：原生支持 Micrometer Metrics、Langfuse 追踪、OpenTelemetry 分布式追踪
生产者-消费者解耦 ：Listener 负责生产 Observation 数据，Handler 负责消费并生成指标，两者独立运行

附录：核心类速查表

类名	职责	关键方法
`GraphObservationLifecycleListener`	生命周期监听驱动	`onStart()`, `before()`, `after()`, `onError()`
`SpringAiAlibabaChatModelObservationConvention`	Chat Model 观测约定	`getHighCardinalityKeyValues()`
`GraphObservationHandler`	图观测处理器	`onStop()`, `onError()`
`GraphNodeObservationHandler`	节点观测处理器	`onStop()`, `onError()`
`GraphEdgeObservationHandler`	边观测处理器	`onStop()`, `onError()`
`GraphMetricsGenerator`	指标生成器	`generate(...)` (三个重载)
`GraphObservationContext`	图观测上下文	`getGraphName()`, `getState()`, `getOutput()`
`GraphNodeObservationContext`	节点观测上下文	`getNodeName()`, `getEvent()`
`GraphEdgeObservationContext`	边观测上下文	`getGraphEdgeName()`, `getNextNode()`
`GraphObservationAutoConfiguration`	自动配置类	各类 Bean 定义
`SpringAiAlibabaKind`	观测类型枚举	`GRAPH`, `GRAPH_NODE`, `GRAPH_EDGE`