SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-code-telemetry-enable

claude-code-telemetry-enable

部署与运维

查看项目

更新于 10-15 13:47

技能介绍

用途

Claude Code Telemetry Enable 用于在 Claude Code 中启用 OpenTelemetry（OTEL）遥测，将指标（metrics）、日志（logs）和追踪（traces）发送到你自己的可观测性栈，例如本地 LGTM 栈或 Railway 上的栈。

适用时机包括：部署完可观测性栈（observability-stack-setup）之后、需要为 Claude Code 开启监控时、想为本地或云端后端配置遥测时，以及需要验证遥测连通性时。

主要能力

该技能会创建 Claude Code 环境配置文件，启用以下数据的采集：

  • 指标：Token 用量、成本、会话数、工具性能等。
  • 日志：用户提示词（完整内容）、工具结果、API 请求与错误。
  • 追踪：会话流程、工具执行 span、API 调用追踪。

隐私说明：按资料描述，配置为 FULL LOGGING（不进行脱敏）。

使用方式（操作命令）

enable-local

为本地 LGTM 栈配置 Claude Code，创建 ~/.config/claude-code/.env.telemetry。关键环境变量示例：

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_METRIC_EXPORT_INTERVAL=10000
OTEL_LOGS_EXPORT_INTERVAL=5000
OTEL_LOG_USER_PROMPTS=1
OTEL_METRICS_INCLUDE_SESSION_ID=true
OTEL_METRICS_INCLUDE_VERSION=true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true

enable-railway

为 Railway 托管的 LGTM 栈配置。参数：--endpoint（Railway Alloy OTLP 端点 URL）、--token（可选，Railway 认证令牌）。示例：

enable-railway \
  --endpoint https://your-alloy-abc123.railway.app:443 \
  --token your-railway-token

enable-custom

为自定义 OTLP 端点（如 Grafana Cloud、DataDog）配置。参数：--endpoint、--protocol（grpc 或 http，默认 grpc）、--headers（认证头）。示例：

enable-custom \
  --endpoint https://otlp.grafana.net:443 \
  --protocol grpc \
  --headers "Authorization=Basic base64encodedcreds"

verify

测试遥测配置与连通性，检查配置文件是否存在、必需环境变量是否设置、OTLP 端点是否可达、测试遥测是否成功发送、后端（Grafana/Loki/Prometheus/Tempo）中数据是否可见。

disable

完全关闭遥测：把 .env.telemetry 重命名为 .env.telemetry.disabled，或将 CLAUDE_CODE_ENABLE_TELEMETRY 设为 0。可重新启用。

status

显示当前遥测配置，包括状态、端点、协议、隐私级别、导出间隔以及采集的数据类型。

配置细节

关键环境变量：

  • CLAUDE_CODE_ENABLE_TELEMETRY：1 启用，0 禁用。
  • OTEL_EXPORTER_OTLP_ENDPOINT：OTLP 端点 URL。
  • OTEL_EXPORTER_OTLP_PROTOCOL：grpc 或 http。
  • OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER：设为 otlp 以通过 OTLP 发送。
  • OTEL_METRIC_EXPORT_INTERVAL：指标导出间隔（毫秒，默认 60000）。
  • OTEL_LOGS_EXPORT_INTERVAL：日志导出间隔（毫秒，默认 5000）。
  • 隐私控制：OTEL_LOG_USER_PROMPTS（1 记录完整内容，0 仅记录长度）、OTEL_METRICS_INCLUDE_SESSION_ID、OTEL_METRICS_INCLUDE_VERSION、OTEL_METRICS_INCLUDE_ACCOUNT_UUID。
  • 认证：OTEL_EXPORTER_OTLP_HEADERS（如 "Authorization=Bearer token"）。

采集内容

指标（计数器、仪表、直方图）：

  • claude_code.session.count
  • claude_code.token.usage
  • claude_code.cost.usage
  • claude_code.code_edit_tool.decision
  • claude_code.active_time.total
  • claude_code.pull_request.count
  • claude_code.commit.count

日志事件（结构化 JSON）：

  • claude_code.user_prompt
  • claude_code.tool_result
  • claude_code.api_request
  • claude_code.api_error
  • claude_code.tool_decision

追踪：会话追踪、工具调用 span（Read、Write、Edit、Bash、Glob、Grep、Task 等）、Agent 任务 span、API 请求 span。

数据保留：所有数据存储 365 天（在可观测性栈中配置）。

文件位置

配置文件：

  • Linux/WSL/macOS：~/.config/claude-code/.env.telemetry
  • Windows：%USERPROFILE%\.config\claude-code\.env.telemetry

托管设置（组织强制，可选）：Linux /etc/claude-code/managed-settings.json；macOS /Library/Application Support/ClaudeCode/managed-settings.json；Windows C:\ProgramData\ClaudeCode\managed-settings.json。

排查

  • Grafana 中无遥测：检查是否启用、OTLP 端点是否可达、可观测性栈是否运行、使用 Claude Code 后立即查询 Loki。
  • 端口 4317 被占用：停止冲突服务，或在可观测性栈中修改 Alloy 端口后更新遥测配置端点。
  • 权限被拒：手动创建目录 mkdir -p ~/.config/claude-code 并 chmod 755。

后续步骤

启用遥测后：使用 Claude Code 运行工具以生成遥测数据，在 Grafana（http://localhost:3000）中查看 "Claude Code Overview" 仪表盘，核对 Token 用量、成本、工具调用等指标。

参考资料与脚本

references 目录包含本地/Railway/自定义端点模板、环境变量说明与隐私设置文档；scripts 目录包含 enable-local.sh、enable-railway.sh、verify-telemetry.sh、disable-telemetry.sh。