Spring AI Alibaba与云平台ARMS集成：智能体应用的全链路追踪实践

在企业级智能体（Agent）应用开发中，你是否经常遇到这些痛点：模型调用延迟难以定位？多智能体协作流程黑盒化？用户提问到回答的全链路无法追溯？Spring AI Alibaba与云平台ARMS（Application Real-Time Monitoring Service，应用实时监控服务）的深度集成，通过自动化埋点和分布式追踪能力，让智能体应用的观测变得简单高效。本文将带你从零开始实现智能体应用的全链路追踪，解决生产环境中智能体可观测性的核心难题。

为什么智能体应用需要全链路追踪？

智能体应用与传统软件的最大区别在于其非线性执行流程和外部依赖复杂性。一个典型的多智能体应用可能涉及：

  • 多次大语言模型（LLM）调用（如通义千问、GPT系列）
  • 工具调用链（如数据库查询、API请求、MCP服务调用）
  • 多智能体协作（如规划智能体、执行智能体、评估智能体）
  • 持久化存储交互（如会话记忆、知识库检索）

这些环节的任何延迟或错误都可能导致整个智能体响应异常。根据Spring AI Alibaba官方文档README-zh.md的描述，企业级智能体落地的核心挑战之一就是可观测性，而ARMS集成正是解决这一问题的关键方案。

Spring AI Alibaba架构

全链路追踪能解决的3个核心问题

  1. 性能瓶颈定位：通过追踪每个环节耗时（如模型调用耗时、工具执行耗时），快速定位性能瓶颈
  2. 异常溯源：当智能体回答错误或超时，可通过追踪数据还原完整调用链，定位根因
  3. 成本优化：统计模型Token消耗、API调用次数，为资源优化提供数据支持

技术原理：Spring AI Alibaba与ARMS的无缝集成

Spring AI Alibaba通过两个核心模块实现与ARMS的集成：

1. 观测扩展模块：spring-ai-alibaba-observation-extension

该模块位于spring-ai-alibaba-observation-extension/，提供了ARMS的具体实现。从其POM文件spring-ai-alibaba-observation-extension/pom.xml可以看到，它依赖于Spring AI的核心观测接口和Micrometer Tracing：

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-model</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2. 自动配置模块：spring-ai-alibaba-autoconfigure-arms-observation

该模块位于auto-configurations/spring-ai-alibaba-autoconfigure-arms-observation/，通过Spring Boot自动配置机制，实现ARMS追踪的"零代码侵入"。其POM文件auto-configurations/spring-ai-alibaba-autoconfigure-arms-observation/pom.xml显示，它依赖于核心模块和观测扩展模块：

<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-core</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-observation-extension</artifactId>
    </dependency>
</dependencies>

数据流转流程

Spring AI Alibaba与ARMS的集成遵循OpenTelemetry规范，数据流转流程如下：

mermaid

实战：5分钟实现智能体应用全链路追踪

环境准备

开始前请确保：

  • JDK 17+（参考README.md的环境要求）
  • Spring AI Alibaba 1.0.0.3+
  • 云平台ARMS账号（免费试用可参考云平台官方文档）

步骤1：添加依赖

在pom.xml中添加ARMS starter依赖。首先引入Spring AI Alibaba BOM：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.0.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后添加ARMS starter：

<dependencies>
    <!-- ARMS观测依赖 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-arms-observation</artifactId>
    </dependency>
    <!-- 基础智能体依赖 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    </dependency>
</dependencies>

步骤2：配置ARMS

在application.properties中添加ARMS配置：

# ARMS应用名称（必填）
spring.application.name=spring-ai-agent-demo
# ARMS服务端点（根据地域选择，例如杭州）
management.otlp.tracing.endpoint=https://tracing-analysis-dc-hz.aliyuncs.com/adapt_f860e65f0b684e9dba8bfa55@******/api/traces
# 采样率（开发环境1.0，生产环境可调整为0.1）
management.tracing.sampling.probability=1.0

注意：ARMS服务端点和认证信息需从云平台ARMS控制台获取，详细步骤可参考云平台官方文档。

步骤3：开发带追踪能力的智能体

创建一个简单的对话智能体，Spring AI Alibaba会自动为其添加追踪埋点：

import com.alibaba.cloud.ai.dashscope.DashScopeChatClient;
import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AgentController {

    @Autowired
    private DashScopeChatClient chatClient; // 自动注入带追踪能力的客户端

    @GetMapping("/chat")
    public String chat(@RequestParam String question) {
        // 自动追踪：UserMessage创建、模型调用、响应处理
        ChatResponse response = chatClient.call(new UserMessage(question));
        return response.getResult().getOutput().getContent();
    }
}

