文档中心

全栈可观测平台

AI Agent 观测实践

Claude Code 链路监控

Claude Code 是 Anthropic 推出的编程专用 AI 智能体，依托终端原生运行，具备完整代码库全局解析、需求拆解规划、本地文件编辑、终端命令调用、自测修复闭环执行能力，可端到端完成编码、调试、重构、提 PR 等全流程开发任务，为研发提效、代码工程自动化场景提供完整智能执行能力。本文为您详细介绍如何将 Claude Code 的观测数据接入 APMPlus，并查看调用链路监控。

前提条件

已经安装 Claude Code，且可以正常运行 Claude 命令。

已经获取 Claude Code 接入所需参数配置中的信息。详细参数和获取方法如下：

配置项	是否必选	说明
--app-key	是	应用性能监控的认证信息。虽然认证信息 App Key 不区分接入的服务类型和数据采集方式，但不同工作区的认证信息 App Key 各不相同，获取方式参考：如何获取应用性能监控的认证信息 AppKey。
--region	是	服务接入的地域 ID，例如：cn-beijing。应用性能监控目前支持的地域信息参见：开服地域。
--service-name	是	服务名称，例如：claude-code-apmplus。服务在应用性能监控中的显示名称，可根据实际情况自定义服务名称。
--version	否	指定安装版本。默认 latest，也支持 0.1.0 或 v0.1.0。
--package-url	否	覆盖插件包下载地址，通常只在灰度或排障时使用。
--tos-base-url	否	覆盖对象存储根地址，默认使用正式发布地址。
--no-launchctl	否	macOS 环境中不写入 launchctl 环境变量，仅更新 Claude settings。

操作步骤

步骤一：Claude Code 接入

执行以下命令，在 ~/.claude 目录中安装 apmplus@apmplus-claudecode-plugin 插件。

说明

若需要升级或重新安装 apmplus@apmplus-claudecode-plugin 插件，重复执行安装命令即可。

安装最新版本的示例代码如下：

curl -fsSL "https://apmplus-claudecode-plugin.tos-cn-beijing.volces.com/install.sh" | bash -s -- \
--region "cn-beijing" \
--app-key "your-appKey" \
--service-name "your-service-name"

安装指定版本的示例代码如下：

curl -fsSL "https://apmplus-claudecode-plugin.tos-cn-beijing.volces.com/install.sh" | bash -s -- \
--region "cn-beijing" \
--app-key "your-appKey" \
--service-name "claude-code" \
--version "0.1.0"

安装完成后，重启 Claude Code，使配置生效。

在 Claude Code 中发起一次新对话或工具调用，检查脚本输出或配置结果，存在以下情况表示安装成功。

安装脚本输出 APMPlus Claude Code Plugin installation complete，且 claude plugin 能识别 apmplus@apmplus-claudecode-plugin 插件。

~/.claude/settings.json中存在由 Region 与 appKey 生成的 APMPlus endpoint、service name 与 preload 路径。

前往 APMPlus 查询对应 service.name 的 Trace 数据，新会话产生的 Trace 中，服务名与安装参数一致。

步骤二：查看可观测数据

前往服务列表，可通过服务名搜索已经接入的 Claude Code。

单击服务名称，进入服务详情页，在 Trace 分析页面查看 Claude Code 服务对应的 Span 列表。

单击目标 Trace ID，切换到 LLM 数据或属性页签，可查看本次请求的详细信息。

切换到 Trace 完整日志页签，可查看 Claude Code 运行过程的详细日志。

常见问题

若插件安装和使用过程可能遇到以下情况，可根据处理建议进行解决。

问题现象	处理建议
提示 --region, --app-key and --service-name are required	安装命令缺少必填参数，补充 --region、--app-key 和 --service-name 后重试。
提示 --endpoint is no longer supported	请勿手动上传 endpoint，调整为上传 --region 和 --app-key，由安装脚本自动拼接。
提示 --region should be a region id	--region 只需要填写 Region ID，例如 cn-beijing。无需填写完整 URL，也无需带 apmplus- 前缀。
提示 --app-key should be the appKey only	--app-key 只填写 appKey，无需填写完整 URL 或 endpoint。
提示 claude command is required	本机未安装 Claude Code 或 Claude 不在当前 shell 的 PATH 中。
下载插件包失败	检查网络是否可访问对象存储域名，或使用 --package-url 指向可访问的插件包地址。
APMPlus 没有 Trace	确认 Claude Code 已重启，并检查 region、appKey、service name、网络出口和 APMPlus 查询时间范围。
macOS 重启后环境未生效	重新执行安装命令，或不带 --no-launchctl 参数，让脚本同步写入 launchctl 环境。

最近更新时间：2026.06.29 16:00:02

这个页面对您有帮助吗？

有用

无用