使用OpenTelemetry实现Claude Code的可观测性

注意：尽管本指南中的示例是针对单用户环境进行的配置，但实际上在部署采集器时，系统通常会包含多个后端。由于这些后端的存储和查询方式可能不同，因此让采集器接收来自所有数据生产者的数据，然后再将它们分别转发到相应的后端，要比直接为每个应用程序连接三个后端更为简便。正因为如此，对于个人使用来说，收集器可能是可选的；但在生产环境中，它绝对是必不可少的——随着数据生产者数量和后端数量的增加，收集器的价值会变得更加显著。

先决条件

本指南的每一部分都会提供相关文档的链接，但如果您已经熟悉以下工具和查询语言，那么学习进程将会更加顺利：

您需要准备以下内容：

• Claude Code的最新版本

• Docker Engine（29.4.1及以上版本），以及Docker Compose。

  • 至少需要5个容器的运行能力（4核CPU、8GB内存、15GB硬盘空间）

• 一个包含增强型遥测功能测试版的Claude Plan（Pro+或Max套餐）

• Git

• 请确保本地主机上的以下端口是空闲的：

  • 3000（用于Grafana)

  • 3100（用于Loki)

  • 4317/4318（用于OTel Collector的OTLP协议，支持gRPC和HTTP接口）

  • 9090（用于Prometheus)

  • 16686（用于Jaeger UI)

还有一些知识也会对您有所帮助：

• Docker Compose：如何使用docker compose ...命令来启动compose文件中定义的容器，以及查看容器的状态和日志。

• Bash

  脚本及配置文件：如何设置环境变量，以及如何编辑JSON格式的文件。

• PromQL

  语言：如何使用计数器/仪表盘、范围选择器，以及sum、increase、rate和by（基于标签的分类）等功能。

• Grafana：如何探索数据源，使用统计信息和时间序列图表来构建仪表板；同时了解如何对面板数据进行转换操作，以及如何使用全局变量。

• LogQL

  语言：如何使用流选择器、logfmt格式和label_format功能来处理日志数据。

• Jaeger与追踪系统：了解trace/span模型（包括父子span关系、跨度数量及持续时间等概念），以及Jaeger UI中的标签搜索功能。

• Claude Code的执行机制：会话管理、子代理的使用、技能配置、工具选择，以及数据压缩技术。

• Claude的计费机制：了解令牌的概念，以及提示缓存分级制度。

设置

测试用可观测性组件是通过Docker Compose来部署的。为了使遥测数据能够被正确导出，Claude Code必须能够访问位于同一台机器上的Collector的OTLP端点：当在同一台机器上运行时，该端点的地址为localhost:4317（使用gRPC协议）或localhost:4318（使用HTTP协议）。所有的后端服务都运行在容器中，并且各自拥有独立的Docker卷用于数据持久化存储。

该图示展示了我们所使用的各类遥测组件是如何相互连接的。

• 除了Claude Code之外，所有其他组件都是通过Docker Compose管理的容器来运行的。

• 只要任何一台机器（无论是本地主机还是云虚拟机）上运行的Claude Code实例能够与Collector建立连接，那么这些实例就都能够将遥测数据导出给Collector。具体来说，运行 Collector容器的那台机器的4317/4318端口必须是可访问的。

从上到下的逻辑流程如下：

• Claude Code会通过OTLP协议将三种类型的遥测数据都导出给Collector。

• 随后，Collector会将这些数据按类型进行分类：将追踪数据发送到Jaeger，将日志数据发送到Loki，同时会在8889端口上暴露指标数据，以便Prometheus能够对这些数据进行抓取。

• Jaeger、Prometheus和Loki各自会将处理后的数据存储在各自的Docker卷中。

• Grafana会将这些数据整合起来，形成一个统一的仪表盘界面供用户查询。

我们的目标是实现这样一种机制：让Claude Code生成的遥测数据能够实时被传输到后端存储系统中，并且可以在需要时随时进行查询——无论是在会议进行期间，还是会议结束后很长时间。为此，必须满足以下两个条件：

