Spring AI应用系列——基于OpenTelemetry实现大模型调用的可观测性实践

一、项目背景与目标

在AI应用日益复杂的今天，大模型服务（如语言理解和生成）的性能监控和问题排查变得尤为关键。为了实现对大模型调用链路的可观测性（Observability）管理，我们基于 Spring Boot + Spring AI Alibaba + OpenTelemetry SDK 构建了一套完整的观测系统。

本文将从以下维度展开：

整体架构设计
核心原理与组件说明
可观测性相关参数配置规则与使用方法
测试验证结果对比

二、系统架构设计

1. 架构图概述

本系统主要由以下几个模块构成：

[客户端请求] → [JokeController]↓[ChatClient API]↓[DashScopeChatModel]↓[OpenTelemetry Trace Exporter]↓[OtlpFileSpanExporter]

2. 模块职责划分

组件名称	职责描述
`JokeController`	接收 HTTP 请求，调用 ChatClient 获取笑话
`ChatClient`	抽象了大模型交互接口，封装上下文处理逻辑
`DashScopeChatModel`	阿里云 DashScope 大模型的适配器
`ObservationRegistry`	提供 Observation 支撑用于记录 Span 和 Metrics
`OtlpFileSpanExporter`	将 Trace 数据以 OTLP 格式导出至日志系统

三、核心技术原理与参数配置详解

1. Spring AI 中的 Tracing 观察机制

Spring AI 借助 Micrometer Observations 实现了统一的观察数据采集机制，支持如下几个关键方面：

Trace ID & Span ID 的注入
Input / Output 内容记录
Prompt、Completion 等元信息采样

关键配置项：

spring.ai.chat.client.observations.include-input=true
spring.ai.chat.observations.include-completion=true
spring.ai.chat.observations.include-prompt=true

这些参数控制是否记录聊天过程中输入输出内容和提示词等上下文信息，用于后续调试或优化模型效果。

2. OpenTelemetry 参数配置

OpenTelemetry 通过 SPI 自动装配加载自定义的 SpanExporter，这里我们使用了 OtlpFileSpanExporter 来进行本地日志输出。

自定义导出器配置类（OtlpFileSpanExporterProvider）：

@Component
public class OtlpFileSpanExporterProvider implements ConfigurableSpanExporterProvider {@Overridepublic SpanExporter createExporter(ConfigProperties config) {return OtlpFileSpanExporter.create();}@Overridepublic String getName() {return "logging-otlp";}
}

该模块实现了自动注册机制，并返回一个自定义的 SpanExporter 实例。

3. Sampling 抽样率设置

对于生产环境，通常不会记录所有请求，而是按一定概率抽样。Spring Boot 提供如下配置项：

management.tracing.sampling.probability=1.0

表示开启全量采样，适用于开发阶段调试。生产建议设置为 0.1~0.5 之间。

四、测试验证与日志导出比对

1. 测试入口点 —— `/joke`

通过访问 /joke 接口，触发一次完整的 LLM 调用流程并打印追踪日志。

@GetMapping("/joke")
Map<String, String> joke() {var reply = chatClient.prompt().user("tell me a joke. be concise.").call().content();Span currentSpan = Span.current();return Map.of("joke", reply, "traceId", currentSpan.getSpanContext().getTraceId());
}

2. 日志输出结构（OTLP JSON）

OtlpFileSpanExporter 会将每个 Span 导出为类似如下结构的日志行：

{"resourceSpans": [{"resource": { "attributes": [ ... ] },"scopeSpans": [{"spans": [{"name": "chat.model","spanId": "...","traceId": "...","startTimeUnixNano": "...","endTimeUnixNano": "...","attributes": {"ai.request.input": "...","ai.response.output": "..."}}]}]}]
}