步骤4：运行与查看追踪数据

启动应用后，访问http://localhost:8080/chat?question=Spring AI Alibaba是什么，然后登录云平台ARMS控制台：

  1. 在"应用列表"中找到你的应用：名称为spring-ai-agent-demo
  2. 查看调用链：在"分布式追踪"页面，搜索traceID或按时间筛选
  3. 分析性能数据：在"应用监控"→"性能分析"中查看各环节耗时

ARMS追踪示例

高级特性：自定义追踪维度

Spring AI Alibaba允许开发者添加自定义追踪维度，例如智能体类型、用户ID等。通过ObservationContext扩展实现：

import io.micrometer.tracing.Tracer;
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class CustomTraceAgent {

    private final ChatClient chatClient;
    private final Tracer tracer;

    @Autowired
    public CustomTraceAgent(ChatClient chatClient, Tracer tracer) {
        this.chatClient = chatClient;
        this.tracer = tracer;
    }

    public String chatWithTrace(String question, String userId) {
        // 添加自定义Span
        try (var span = tracer.nextSpan().name("custom-agent-chat").start()) {
            // 添加自定义标签
            span.tag("agent.type", "qa-bot");
            span.tag("user.id", userId);
            
            // 模型调用（会自动继承当前Span上下文）
            ChatResponse response = chatClient.call(new UserMessage(question));
            
            // 添加结果标签
            span.tag("response.status", "success");
            return response.getResult().getOutput().getContent();
        }
    }
}

添加自定义维度后，可在ARMS控制台通过这些维度进行筛选和聚合分析，例如统计不同用户群体的智能体使用情况。

最佳实践与注意事项

1. 采样率配置

  • 开发/测试环境：management.tracing.sampling.probability=1.0（全量采样）
  • 生产环境：根据QPS调整，建议0.1~0.5，避免大量追踪数据影响性能

2. 敏感信息过滤

智能体对话可能包含敏感信息，可通过ARMS的数据脱敏功能配置：

# 对"content"字段进行脱敏
arms.trace.data.masking.fields=content
# 脱敏规则：保留前3后4字符，中间用*代替
arms.trace.data.masking.pattern=(\w{3})\w*(\w{4})
arms.trace.data.masking.replacement=$1****$2

3. 与MCP服务追踪联动

当智能体调用MCP（Model Control Plane）服务时，确保MCP服务也已集成ARMS，实现端到端追踪。Spring AI Alibaba的MCP模块spring-ai-alibaba-mcp/已内置追踪支持，无需额外配置。

4. 告警配置

在ARMS控制台配置关键指标告警，例如：

  • 模型调用耗时>500ms
  • 工具调用失败率>1%
  • 智能体整体响应时间>2s

总结与展望

Spring AI Alibaba与云平台ARMS的集成，为智能体应用提供了开箱即用的全链路追踪能力。通过本文介绍的方法，你已掌握：

  • 智能体应用全链路追踪的核心价值
  • Spring AI Alibaba与ARMS集成的技术原理
  • 5分钟实现追踪的完整步骤
  • 自定义追踪维度和最佳实践

随着智能体应用复杂度的提升，可观测性将成为企业级应用的必备能力。Spring AI Alibaba社区正在持续增强观测能力，未来将支持更多AI-specific指标（如Token消耗统计、RAG检索相关性评分）。

立即访问Spring AI Alibaba代码仓库，开启企业级智能体开发之旅！如果你觉得本文有帮助，欢迎点赞收藏，关注Spring AI Alibaba社区获取更多最佳实践。

Logo
ModelEngine社区

更多推荐

从崩溃到自愈：Temporal+MCP-Agent构建永不中断的AI工作流

你是否遇到过AI工作流执行到90%突然崩溃的绝望？训练了数小时的模型因服务器重启前功尽弃？团队协作时因某人未及时审批导致整个流程停滞？本文将展示如何通过Temporal与MCP-Agent的深度集成，彻底解决这些痛点，构建真正企业级的可靠AI工作流系统。读完本文你将掌握：- 3行代码实现工作流故障自愈- 零停机升级正在运行的AI任务- 跨团队协作的工作流信号机制- 从本地开发到生产集群

avatar ModelEngine社区
cover

从"数据喂养"到"数据工程"：大模型时代的数据哲学

avatar ModelEngine社区
cover

GPU 虚拟化：从理论到落地（一）三维正交坐标系讲透分类

avatar ModelEngine社区