• 首先需要在Claude Code中启用遥测功能。虽然相关的监测工具已经被内置在了代码中，但只有在启用了遥测功能并且将其OTLP导出器配置为指向Collector之后，这些数据才会被真正发送出去。

• 其次，必须运行后端服务。Collector会负责处理接收到的所有遥测数据，并将其转发给Prometheus、Loki和Jaeger进行进一步存储或查询处理。

你需要先启动后端服务，这样遥测数据才会有地方被存储和处理。

启动可观测性后端服务

在启用Claude Code的遥测功能之前，请确保整个系统已经能够正常收集、处理和读取数据。测试用可观测性后端的代码保存在这个Github仓库中。

该仓库的结构如下：

.
├── README.md
└── compose
    ├── docker-compose.yml # 用于配置可观测性组件堆栈中的5个容器的Docker配置文件。其中指定了各服务的镜像版本、端口映射以及命名卷设置。
    ├── grafana
    │   └── provisioning
    │       ├── alerting
    │       ├── dashboards
    │       ├── datasources # 包含Prometheus、Loki和Jaeger的数据源配置，以及仪表盘相关设置。初始状态下这些目录是空的。
    │       └── plugins
    ├── jaeger-config.yaml # Jaeger v2的配置文件，规定了追踪数据的存储方式（使用本地文件系统）。注意：此配置与root用户账户有关。
    ├── loki-config.yaml # Loki的配置文件，采用了简单的文件系统存储方式。配置参数基本为默认值。
    ├── otel-collector-config.yaml # 定义了数据接收、处理和导出的流程：遥测数据通过4317/4318端口进入系统，追踪数据被发送到Jaeger，日志数据被保存到Loki，而指标数据则会在8889端口上暴露出来供Prometheus抓取。
    └── prometheus.yml # 定义了针对Collector的8889端口的定期数据抓取任务，抓取间隔为30秒。

您只需要使用docker compose命令即可启动这些容器。该命令会读取docker-compose.yml文件，然后启动相应的容器，并将它们与各自的配置文件关联起来。

容器之间的连接性：

所有容器都在同一个Docker网络中运行，因此它们可以直接使用容器名称进行通信。例如，在collector的配置文件中，就使用了容器名称：

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true
  prometheus:
    endpoint: 0.0.0.0:8889
  otlphttp/loki:
    endpoint: http://loki:3100/otlp

需要注意的是，该配置文件中并不包含Prometheus的配置信息，因为Prometheus实际上会从collector那里获取这些数据，具体配置方式详见prometheus.yml文件：

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: otel-collector
    staticconfigs:
      - targets: ["otel-collector:8889"]

使用Docker compose来启动这些容器：

git clone https://github.com/ps-mir/otel-dev-stack.git
cd otel-dev-stack/compose
docker compose up -d

# 输出结果
✔ Volume compose_loki_data                          已创建                                                                                                                                          0.0秒
✔ Volume compose_grafana_data                       已创建                                                                                                                                          0.0秒
✔ Volume compose/prometheus_data                    已创建                                                                                                                                          0.0秒
✔ Volume compose_jaeger_data                        已创建                                                                                                                                          0.0秒
✔ Network compose_default                           已创建                                                                                                                                          0.1秒
✔ Container compose-prometheus-1                    已启动                                                                                                                                          4.1秒
✔ Container compose-loki-1                          已启动                                                                                                                                          4.2秒
✔ Container compose-jaeger-1                        已启动                                                                                                                                          4.3秒
✔ Container compose-otel-collector-1                已启动                                                                                                                                          3.3秒
✔ Container compose-grafana-1                       已启动                                                                                                                                          2.7秒

检查容器状态：

# 所有五个服务都应该显示为“Up”状态
docker compose ps

