SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场observability-stack-setup

observability-stack-setup

部署与运维

查看项目

更新于 10-15 10:53

技能介绍

用途

Observability Stack Setup 是一个用于自动化部署完整 LGTM（Loki、Grafana、Tempo、Mimir/Prometheus）+ Alloy 可观测性技术栈的技能，专门面向 Claude Code 的监控场景。当需要首次为 Claude Code 搭建可观测性、部署本地开发监控基础设施、监控 Claude Code 操作（工具调用、成本、错误、性能），或希望使用预配置仪表盘分析 Claude Code 时，可使用该技能。

主要能力

该技能会自动部署并配置以下组件：

  • Grafana Alloy：OTEL 收集器，接收来自 Claude Code 的遥测数据。
  • Loki：日志聚合，存储所有 Claude Code 日志。
  • Tempo：分布式追踪，跟踪工具调用与 API 请求。
  • Prometheus：指标存储，记录 token 用量、成本与性能。
  • Grafana：可视化，附带预构建的 Claude Code 仪表盘。

部署的服务及端口如下：

服务 端口 用途
Grafana 3000 仪表盘与可视化
Grafana Alloy 4317 (gRPC)、4318 (HTTP)、12345 (metrics) OTLP 接收器
Loki 3100 日志存储与查询
Tempo 3200 追踪存储与查询
Prometheus 9090 指标存储与查询

所有数据持久化在 .observability/volumes/ 目录下，包括 alloy-data、loki-data、tempo-data、prometheus-data 和 grafana-data。

预构建仪表盘包括：

  • Claude Code Overview：会话数量、时长、活跃时间、token 用量与成本趋势、按工具划分的错误率、热门操作。
  • Tool Performance Matrix：各工具调用次数、平均/P95/P99 延迟、成功/失败率、最常见错误。
  • Cost Analysis：日/周/月成本、token 用量明细、预算跟踪、成本预测。
  • Error Tracking：错误时间线、错误类型分布、受影响工具、近期错误详情。
  • Session Analysis：会话时长分布、每日/每周会话数、对话深度、活跃与空闲时间。

使用方式

前置条件

需验证 Docker 已安装（要求 ≥ 20.10）：

docker --version

需验证 Docker Compose 已安装（要求 ≥ 2.0）：

docker compose version

部署流程

调用该技能后，它会执行以下步骤：

  1. 验证 Docker 与 Docker Compose 版本兼容性。
  2. 创建 .observability/ 目录结构，包含 docker-compose.yml、alloy/config.yaml、grafana/datasources/、grafana/dashboards/ 及 volumes/ 等。
  3. 从模板生成所有配置文件。
  4. 使用 docker compose -f .observability/docker-compose.yml up -d 启动技术栈。
  5. 对每个服务执行健康检查：Alloy（http://localhost:12345/metrics）、Loki（http://localhost:3100/ready）、Tempo（http://localhost:3200/ready）、Prometheus（http://localhost:9090/-/healthy）、Grafana（http://localhost:3000/api/health）。
  6. 通过 Grafana API 导入所有预构建仪表盘。
  7. 输出各服务的访问 URL、默认凭据（admin/admin）、供 Claude Code 配置使用的 OTLP 端点，以及下一步操作提示。

预计耗时 5-10 分钟。

配置细节

Grafana Alloy 通过 OTLP 协议接收来自 Claude Code 的遥测数据，gRPC 端点为 localhost:4317，HTTP 端点为 localhost:4318，并将遥测路由至后端：日志 → Loki，追踪 → Tempo，指标 → Prometheus。

保留策略默认 365 天，可在 docker-compose.yml 中配置：Loki 为 365 天（-ingester.max-chunk-age=365d），Tempo 为 365 天（-storage.trace.local.path retention），Prometheus 为 365 天（--storage.tsdb.retention.time=365d）。

隐私设置方面，该配置启用完整日志记录（无脱敏）：用户提示完整内容记录、文件路径完整可见、工具执行完整命令详情、API 请求所有参数可见。此配置假设为个人使用的可观测性场景，具备完整数据访问权限。

后续步骤

技术栈运行后：

  1. 启用 Claude Code 遥测：使用 claude-code-telemetry-enable 技能。
  2. 使用 Claude Code：运行工具、读取文件、执行命令。
  3. 查看仪表盘：打开 http://localhost:3000，浏览预构建仪表盘。
  4. 验证数据流动：检查 Grafana → Explore → Loki/Prometheus/Tempo。

停止技术栈

优雅关闭（保留数据）：

docker compose -f .observability/docker-compose.yml down

完全移除（删除数据）：

docker compose -f .observability/docker-compose.yml down -v

适用场景

  • 首次为 Claude Code 搭建可观测性。
  • 部署本地开发可观测性基础设施。
  • 需要监控 Claude Code 操作（工具调用、成本、错误、性能）。
  • 希望使用预配置仪表盘进行 Claude Code 分析。

限制与注意事项

  • 需预先安装 Docker（≥ 20.10）与 Docker Compose（≥ 2.0）。
  • 若端口 3000、3100、3200、4317、4318、9090 或 12345 被占用，需停止冲突服务或修改 docker-compose.yml 中的端口。
  • 服务未启动时，可通过 docker compose -f .observability/docker-compose.yml logs [service_name] 查看日志；常见问题包括磁盘空间不足、内存不足（Alloy 约需 512MB，其他各约 256MB）、卷目录权限问题。
  • 仪表盘未出现时，可手动导入：将仪表盘 JSON 复制到容器后通过 Grafana API 导入。
  • 隐私配置默认启用完整日志记录且无脱敏，仅适用于个人使用场景。

参考与脚本

参考文件包括：references/docker-compose-full.yml、references/alloy-config.yaml、references/grafana-datasources/、references/dashboards/、references/troubleshooting.md。

脚本包括：scripts/setup-stack.sh（主设置脚本）、scripts/verify-health.sh（健康检查）、scripts/import-dashboards.sh（导入仪表盘）。

版本信息

组件版本（截至 2025-11-22 最新）：Grafana 11.5.2、Grafana Alloy 1.5.0、Loki 3.4.2、Tempo 2.7.1、Prometheus 2.55.0。所有版本在 docker-compose.yml 中固定以保证可复现性。