# Claude Code 监控与分析

> Claude Code OpenTelemetry、analytics dashboard、usage/cost 事件、traceparent、隐私开关、团队指标和 Passion8 网关观测边界。

URL: https://docs.passion8.cc/docs/claude-code/monitoring
Language: zh-CN
Publisher: Passion8

Claude Code 有两类观测能力:本地/企业可配置的 OpenTelemetry 导出,以及 Anthropic 组织侧的 analytics dashboard。它们解决的问题不同。

| 能力 | 适合 |
| --- | --- |
| OpenTelemetry | 企业把 usage、成本、工具调用、trace 发到自己的观测系统 |
| Analytics dashboard | Team/Enterprise 或 API 组织看 adoption、活跃用户、接受行数、花费 |
| `/usage`、`/cost`、status line | 单个开发者看当前会话和计划窗口 |
| Passion8 控制台 | 看网关余额、模型请求和实际扣费 |




接入 Passion8 后,Claude Code 本地仍能产生 OTel 数据,但 Anthropic 的平台 analytics 不一定能完整反映第三方网关账单。实际余额和扣费以 Passion8 为准。




## OpenTelemetry 快速开始

```bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

claude
```

调试时可以缩短导出周期:

```bash
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000
```

生产环境不要把 interval 设得太短,否则观测系统和本机都会增加负担。

## 管理员下发

组织可以通过 managed settings 强制启用:

```json title="managed settings"
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}
```

Managed settings 里的环境变量优先级高,普通用户不能覆盖。注意 Claude Code 不会把 `OTEL_*` 自动传给 Bash、Hooks、MCP servers 或 language servers。如果这些子进程也要导出 telemetry,需要单独配置。

## 常用环境变量

| 变量 | 作用 |
| --- | --- |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | 启用 telemetry |
| `OTEL_METRICS_EXPORTER` | `otlp`、`prometheus`、`console`、`none` |
| `OTEL_LOGS_EXPORTER` | `otlp`、`console`、`none` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`、`http/json`、`http/protobuf` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector 地址 |
| `OTEL_EXPORTER_OTLP_HEADERS` | 静态认证 header |
| `OTEL_METRIC_EXPORT_INTERVAL` | metrics 导出间隔 |
| `OTEL_LOGS_EXPORT_INTERVAL` | logs 导出间隔 |
| `OTEL_LOG_USER_PROMPTS` | 是否记录用户 prompt 原文 |
| `OTEL_LOG_ASSISTANT_RESPONSES` | 是否记录 assistant 回复文本 |
| `OTEL_LOG_TOOL_DETAILS` | 是否记录工具参数、命令、MCP 名称 |
| `OTEL_LOG_TOOL_CONTENT` | tracing 中记录工具输入输出内容 |
| `OTEL_LOG_RAW_API_BODIES` | 记录完整 Messages API 请求/响应,风险最高 |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 动态 header helper 刷新间隔 |




默认不要打开 `OTEL_LOG_RAW_API_BODIES`。它可能包含完整对话历史、文件片段、工具输入输出和密钥。只有在隔离环境排查协议问题时短期开启。




## Metrics cardinality

高基数字段会让监控存储变贵。官方提供这些开关:

| 变量 | 默认 | 作用 |
| --- | --- | --- |
| `OTEL_METRICS_INCLUDE_SESSION_ID` | `true` | 是否把 session.id 放入 metrics |
| `OTEL_METRICS_INCLUDE_VERSION` | `false` | 是否带 Claude Code 版本 |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | `true` | 是否带账号标识 |
| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | `false` | 是否带入口来源 |
| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `true` | 是否把 resource attributes 作为 datapoint labels |

团队维度可以用:

```bash
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
```

不要在这里放空格或高基数随机值。

## Traces

Tracing 需要额外打开 beta 开关:

```bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
```

每个用户 prompt 会形成 `claude_code.interaction` root span,下面挂 API 请求、工具调用和 Hook 执行。子代理的 API 和工具 span 会挂在父级 Agent tool span 下。

```text
claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── subagent claude_code.llm_request / claude_code.tool
```

当 tracing 打开时,Bash 和 PowerShell 子进程会收到 `TRACEPARENT`。如果你通过自定义 `ANTHROPIC_BASE_URL` 代理模型请求,默认不会把 traceparent 发给第三方 provider。确实要传播时设置:

```bash
export CLAUDE_CODE_PROPAGATE_TRACEPARENT=1
```

## Analytics dashboard

| 计划 | 地址 | 内容 |
| --- | --- | --- |
| Claude Team / Enterprise | `https://claude.ai/analytics/claude-code` | 使用量、贡献指标、leaderboard、CSV 导出 |
| Claude Console API | `https://platform.claude.com/claude-code` | 使用量、花费、团队 insight |

Team/Enterprise 的贡献指标需要 GitHub app 和组织设置。它会统计 Claude Code 辅助的 PR、代码行、接受率和活跃用户。Zero Data Retention 组织只能看 usage metrics,不能看贡献指标。

API 用户的 Console dashboard 主要显示 accepted lines、suggestion accept rate、activity、spend 和 per-user insights。Spend 是 analytics 估算,实际账单以 billing 为准。

## 和缓存、成本的关系

| 行为 | 对 5m / 1h 缓存的影响 |
| --- | --- |
| 开启 OTel metrics/logs | 不改变模型 prompt,通常不影响缓存 |
| 开启 tracing | 不改变 prompt,但可能增加本机导出开销 |
| 打开 prompt/tool/raw body 记录 | 不影响缓存,但显著增加隐私和日志成本风险 |
| `/usage`、`/cost` | 本地/账号用量展示,不改变 prompt 前缀 |
| status line 展示成本 | 本地脚本,不调用模型 |

如果要优化 Passion8 账单,优先看 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching)、[成本优化](https://docs.passion8.cc/docs/claude-code/cost-saving) 和 Passion8 控制台,不要只看 Anthropic dashboard。

## 官方参考

- [Monitoring with OpenTelemetry](https://code.claude.com/docs/en/monitoring-usage.md)
- [Track team usage with analytics](https://code.claude.com/docs/en/analytics.md)
- [Status line](https://code.claude.com/docs/en/statusline.md)
- [Manage costs effectively](https://code.claude.com/docs/en/costs.md)