# 输出结果
NAME                       IMAGE                                              COMMAND                  SERVICE          CREATED         STATUS         PORTS
compose-grafana-1          grafana/grafana:13.2.0                            "/run.sh"                grafana          3分钟前   Up 3分钟   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
compose-jaeger-1           cr.jaegertracing.io/jaegertracing/jaeger:2.20.0   "/go/bin/jaeger --co…"   jaeger           3分钟前   Up 3分钟   0.0.0.0:16686->16686/tcp, [::]:16686->16686/tcp
compose-loki-1             grafana/loki:3.7.6                                "/usr/bin/loki -conf…"   loki             3分钟前   Up 3分钟   0.0.0.0:3100->3100/tcp, [::]:3100->3100/tcp
compose-otel-collector-1   otel/opentelemetry-collector-contrib:0.159.0      "/otelcol-contrib --…"   otel-collector   3分钟前   Up 3分钟   0.0.0.0:4317-4318->4317-4318/tcp, [::]:4317-4318->4317-4318/tcp, 55679/tcp
compose-prometheus-1       prom/prometheus:v3.11.2                           "/bin/prometheus --c…"   prometheus       3分钟前   Up 3分钟   0.0.0.0:9090->9090/tcp, [::]:9090->9090/tcp

提示： Jaeger在运行时会以root用户的身份创建badger目录。如果不这样做，就会出现“权限不足”的错误：mkdir /badger/key: permission denied。虽然Jaeger本身不需要root权限，但Docker卷在首次挂载时会被设置为root:root所有。

启用遥测功能

一旦将OpenTelemetry监控工具添加到应用程序中，该功能会处于禁用状态，直到通过特定配置将其启用为止。

在Claude Code中，有两种方法可以启用遥测功能：

1. 使用环境变量

设置相应的环境变量即可启用遥测功能的生成。除了标准的OTEL_*变量外，Claude Code还定义了自己的CLAUDE_CODE_*变量。

本指南使用以下配置：

# 默认设置：如果未设置或值为0，Claude Code不会生成任何遥测数据
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 启用beta版本的增强型遥测功能及相关属性和事件记录
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

# 选择具体的信号导出方式；"otlp"表示通过OTLP协议传输数据
# 其他可选值包括"console"（在本地显示数据）、"prometheus"（仅输出指标数据）以及"none"（不传输任何数据）
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp

# OTLP传输协议："grpc"表示通过4317端口传输数据；"http/protobuf"则使用4318端口
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# 所有三种信号的统一接收端点：本地机器上收集器的OTLP监听器地址
export OTEL_EXPORTER.otLP_ENDPOINT=http://localhost:4317

# 指标数据更新的频率，单位为毫秒；默认值为60000毫秒（即60秒）
# 为了便于手动检查，这里将更新间隔设置得较短
export OTEL_METRIC_EXPORT_INTERVAL=5000

# 输出累积计数值而非差分值（详见下文“数据聚合方式”部分）
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

然而，环境变量是整个进程范围内有效的，因此它们可能会影响不仅仅是Claude Code。例如：

• 可能会在其他应用程序中无意中启用数据采集功能。

• 如果你在自行开发数据采集模块或使用任何OpenTelemetry SDK，就可能会干扰OpenTelemetry的相关代码或测试流程。

2. Claude Code的`settings.json`文件

OpenTelemetry定义了基于YAML格式的声明式配置机制，用于启用数据采集功能，但Claude Code并不支持这种配置方式。不过，你仍然可以在`~/.claude/settings.json`文件中设置相应的环境变量。虽然这不属于声明式配置，但它比shell环境变量更有效，因为这些变量仅适用于Claude Code。举个例子：

{
  "effortLevel": "medium",
  "tui": "fullscreen",
  "env": {
     "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
     "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
     "OTEL_METRICS_EXPORTER": "otlp",
     "OTEL_LOGS_EXPORTER": "otlp",
     "OTEL_TRACES_EXPORTER": "otlp",
     "OTELEXPORTER_OTLP_PROTOCOL": "grpc",
     "OTEL_EXPORTER_otLP_ENDPOINT": "http://localhost:4317",
     "OTEL_METRIC-export_INTERVAL": "5000",
     "OTEL_EXPORTER.otLP_metRICS_TEMPORALITY_PREFERENCE": "cumulative"
  }
}

