前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

一、核心概念

1、什么是 Spring AI 可观测性

可观测性 = AI 系统的 “监控雷达”：让 AI 调用（聊天、嵌入、向量库、工具）全透明：耗时多少、用了多少 token、成功失败、调用了什么、在哪卡住。

1）监控干什么

• 指标（Metrics）：QPS、延迟、token 用量、调用次数

• 链路追踪（Tracing）：一次请求完整调用链（Chat → Embedding → VectorStore）

• 日志（Logging）：提示词、响应、报错信息

2）核心指标

• 调用耗时

• token 用量（input/output/total）

• 并发数

• 成功 / 失败率

• 向量库增删改查耗时

2、低基数 vs 高基数键

• 低基数 (Low Cardinality)：值是有限的、可枚举的。

  • 可用于监控图表 （Metrics）
  • 内容简单、数量少（如：模型名称、操作类型）

• 高基数 (High Cardinality)：值是无限的、唯一的。

  • 只用于追踪（Trace）
  • 内容长、数量多（如：提示词、响应文本、文档内容）
  • 默认关闭，避免性能 / 泄露问题

3、 观测点

• ChatClient：应用层调用（包含 Advisor 增强逻辑）。
• ChatModel：实际与大模型厂商（OpenAI, Azure 等）的交互。
• EmbeddingModel / ImageModel：向量和图像模型的调用。
• VectorStore：

4、配置建议

1. 开发 / 测试环境：全部 log-prompt / log-completion 开启，便于调试。
2. 生产环境：关闭提示 / 回复记录，避免敏感信息泄露与性能损耗。
3. 必开项：include-error-logging 与 token 指标，用于成本核算与问题定位。
4. 向量库：仅在调试时开启 log-query-response，生产关闭。
5. 暴露端点：生产建议只暴露 health,info,metrics，不要 *。

二、指标大全

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

1、聊天客户端指标

当调用 ChatClient 的 call() 或 stream() 操作时，会记录 spring.ai.chat.client 观测。它们测量执行调用所花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

3）配置项

spring:
  ai:
    chat:
      client:
        observations:
          log-prompt: true
          log-completion: true

2、 聊天客户端顾问 Advisor

当执行顾问时，会记录 spring.ai.advisor 观测。它们测量在顾问中花费的时间（包括在内部顾问中花费的时间）并传播相关的跟踪信息。

1）低基数键

2）高基数键

3、聊天模型

当调用 ChatModel 的 call 或 stream 方法时，会记录 gen_ai.client.operation 观测。它们测量方法完成所花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

4）聊天提示和完成数据

聊天提示和完成数据通常很大，可能包含敏感信息。因此，默认情况下不导出。

Spring AI 支持记录聊天提示和完成数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息，以便更好地进行关联。

spring:
  ai:
    chat:
      observations:
        log-prompt: true
        log-completion: true
        include-error-logging: true

4、工具调用

当在聊天模型交互的上下文中执行工具调用时，会记录 spring.ai.tool 观测。它们测量完成工具调用所花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

3）工具调用参数和结果数据

工具调用的输入参数和结果默认情况下不导出，因为它们可能包含敏感信息。

Spring AI 支持将工具调用参数和结果数据导出为 span 属性。

spring:
  ai:
    tools:
      observations:
        include-content: true

4、嵌入模型

当调用嵌入模型方法时，会记录 gen_ai.client.operation 观测。它们测量方法完成所花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

5、图像模型

当调用图像模型方法时，会记录 gen_ai.client.operation 观测。它们测量方法完成所花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

3）图像提示数据

图像提示数据通常很大，可能包含敏感信息。因此，默认情况下不导出。

Spring AI 支持记录图像提示数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息，以便更好地进行关联。

spring:
  ai:
    image:
      observations:
        log-prompt: true

6、 向量存储

Spring AI 中的所有向量存储实现都经过检测，通过 Micrometer 提供指标和分布式跟踪数据。

当与向量存储交互时，会记录 db.vector.client.operation 观测。它们测量在 query、add 和 remove 操作中花费的时间并传播相关的跟踪信息。

1）低基数键

2）高基数键

3）响应数据

向量搜索响应数据通常很大，可能包含敏感信息。因此，默认情况下不导出。

Spring AI 支持记录向量搜索响应数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息，以便更好地进行关联。

spring:
  ai:
    vectorstore:
      observations:
        log-query-response: true

三、实战案例

1、基础聊天观测 (ChatClient & ChatModel)

/**
 * 场景1：基础聊天观测 (ChatClient & ChatModel)
 * 演示如何获取 OpenAI 调用的详细指标
 */
@GetMapping("/chat")
public ChatResponse chat(@RequestParam String message) {
    // 1. 调用 ChatClient
    // 根据配置，如果 log-prompt=true，这里会记录 Prompt
    ChatResponse response = chatClient.prompt()
            .user(message)
            .call()
            .chatResponse();
    return response;
}

{
    "metadata": {
        "empty": false,
        "id": "",
        "model": "qwen3:14b",
        "promptMetadata": [],
        "rateLimit": {
            "requestsLimit": 0,
            "requestsRemaining": 0,
            "requestsReset": "PT0S",
            "tokensLimit": 0,
            "tokensRemaining": 0,
            "tokensReset": "PT0S"
        },
        "usage": {
            "promptTokens": 17,
            "completionTokens": 1000,
            "totalTokens": 1017
        }
    },
    "result": {
        "metadata": {
            "contentFilters": [],
            "empty": false,
            "finishReason": "length"
        },
        "output": {
            "media": [],
            "messageType": "ASSISTANT",
            "metadata": {
                "messageType": "ASSISTANT"
            },
            "text": "SpringAI 的可观测性**可能涉及以下核心价值和用途：\n\n---\n\n### **1. 监控 AI 模型的运行状态**\n在 Spring 应用中集成 AI 模型（如机器学习、大语言模型）时，",
            "toolCalls": []
        }
    },
    "results": [
        {
            "metadata": {
                "contentFilters": [],
                "empty": false,
                "finishReason": "length"
            },
            "output": {
                "media": [],
                "messageType": "ASSISTANT",
                "metadata": {
                    "messageType": "ASSISTANT"
                },
                "text": "SpringAI 是一个假设的概念（目前 Spring 官方并未推出名为 \"SpringAI\" 的项目），但如果我们从“Spring 生态”与“AI 可观测性”的结合角度来探讨，t ",
                "toolCalls": []
            }
        }
    ]
}