Spring AI 可观测性（Observability）技术详解

本文将系统梳理 Spring AI 的可观测性能力，包括名词解释、发展历史、架构原理、关键配置、指标体系，并使用 Mermaid 绘制三类结构图，帮助你快速建立系统性认知。

---

一、什么是可观测性（Observability）？

名词解释

• 可观测性（Observability）
  指系统能够通过外部输出（如日志、指标、跟踪）反映内部状态，便于监控、诊断和优化。

• Spring Boot Actuator
  Spring Boot 的监控和管理工具包，提供健康检查、指标暴露、应用监控等能力。

• Micrometer
  JVM 应用指标收集库，支持多种监控后端（如 Prometheus、Grafana）。

• OpenTelemetry
  开源分布式追踪/指标标准，Spring AI 参考其语义约定。

---

二、Spring AI 可观测性简介

Spring AI 集成了 Spring 生态的可观测性能力，支持对 AI 相关组件（如 ChatClient、ChatModel、EmbeddingModel、ImageModel、VectorStore）进行性能监控、分布式链路追踪和指标采集。通过配置，可以细粒度控制敏感数据的暴露与日志收集，兼顾安全与调试需求。

---

三、项目背景与发展历史

背景

• 随着生成式 AI 应用的兴起，模型调用、Prompt 设计、向量存储等链路日益复杂。
• 企业级应用对 AI 系统的性能、稳定性、合规性提出高要求。
• 可观测性成为 AI 应用“可管可控”的基础能力。

发展历程

• Spring Boot Actuator 成熟的应用监控方案，成为 Spring AI 的基础。
• Micrometer 与 OpenTelemetry 的接入，实现通用指标和链路追踪。
• Spring AI 持续扩展对主流大模型、向量数据库的观测能力，并对敏感数据的采集策略不断优化。

参考资料

• Spring AI 官方文档
• OpenTelemetry Semantic Conventions for Generative AI
• Micrometer 官方文档

---

四、架构原理与指标体系

1. 组件结构

主要观测对象

组件	说明
ChatClient	对话客户端（调用、流式响应）
ChatModel	大模型接口（OpenAI、Azure等）
EmbeddingModel	向量生成模型
ImageModel	图像生成模型
VectorStore	向量数据库

观测维度

• 低基数键（Low Cardinality Keys）：用于指标，便于聚合和查询。
• 高基数键（High Cardinality Keys）：用于追踪，包含详细参数和内容。

---

2. 关键配置与数据安全

配置项	作用	默认值
spring.ai.chat.client.observations.log-prompt	是否记录 Prompt 内容	false
spring.ai.chat.client.observations.log-completion	是否记录模型回复	false
spring.ai.chat.observations.log-prompt	是否记录 ChatModel 的 Prompt	false
spring.ai.chat.observations.log-completion	是否记录 ChatModel 的 Completion	false
spring.ai.vectorstore.observations.log-query-response	是否记录向量查询结果	false
spring.ai.tools.observations.include-content	是否记录工具调用的参数与结果	false

安全提示：
启用日志内容记录时，务必注意敏感信息泄露风险！

---

3. 指标体系与 Prometheus 集成

主要指标

指标名	类型	单位	作用说明
gen_ai_chat_client_operation_seconds_sum	Timer	seconds	对话客户端总耗时
gen_ai_chat_client_operation_seconds_count	Counter	count	对话客户端调用次数
gen_ai_client_token_usage_total	Counter	tokens	模型调用消耗 Token 数量
db_vector_client_operation_seconds_sum	Timer	seconds	向量库操作总耗时

标签示例

• gen_ai_token_type=input / output / total
• db_operation_name=add / query / delete
• db_system=redis / chroma / pgvector / …

---

五、结构化说明（Mermaid 图）

1. 系统流程总览（Flowchart）

解读：
用户请求经过 ChatClient，可能调用 ChatModel、EmbeddingModel、ImageModel 或 VectorStore，所有关键操作均通过 Micrometer 采集指标、OpenTelemetry 进行链路追踪，最终在 Prometheus、Grafana 等后端展示。

---

2. 观测状态变迁（StateDiagram）

解读：
每次请求经历参数解析、业务处理后，进入观测采集阶段，分别生成日志、指标和追踪数据，供后续分析。

---

3. 调用链路（SequenceDiagram）

解读：
每次调用均同步记录指标和链路信息，确保每个环节都可观测和溯源。

---

六、速记口与系统性认知总结

速记口

• 三步观测： 采集指标、链路追踪、日志输出
• 两类键： 低基数（聚合指标），高基数（详细追踪）
• 五大组件： ChatClient、ChatModel、EmbeddingModel、ImageModel、VectorStore
• 安全优先： 内容日志默认关闭，敏感数据需谨慎

系统性认知

Spring AI 可观测性能力，基于 Spring Boot Actuator + Micrometer + OpenTelemetry 构建，覆盖了从模型调用到向量存储的全链路性能监控与分布式追踪，支持主流 AI 服务和数据库，指标体系与 Prometheus 完美兼容，配置灵活，安全可控，是企业级 AI 应用不可或缺的基础设施。

---

参考文献

1. Spring AI Observability 官方文档
2. OpenTelemetry Semantic Conventions for Generative AI
3. Micrometer Naming Meters
4. Spring Boot Actuator 官方文档

---

Spring AI 可观测性，让你的 AI 系统不仅“会用”，更“可管、可控、可优化”！