对于数据采集功能而言，只有`env`块中的设置才具有实际意义。`effortLevel`和`tui`则是与数据采集无关的配置选项，你可能已经设置了这些选项。上述环境变量名称与OpenTelemetry规定的名称是一致的。

聚合时间范围

Prometheus中属于计数器类型的指标其数值只会随时间不断增加。因此，直接查看这些指标的原始值是没有意义的，通常需要通过计算每秒的增长幅度（`rate()`）或某个时间窗口内的总增长量（`increase()`）来分析它们。

“聚合时间范围”决定了在每次数据导出时，计数器会报告哪些数值：是自上次导出以来的变化量（Delta），还是从进程启动以来的累计值（Cumulative）。

举个简单的例子。假设Claude Code在四个5秒钟的时间间隔内消耗代币：

默认情况下，Claude Code会以`AggregationTemporality: Delta`的方式生成指标数据。你可以通过以下命令在收集器的容器日志中查看这一设置：

# 该命令仅适用于包含docker-compose.yml文件的目录
docker compose logs otel-collector

注意：若要在Collector中启用详细日志记录，您需要将debug导出器添加到Collector配置文件中。

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger, debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus, debug]

然后重新启动容器：

# 该命令仅能在包含docker-compose.yml文件的目录中执行
docker compose up -d --force-recreate otel-collector

当使用AggregationTemporality: Delta进行日志输出时，日志格式如下：

otel-collector-1  | 描述符:
otel-collector-1  |      -> 名称：claude_code.active_time.total
otel-collector-1  |      -> 描述：总活跃时间（以秒为单位）
otel-collector-1  |      -> 单位：秒
otel-collector-1  |      ->> 数据类型：求和
otel-collector-1  |      ->> 是否单调递增：true
otel-collector-1  |      ->> 聚合时间范围：Delta <---
otel-collector-1  | 数值数据点数量 #0

对于Prometheus提供的rate()/increase()等函数而言，Delta时间范围并不适用，因为这些函数期望接收累积值。

将OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative这个配置项设置为“cumulative”，就可以使导出的指标数据采用累积时间范围进行计算。本指南中既在环境变量设置中提到了这一点，也在JSON配置文件中进行了说明。

与之前一样，任何配置更改后都需要重新启动Collector容器，才能让新的配置生效。

探索遥测数据

一旦遥测数据开始流动，您就可以开始对这些数据进行分析查询了。指标数据、日志记录以及跟踪信息分别能够帮助我们了解Claude Code的使用情况，因此以下这三个部分在功能上是相对独立的。

这些数据来源于两个途径。

• “指标数据”和“日志记录”这两个部分会显示后端系统中累积的Claude Code使用数据，因此您看到的数据会反映您自己实际进行的操作，而这些数值可能与截图中的内容不一致。在看到有明显的结果之前，请先进行几次真实的操作。

• 而“跟踪信息”部分则会展示一次特定的操作流程——这种自定义生成的流程能够详细地反映一系列会议的执行过程，您无需重新执行这些操作即可查看相关数据。

指标数据

指标数据是对Claude Code使用情况进行的汇总分析，它是按照特定时间窗口进行统计得出的结果。例如，总成本、token的使用量，以及这些数值随模型、工作难度或token的类型等属性的变化趋势等。利用这些指标数据，您可以监控使用情况并及时发现消费模式中的变化。

每一项指标数据都是随着时间推移而记录下来的数值，它们属于时间序列数据，您可以对这些数据进行绘制或汇总分析。Claude Code的指标数据都是累计值，因此查询结果反映的是在指定时间窗口内的变化情况，而非原始数值。具体原理请参见上文聚合时间范围部分。

Prometheus正是我们在这里使用的指标后端工具。它负责从数据收集器中获取数据、存储这些指标信息，并能够响应使用PromQL编写的查询请求。Grafana会从localhost:3000这个地址读取相同的数据，用于生成仪表板界面。所有指标及其属性的完整列表可以在Claude Code监控文档中找到。

