使用 OpenTelemetry 对 Claude Code 进行监控与可观测性

通过 OpenTelemetry 监控 Claude Code，可以让你全面掌握整个工程团队使用 Claude 的情况。本指南将带你把 Claude Code 的日志和指标导出到 SigNoz，从而追踪最关键的信号：

Token 用量与成本——按用户、模型或 subagent 拆分开销
会话与请求活动——追踪使用情况、活跃时长和请求量
性能——监控 API 延迟、缓存命中率和工具执行耗时
配额与限制——在速率限制影响开发者之前提前预警
工具决策——查看 Edit、Write 等工具的接受/拒绝率
错误与重试——在 API 失败和重试耗尽演变成大问题之前及时发现

配置完成后，所有数据都会汇入 SigNoz 仪表盘，你可以在其中关联日志与指标、设置告警，并分析长期趋势。

前提条件

SigNoz 环境（二选一）：
- SigNoz Cloud 账号，且有可用的 ingestion key
- 自托管的 SigNoz 实例
能够联网，以便将遥测数据发送到 SigNoz Cloud
系统中已安装并运行 Claude Code

监控 Claude Code

关于如何为 Claude Code 配置 OpenTelemetry 埋点的详细说明，请参阅 Claude Code 监控文档。下文用到的所有变量都列在环境变量参考中。

方式一（VSCode）

第 1 步：以启用遥测的方式启动 VSCode

Copy

CLAUDE_CODE_ENABLE_TELEMETRY=1 \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_METRIC_EXPORT_INTERVAL=10000 \
OTEL_LOGS_EXPORT_INTERVAL=5000 \
code .

<region>：你的 SigNoz Cloud region
<your-ingestion-key>：你的 SigNoz 摄入密钥

Info

如果你使用的是自托管的 SigNoz，大部分步骤是完全相同的。要适配本指南，请按照云端转自托管的说明更新端点，并移除摄入密钥请求头。

这将打开 VSCode，所需的环境变量已预先配置好。从这里开始，任何 Claude Code 活动都会自动生成遥测数据，并将日志导出到你的 SigNoz 云端实例。

为了更方便，你克隆我们的bash 脚本，用你的 SigNoz 端点和摄入密钥替换其中的占位符，然后直接运行即可。

方案 2（终端）

第 1 步： 启动启用遥测的 Claude Code

Copy

CLAUDE_CODE_ENABLE_TELEMETRY=1 \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_METRIC_EXPORT_INTERVAL=10000 \
OTEL_LOGS_EXPORT_INTERVAL=5000 \
claude

将<region> 设置为你 SigNoz 云端的区域
将<your-ingestion-key> 替换为你的 SigNoz 摄入密钥

Info

如果你使用的是自托管的 SigNoz，大部分步骤是完全相同的。要适配本指南，请按照云端转自托管的说明更新端点，并移除摄入密钥请求头。

这将启动启用遥测的 Claude Code。在终端会话中，任何 Claude Code 活动都会自动生成日志和指标，并导出到你的 SigNoz 云端实例。

为了更方便，你克隆我们的bash 脚本，用你的 SigNoz 端点和摄入密钥替换其中的占位符，然后直接运行即可。

管理员配置

管理员可通过托管设置文件为所有用户配置 OpenTelemetry，从而在组织范围内集中控制遥测设置。有关设置生效优先级的更多说明，请参阅设置优先级。

托管设置文件位于：

macOS：/Library/Application Support/ClaudeCode/managed-settings.json
Linux 和 WSL：/etc/claude-code/managed-settings.json
Windows：C:\ProgramData\ClaudeCode\managed-settings.json

托管设置配置示例：

复制

{
  "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.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

可通过 MDM（移动设备管理）或其他设备管理方案分发托管设置。托管设置文件中定义的环境变量具有较高优先级，用户无法覆盖。

配置示例

Copy

# 控制台调试（1 秒间隔）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000
 
# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 
# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus
 
# 多导出器
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
 
# 指标和日志使用不同的端点/后端
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317
 
# 仅指标（不含事件/日志）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 
# 仅事件/日志（不含指标）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

配置完成后，Claude Code 的活动就会自动输出日志和指标。

最后，你应该能在 Signoz Cloud 的日志页签中查看这些日志：