1. 为什么 AI 应用的可观测性比传统微服务更难做传统 Java 微服务接入 ARMS你关心的是 QPS、P99、HTTP 状态码、慢 SQL这些指标在 ARMS 控制台里天然就有。但一旦应用里开始调用大模型监控面板上会突然多出一类看不见的成本一次/chat请求背后可能消耗了 3000 个 Token模型返回慢是因为网络还是因为推理排队用户投诉答非所问时你根本不知道当时发出去的 Prompt 长什么样。我见过最典型的翻车场景客服机器人上线三天账单比预期高了四倍但 ARMS 上 HTTP 接口的 P99 只有 800ms看起来一切正常。问题出在模型调用这一层——某个上游业务把历史对话全量拼进了 Prompt单次输入从 500 Token 涨到了 6000 Token而传统监控完全看不到这个维度。这就是 AI 应用可观测性的核心差异调用链路上多了一个黑盒环节。你需要同时回答两类问题一类是传统问题接口是否健康、依赖是否超时另一类是 AI 特有问题Prompt 是什么、消耗多少 Token、模型参数是否合理、响应内容是否被截断。阿里云 ARMS 的 Java Agent 方案恰好能覆盖这两类需求。它通过字节码增强在 JVM 层面自动拦截 AI 调用不需要你改一行业务代码就能把 Prompt、Completion、Token 用量、模型名称这些信息作为 Span 属性上报。而当你把 AI 调用的凭证统一收敛到 TaoToken 的 Key/API 通道后Key 的使用情况、调用来源、模型分布也能在 ARMS 里形成完整的可观测闭环。这篇文章面向的是已经有 ARMS 环境、正在用 Java 写 AI 应用的开发者。我会给出可直接复制的 Java Agent 挂载参数、application.yml与settings.json骨架以及一套验证请求是否真正上报成功的动作。适合谁正在把 Spring Boot 应用接入大模型、又不想自己搭 Prometheus Jaeger 那一整套的团队。2. TaoToken 统一 Key 通道与 ARMS 的衔接方式在讲配置之前先把架构关系理清楚否则后面挂 Agent 参数时容易搞混谁在采集、谁在被采集。ARMS Java Agent 的角色是采集端它挂在你的业务 JVM 上负责拦截方法调用并生成 Span。TaoToken 的角色是被调用的 AI 通道你的应用通过它统一访问模型Key 和 Base URL 都指向 TaoToken。两者之间没有直接依赖——Agent 不关心你调的是哪家模型它只关心这里发生了一次 AI 调用。所以衔接点其实在配置层你的应用需要把 AI 客户端的 Base URL 指向 TaoToken 的 API 地址把 Key 换成 TaoToken 生成的统一 Key同时让 ARMS Agent 能识别这次调用是 AI 调用。识别靠的是 Spring AI 的观测埋点Agent 通过拦截ChatClient、ChatModel这些类的方法来生成 AI 专属 Span。这里有个容易踩的坑很多人以为挂了 Agent 就自动有 AI 数据其实还需要在依赖里引入spring-ai-alibaba-starter-arms-observation它负责把 Spring AI 的观测事件桥接到 OpenTelemetry 格式ARMS Agent 才能正确解析。少了这个 starter你只能看到 HTTP 层的 Span看不到 Prompt 和 Token。TaoToken 的接入信息如下后面配置里会反复用到官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址Base URLhttps://taotoken.net/api模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content统一 Key 的价值在于所有 AI 调用都走同一个出口ARMS 里按gen_ai.request.model和gen_ai.usage.input_tokens聚合时你能清楚看到哪个业务线、哪个接口在消耗 Token。如果每个服务各用各的 Key成本归因就会变成一团乱麻。需要提醒的是TaoToken 是合规的 API 聚合通道不是所谓的中转代理配置时直接把它当成标准的 OpenAI 兼容端点即可。Base URL 填https://taotoken.net/api不要加多余的路径后缀Spring AI 会自动拼接/v1/chat/completions。3. 可复制的 Java Agent 挂载参数与配置文件骨架这一节是全文的核心所有片段都可以直接复制到项目里。我按依赖 → 配置 → 启动参数的顺序给出路径和原文保持一致。3.1 Maven 依赖骨架dependencies !-- Web 入口触发整个调用链路 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Actuator暴露 /actuator/health 等端点K8s 存活检测依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency !-- Micrometer 到 OTel 的桥接Spring 生态用 MicrometerARMS 用 OTel -- dependency groupIdio.micrometer/groupId artifactIdmicrometer-tracing-bridge-otel/artifactId /dependency !-- 核心ARMS 可观测性 Starter自动拦截 AI 调用生成 Span -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-arms-observation/artifactId /dependency !-- 模型连接器封装 HTTP 调用提供 ChatClient API -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-dashscope/artifactId /dependency /dependencies3.2 application.yml 完整配置spring: application: name: observability-arms-taotoken # ARMS 控制台显示的应用名 ai: openai: # 关键Base URL 指向 TaoToken 统一通道 base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini chat: observations: log-prompt: true # 记录发给模型的 Prompt log-completion: true # 记录模型返回的 Completion include-error-logging: true client: observations: log-prompt: true log-completion: true management: endpoints: web: exposure: include: * endpoint: health: show-details: always tracing: sampling: probability: 1.0 # 开发环境 100% 采样 http: client: read-timeout: 60s3.3 settings.json 骨架用于本地工具链如果你用 Claude Code 或类似的编码工具做本地调试settings.json里需要把模型端点也指向 TaoToken保持和线上一致{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Bash, Read, Write] } }3.4 Java Agent 挂载参数这是最容易出错的一步。Agent 必须在-jar之前且路径要写对java \ -javaagent:./src/javaagent/AliyunJavaAgent/aliyun-java-agent.jar \ -Darms.licenseKey${ARMS_LICENSE_KEY} \ -Darms.appName${ARMS_APP_NAME} \ -Daliyun.javaagent.regionId${ARMS_REGION_ID} \ -jar ./target/observability-arms-example-1.0.0.jar三个-D参数缺一不可licenseKey决定数据上报到哪个 ARMS 实例appName决定控制台里的应用分组regionId决定上报端点。如果appName写错你会在控制台里看到两个应用数据被拆散。3.5 启动类里显式声明全局 OpenTelemetrySpringBootApplication public class ObservabilityApplication { public static void main(String[] args) { SpringApplication.run(ObservabilityApplication.class, args); } Bean public OpenTelemetry openTelemetry() { // 复用 ARMS Agent 在 premain 阶段初始化好的全局实例 // 不写这个 BeanSpring AI 会自己 new 一套导致 TraceId 传递中断 return GlobalOpenTelemetry.get(); } }这个 Bean 是很多链路断掉问题的根因。ARMS Agent 在 JVM 启动的 premain 阶段就已经建好了一套 OTel SDK如果 Spring AI 再自建一套两套体系的 TraceId 互不相认你在 ARMS 里只能看到孤立的 Span。4. 验证请求是否真正上报到 ARMS配置写完不代表数据就上去了必须做一次端到端验证。我按本地请求 → 日志确认 → 控制台确认三步走。4.1 发一个带 TraceId 回显的请求控制器里把当前 Span 的 TraceId 返回给客户端这样你能拿着这个 ID 去 ARMS 里精确检索RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/joke) public MapString, String joke() { var reply chatClient .prompt() .user(Tell me a joke. be concise.) .call() .content(); Span currentSpan Span.current(); String traceId currentSpan.getSpanContext().getTraceId(); return Map.of( joke, reply, traceId, traceId ); } }启动后执行curl http://localhost:8080/joke预期返回类似{ joke: Why dont scientists trust atoms? Because they make up everything!, traceId: abc123def4567890abc123def4567890 }4.2 日志侧确认 Agent 已加载# 确认 Agent 挂载成功 jps -lvm | grep javaagent # 确认 ARMS 相关日志出现 grep -i arms\|agent logs/application.log # 实时观察 TraceId 与错误 tail -f logs/application.log | grep -E (ARMS|traceId|ERROR)如果jps输出里看不到-javaagent参数说明启动命令写错了Agent 根本没加载后面所有配置都是白搭。4.3 ARMS 控制台确认拿到traceId后进入 ARMS 控制台的「调用链路」页面用 TraceId 检索。你应该能看到一条完整的链路HTTP GET /joke→ai.chat→HTTP POST /api/v1/chat/completions。点开ai.chat这个 Span属性里应该包含属性名含义预期值gen_ai.request.model请求的模型gpt-4o-minigen_ai.usage.input_tokens输入 Token约 10-20gen_ai.usage.output_tokens输出 Token约 20-40gen_ai.operation.name操作类型chat如果ai.chat这个 Span 不存在只有 HTTP Span说明spring-ai-alibaba-starter-arms-observation没生效回去检查依赖是否被正确引入。5. 本篇常见报错排查这一节按真实报错信息组织每条都给出定位思路。5.1 401 UnauthorizedHTTP 401 Unauthorized: {error:{message:Invalid API key}}这是最常见的错误。原因通常是TAOTOKEN_API_KEY环境变量没设置或者 Key 复制时带了空格。检查方式echo $TAOTOKEN_API_KEY | head -c 10如果输出为空说明环境变量没导出。注意 TaoToken 的 Key 以sk-开头配置时不要手动加引号YAML 里${TAOTOKEN_API_KEY}这种写法会自动读取环境变量。5.2 local proxy failed / connection refusedjava.net.ConnectException: Connection refused如果报错里出现local proxy failed说明你的 HTTP 客户端配置了本地代理但代理进程没起来。检查application.yml里是否有多余的proxy配置或者 JVM 启动参数里有没有-Dhttp.proxyHost。TaoToken 的 API 地址是公网可达的不需要任何代理配置。5.3 reading choices 相关解析错误com.fasterxml.jackson.databind.JsonMappingException: Cannot deserialize value of type java.util.ArrayList from Object value (token JsonToken.START_OBJECT)这类报错通常出现在响应解析阶段根因是 Base URL 配错了。比如把https://taotoken.net/api写成了https://taotoken.net/api/v1导致路径重复拼接成/api/v1/v1/chat/completions返回的不是标准 OpenAI 格式。正确写法就是https://taotoken.net/apiSpring AI 会自动补全。5.4 OAuth / 认证相关报错OAuth authentication failed: invalid_client如果你用的是 Claude Code 或 Codex 这类工具报 OAuth 错误说明它还在走默认的官方认证流程。需要在settings.json或auth.json里显式覆盖 Base URL 和 Key。Codex 的auth.json骨架{ base_url: https://taotoken.net/api, api_key: sk-your-taotoken-key, model: gpt-4o-mini }三件套必须齐全Base URL、Key、Model ID。少任何一个都会回退到默认认证。5.5 ARMS 控制台看不到应用如果应用启动了、日志也正常但 ARMS 控制台里找不到应用按顺序排查# 1. 确认 Agent 真的挂载了 jps -lvm | grep javaagent # 2. 测试上报端点连通性 curl -v https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com # 3. 确认 appName 和 licenseKey 没写错 echo $ARMS_APP_NAME echo $ARMS_LICENSE_KEY最常见的原因是appName里带了空格或特殊字符ARMS 会把它当成另一个应用。另外regionId要和你的 ARMS 实例所在地域一致杭州是cn-hangzhou北京是cn-beijing。5.6 TraceId 为空如果/joke返回的traceId是00000000000000000000000000000000说明当前没有活跃的 Span。检查两点一是启动类里有没有声明GlobalOpenTelemetry.get()那个 Bean二是management.tracing.sampling.probability是不是被设成了 0。6. 把统一 Key 用起来从验证到长期编码配置跑通之后下一步是让 TaoToken 的 Key 真正承担起统一入口的角色。这里给两个方向。第一个方向是成本归因。在 ARMS 里按gen_ai.request.model和service.name做聚合你能看到每个微服务消耗了多少 Token。如果发现某个服务的 Token 用量异常高回到它的 Prompt 构造逻辑里找原因——通常是历史对话没做截断或者把整个知识库塞进了上下文。第二个方向是长期编码与 Agent 场景。如果你在用 Claude Code 做日常开发把ANTHROPIC_BASE_URL指向 TaoToken 后所有编码会话的调用都会走同一个 Key配合 ARMS 的链路数据你能清楚看到哪些操作消耗大、哪些模型响应慢。需要长期跑 Agent 任务的话Coding Plan 比按量计费更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。验证模型是否可用可以直接在模型对话页试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。管理 Key 和查看用量在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。完整的接入参数说明在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说一个实测下来的经验ARMS 的采样率在开发环境设 1.0生产环境建议降到 0.1 到 0.3但对错误请求做条件采样保证异常链路 100% 保留。这样既不会因为全量上报拖慢应用又能在出问题时拿到完整现场。Token 消耗的告警阈值可以设在日均预算的 80%提前发现异常调用。