在浏览器中打开Prometheus（地址为localhost:9090），在查询框中输入claude，你应该能看到所有被支持的指标：

对于下面列出的每一个指标，你首先会使用PromQL来查询这些数据，然后会用同样的查询语句将这些数据添加到Grafana仪表板中作为面板显示。

总支出金额（美元）

claude_code_cost_usage_USD_total这个指标表示每次会话中累计产生的使用成本，单位为美元。这个指标对于控制预算以及发现使用量突然增加的情况非常有用。

这个数值是基于Anthropic提供的按模型、按类型计价的令牌数量计算得出的。因此，它的数值有时会超过你购买的Claude Code套餐的订阅费用，这是完全正常的。

注意：如果你是按照每次API调用的次数来付费的话，这个指标就显得尤为重要了。而订阅服务会为你提供一定的使用额度，并且会设置更高的但有限的速率限制。

sum(increase(claude_code_cost_usage_USD_total[10m]))

increase(...[10m])这个表达式用于计算过去10分钟内该指标的增长情况。sum(...)如果没有by子句，那么所有基于不同属性的统计数据（如model、effort等）都会被合并成一个数值。

sum(increase(claude_code_cost_usage_USD_total[$__range]))

如果想要将这些数据添加到Grafana仪表板中作为面板显示，可以先在Prometheus中测试上述查询语句，然后选择“Explore”功能，将数据源设置为Prometheus，并运行该查询。最终显示的结果会取决于你在指定时间范围内实际使用了多少Claude Code服务。

在将这个指标添加到仪表板后，你会看到更多的面板设置选项。请选择Stat面板来显示这些数据。

需要将此面板添加到Grafana仪表板中。

总代币使用量

claude_code_token_usage_tokens_total表示累计代币数量，其统计格式与“美元成本”指标相同。首先需要在Prometheus中查看原始数据序列，以确定可以按哪些标签进行汇总分析。单个数据序列的示例如下：

claude_code_token_usage_tokens_total{effort="high", exported_job="claude-code", instance="otel-collector:8889", job="otel-collector", model="claude-sonnet-5", otel_scope_name="com.anthropic.claude_code", otel_scope_version="2.1.252", query_source="auxiliary", session_id="e0b9795b-4da3-4171-8fa6-a2866bf44d86", terminal_type="ssh-session", type="cacheCreation"} 213730

末尾的数字即为统计结果。您需要重点关注的属性包括type、model和effort。下方的按类型划分的代币使用情况图表就是按照type进行分类展示的。

“窗口总计”这一指标的统计格式与总美元支出指标相同，其计算公式为：

sum(increase(claude_code_token_usage_tokens_total[$__range]))

每美元对应的代币数量

与前两个指标不同，这个数值是通过将“总代币数量”除以“总成本”计算得出的。

sum(increase(claude_code_token_usage_tokens_total[$__range])) / sum(increase(claude_code_cost_usage_USD_total[$__range]))

这个数值会将所有不同的属性组合合并为一个最终结果。例如，模型A在中等努力程度下的使用情况与模型B在高努力程度下的使用情况分别属于不同的数据序列，而查询结果会汇总这些数据。

如果要分析特定的属性组合，可以按该属性对数据进行分组后再进行计算比较。

sum by (model) (increase(claude_code_token_usage_tokens_total[$__range])) / sum by (model) (increase(claude_code_cost_usage_USD_total[$__range]))

只需将model替换为effort或type即可；上述原始数据序列中还列出了其他可使用的标签。

最终分析结果：

统计面板（6小时时间窗口）显示：总美元支出为4.28美元，总代币使用量为302万，每美元对应的代币数量为70.7万。

按类型划分的代币使用情况

您可以看到claude_code_token_usage_tokens_total这一指标随时间的变化情况，并且这些数据是按照type进行分类展示的。单独查看一个统计数值会掩盖其变化趋势，因此建议使用时间序列面板来进行分析。

type属性有四种取值，这些取值在成本上存在显著差异：

• cacheRead：从现有缓存中获取的令牌。在较长的会话过程中，这类令牌的使用量占主导地位，其成本也低于基准费率。

• cacheCreation：在首次加载数据时写入提示缓存的令牌。这类操作的成本较高。

• input：新的、未缓存的提示令牌。

• output：模型生成的令牌。

若想查看总计数值，可以同时使用两种查询方式：一种是按类型进行细分统计，另一种则是获取未分类的总计结果以供参考。

# 按类型细分统计
sum by (type) (increase(claude_code_token_usage_tokens_total[$__rate_interval]))
# 总计
sum(increase(claude_code_token_usage_tokens_total[$__rate_interval]))

__rate_interval是Grafana用于时间序列图表的逐步时间间隔设置，与上面用于统计图表的__range参数的作用类似。

在将这两个查询结果保存为图表之前，先在Grafana的浏览界面中运行它们。

将其添加到仪表板后：

每条曲线上的峰值代表Claude Code系统的短暂高负荷运行状态，而平缓的部分则表示系统处于空闲状态。将鼠标悬停在某一点上，可以查看该时间段内四种类型的令牌使用情况：此处总计约有100万令牌，其中cacheRead类型占约92.5万令牌，其余为cacheCreation、output和input类型。

提示：令牌消耗量主要由cacheRead类型决定，而且这种类型的成本也是最低的。

按模型与工作强度划分的令牌使用情况

这就是“每美元令牌消耗量”这一统计指标的具体体现：哪些模型和工作强度组合实际上会消耗最多的令牌。

sum by (model, effort) (
  increase(claude_code_token_usage_tokens_total[$__rate_interval])
)

在这里，令牌使用量是按照模型和工作强度这两个属性进行分类统计的。在这个示例中，所有数据都对应于claude-sonnet-5模型，在medium或high工作强度下运行；其中在18:13左右出现的一次medium强度运行过程产生了约260万令牌的消耗量。不同分类组合的数量取决于所选属性的取值范围大小。

日志

日志记录是一种带有时间戳的事件记录，其中会包含所有相关的字段信息。当你需要了解某次具体事件的发生情况以及其背景信息时，就可以查询这些日志——比如发生了什么、何时发生的、涉及哪些数值等等。

指标则是同一类数据的预先聚合结果。任何需要进行计数、求和或计算百分位数的操作都属于指标的范畴。如果你在后续处理过程中对日志数据进行了汇总分析，那么这些数据从一开始就应该被视作指标来处理。

日志适用于以下场景：

1. 了解单次事件的具体细节：获取某次事件发生的全部详细信息，而不仅仅是汇总后的数字结果。

2. 用于处理离散或不规则发生的事件：比如系统的压缩操作、会话的开始、API错误等等。

3. 在事件发生后进行故障排查：在出现问题后，可以通过查看原始日志记录来进行调试。

4. 实现日志与相关追踪数据之间的关联分析：一条包含追踪ID和跨度ID的日志记录，可以帮助你直接找到该记录所属的请求信息。

我们在这里使用的日志后端是Loki，查询语言为LogQL。通过这样的后端来处理日志数据，可以带来以下优势：

1. 结构化的字段：可以通过命名的字段来进行过滤和计算操作，而无需对文本内容使用正则表达式进行解析。

2. 字段索引功能：只需输入标签名称，就能快速查找相关数据，而无需扫描所有日志记录。

3. 追踪数据之间的关联分析：可以从一条日志记录追溯到其所属的追踪信息，或者提取与某条追踪信息相关的所有日志记录。

4. 基于时间范围的查询功能：每个查询操作都针对特定的时间窗口进行，因此能够有效降低扫描成本。

Grafana在生成仪表盘时也会从Loki中获取数据，这与它处理Prometheus数据的方式是一样的。

压缩事件

当Loki中的数据量过大时，系统会自动进行压缩操作。每次压缩都会生成一条日志记录（event_name="compaction"），其中会包含压缩前后的标记数量(pre_tokens, post_tokens)以及该压缩操作所属的span_id。因此，通过查询这些日志记录，就可以了解压缩操作的频率以及每次压缩所回收的数据量。

在Grafana的“探索”功能中，选择Loki作为数据源，然后粘贴下面的LogQL查询语句。该查询语句会选中所有的压缩事件，使用logfmt函数解析这些事件的字段信息，并通过label_format函数计算出每次压缩所带来的数据减少百分比。需要注意的是，这些字段只有在实际发生了压缩操作之后才会被创建出来，因此需要先触发几次压缩操作才能获取到这些数据。

在这里，为每条记录计算reduction_percentage是可行的，因为这个数值是与具体事件相关联的。而如果要对多次压缩操作进行平均计算，那么这些数据就应该被归类为指标。

label_format这一配置用于添加reduction_pct标签。若想以表格形式显示这些数据，可将面板切换为“表格视图”，并执行以下三项Grafana转换操作：

1. 从标签对象中提取相关字段。

2. 根据字段名称进行过滤，保留Time、pre_tokens、post_tokens、reduction_pct以及span_id这些字段。

3. 将相关字段的类型转换为数值形式，以便pre_tokens、post_tokens和reductionpct能以数字形式显示。

跟踪

跟踪功能能够详细展示请求在应用程序中从开始到结束所经过的完整路径。以下是跟踪技术背后的一些基本概念：

• Span：表示一项具体操作的时间戳记录，是构成跟踪数据的基本单元。所有跟踪信息都会以一系列Span的形式被记录下来，每个Span都有其特定的类型及操作名称：

  • claude_code.interaction：指Claude Code为响应某个用户请求而执行的所有操作。通常来说，这个Span就是整个跟踪过程的代表。

  • claude_code.llm_request：表示在某次交互过程中发生的特定模型调用。

  • claude_code.tool：指在某次交互过程中执行的特定工具命令（如Bash、Write或Agent等）。

• Trace：由多个Span组成的树状结构，用于表示请求从开始到结束所经过的完整路径。

• Session：指一次Claude Code的执行过程，其身份由session.id标识。一次执行可能会产生多个交互事件和相应的跟踪记录。

• Subagent：由Agent工具启动的嵌套式Claude Code实例，它会独立执行自己的交互操作。

Jaeger是此处使用的跟踪后端工具。收集器会通过OTLP将Span数据转发给Jaeger，Jaeger会存储这些数据，并允许用户按服务或Span标签搜索跟踪记录，同时还能以树状结构查看每条记录的详细内容。下面所有操作都是通过地址localhost:16686访问Jaeger的UI来完成的。

生成跟踪记录

为了生成跟踪数据，本指南会使用一个测试提示来启动多个子代理并生成相应的文本内容。这个测试提示是在中等复杂度下使用Sonnet 5工具进行验证的。

你可以直接将这个提示代码粘贴到Claude Code中：

并行启动4个子代理，每个子代理负责处理下面的一个主题。每个子代理都会根据自身掌握的知识来研究该主题，并返回一份约150字的总结，其中包含3个关键点。请注意，这些子代理不得读取文件或执行任何命令。
主题列表：
1. TCP拥塞控制机制的工作原理
2. CAP定理
3> DNS解析过程
4> Bloom过滤器的概念

当所有4个子代理都完成处理后，请将它们的总结内容合并成一份Markdown格式的文档，并保存到summary.md文件中。

注意：在提示命令执行完成后，向Claude Code请求同一会话中的session_id。这个ID将用于在Jaeger中查找相关的追踪记录。

按会话ID查询追踪记录

搜索条件为service = claude-code以及标签session.id=<id>。查询结果返回了6条追踪记录，这些记录都源自claude_code.interaction，其跨度数量介于1到20之间，持续时间从大约1秒到33秒不等。

仅通过这个列表是无法判断每条追踪记录具体执行了什么操作的。需要手动逐一查看这些记录，或者使用针对真实会话的追踪API进行进一步分析，才能得到详细信息：

)

#	追踪记录名称	跨度数量	持续时间	LLM调用次数	使用的工具
1	claude_code.interaction	1	1.4秒	0	–
2	claude_code.interaction	3	4.6秒	2	–
3	claude_code.interaction	1	5.4秒	0	–
4	claude_code.interaction	1	2.5秒	0	–
5	claude_code.interaction	20	15.7秒	7	Agent(x4)
6	claude_code.interaction	15	32.5秒	5	ScheduleWakeup(x2), Write(x1)

一些观察结果：

• 其中有一半的追踪记录其实并无实际意义。记录1、3和4都是仅包含一个跨度的交互操作，既没有模型调用也没有使用任何工具，只是对空闲会话进行的简单检测；记录2则是简短的通信过程；只有记录5和6才真正包含了有意义的操作。

• 这些并行执行的操作实际上都属于同一个交互流程。在记录5中，四个Agent调用都是在一个claude_code.interaction范围内完成的。它们嵌套的模型调用时间各为7到10秒，但这些操作是同时进行的，因此整个交互过程仅耗时约16秒，而所有子代理的模型调用总共花费了大约35秒。

• 每个子代理的模型调用都被包含在其对应的Agent跨度中，并且每个调用都会携带一个agent_id，因此可以区分出这四个不同的子代理。

• agent_id本身并不提供具体的信息。系统中没有agent.name或skill.name这样的字段，因此无法通过这个ID了解每个子代理的具体功能或执行的操作内容。

• 虽然每个跨度都会记录token的数量，但并不会显示对应的费用金额。每个claude_code.llm_request都会包含input_tokens、output_tokens、cache_read_tokens和cache_creation_tokens这些信息，但却没有美元费用的数值。

• 记录6中的“写入操作”属于另一个独立的交互过程。该记录中没有Agent跨度：首先有一个持续时间约为23秒的claude_code.llm_request》用于生成最终的markdown内容，随后才进行了短暂的Write操作；而那两个ScheduleWakeup跨度则属于后台协调任务。

提示：通过跟踪记录，你可以看到四个子代理的调用信息，每个调用都包含agent_id、令牌计数以及时间信息，但这些数据无法说明某个子代理被分配了处理哪个主题的任务。相比之下，指标数据可以通过model、effort和skill等属性来明确显示任务分配情况。

注意：在交互跟踪记录中，userprompt字段默认会被隐藏。将参数OTEL_LOG_USER_PROMPTS设置为1可以取消这一设置，从而记录原始的提示文本。但在多用户/多租户环境中，请避免启用此功能，因为这会使得任何能够访问遥测后端系统的人都能看到提示内容。

结论

本指南全面介绍了Claude Code中的可观测性功能，包括其遥测机制以及如何收集三种类型的数据并在本地后端进行分析。

指标数据可以帮助你按特定属性划分某段时间内累积产生的成本和使用情况。在共享或多租户环境中，这一点尤为重要，因为这些环境中的成本通常不会与某个特定的用户或团队相关联，因此必须有人负责对这些成本进行核算。

日志记录了各个单独的事件，对于了解某个具体操作过程中发生了什么变化非常有用，例如数据压缩操作的具体过程。

跟踪记录展示了某个提示是如何被分解为多个子代理调用以及模型调用的，同时还会显示这些调用的时间信息和令牌计数。这是进行调试或优化复杂的多代理提示系统的起点，不过目前的跟踪系统还无法确定是哪个具体的提示或技能导致了某次调用。

部分遥测功能目前仍处于测试阶段，因此相关参数的名称和属性可能会发生变化，而且像“按调用分配数据”这样的功能也可能在后续版本中得到完善。因此，建议在相关功能正式稳定后，再次查看监控文档以获取最新信息。

参考资料

• Claude定价政策：提示缓存功能

• Claude Code：使用情况监控

• Prometheus：计数器指标类型

• Jaeger：追踪记录的查询方法

• Loki：LogQL日志查询语言

• Grafana：统计信息面板

• OpenTelemetry收集器：配置设置