convez.ai
AgenteDevOps & InfraestruturaAvançado
origoss-labs

Claude Agent Observability

origoss-labs/claude-agent-observability

Observabilidade completa para agentes Claude com stack OpenTelemetry

Ver no GitHub
InicialPluginScore · de 0 a 100

Plataforma Kubernetes local que coleta traces, métricas e logs de sessões do Claude Code e visualiza em Grafana. Integra Alloy, Tempo, Loki, VictoriaMetrics e Prometheus, orquestrada por Argo CD em cluster kind.

Instalação

$npx convez-ai origoss-labs/claude-agent-observability

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar traces e spans de execução do Claude Code em tempo real
  • Correlacionar logs, métricas e traces para debugging de agentes
  • Manter histórico de telemetria local com Prometheus/Victoria stacks paralelos

Veredito

Solução robusta e bem arquitetada para quem precisa observabilidade profunda de agentes Claude em ambiente local. Exige expertise em Kubernetes, OTLP e infraestrutura — não é plug-and-play, mas oferece dois stacks paralelos sofisticados com dashboards prontas.

README

A tradução para o português deste README ainda está na fila.

Claude Agent Observability

A local Kubernetes platform that collects traces, metrics, and logs from Claude Code sessions and visualises them in Grafana. v1 runs on a single-machine kind cluster.

See CONTEXT.md for the glossary and docs/adr/ for the decisions behind the component choices and the GitOps approach.

Architecture

Two parallel stacks share only the ingest gateway and Grafana, so two community dashboards each run on their native backend — see ADR 0003.

 Laptop (same machine)        kind cluster (single node)
 ┌──────────────────┐         ┌──────────────────────────────────────────────────┐
 │ claude (CLI)      │ OTLP    │  Alloy (OTLP gateway :4317/:4318) — SHARED         │
 │  telemetry on     │─:4317──▶│    ├─ traces  ───────────────▶ Tempo  (shared)     │
 │  beta traces on   │ via kind│    ├─ logs    ──┬──▶ Loki          (Prometheus stack)│
 │  content flags on │ portMaps│    │           └──▶ VictoriaLogs   (Victoria  stack)│
 └──────────────────┘         │    └─ metrics ──┬──▶ Prometheus    (Prometheus stack)│
                              │                  └──▶ VictoriaMetrics (Victoria stack)│
                              │  Grafana (:3000) ◀─ 5 datasources + 3 dashboards — SHARED
                              │  Argo CD ◀─ app-of-apps ◀─ GitHub repo              │
                              └──────────────────────────────────────────────────┘
StackMetricsLogsDashboards
PrometheusPrometheusLoki25255, ColeMurray
VictoriaVictoriaMetricsVictoriaLogs24640

Shared by both: Alloy (ingest — forced, Claude has one OTLP endpoint), Tempo (traces / trace→log correlation), Grafana (5 datasources). Deployed via Argo CD (app-of-apps) syncing from this Git remote.

Prerequisites

  • Podman with a running podman machine, kind, kubectl, make (the Makefile sets KIND_EXPERIMENTAL_PROVIDER=podman; for plain docker, unset it)
  • Internet access (Argo CD pulls charts; reconciles from the GitHub remote)
  • This repo pushed to its remote. Argo CD syncs from Git, not your working copy — commit and push before make up, and make sure the repoURL in bootstrap/argocd/root-app.yaml, apps/networking.yaml, and apps/grafana-dashboards.yaml matches your remote.

Quick start

make up          # kind cluster + Argo CD + root app-of-apps
make status      # watch the Applications go Healthy/Synced

Then open Grafana at http://localhost:3000 (admin / admin).

Configure Claude Code to emit telemetry

The platform collects data only from claude sessions that have telemetry enabled. This config is machine-wide (you run claude from your other projects, not from here), so export these before launching claude — e.g. in your shell profile or a per-session env:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1   # enables traces (beta)
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative  # recommended; Alloy also converts delta->cumulative as a safety net
export OTEL_LOG_USER_PROMPTS=1                 # capture prompt text
export OTEL_LOG_TOOL_CONTENT=1                 # capture tool input/output
export OTEL_METRIC_EXPORT_INTERVAL=10000       # 10s, faster feedback while testing

Run claude, do some work, then open the three dashboards (Claude Code dashboards appear in Grafana's dashboard list), or use Explore (Tempo for the trace waterfall, Loki/VictoriaLogs for prompts/events, Prometheus/VictoriaMetrics for token/cost).

Argo CD UI (optional)

make password                                  # admin password
kubectl port-forward -n argocd svc/argocd-server 8080:443
# https://localhost:8080  (user: admin)

Reboot persistence (local)

The stack comes back after a host reboot via two pieces:

  • the kind node container restarts automatically — needs BOTH:
    • mark it: podman update --restart=always claude-obs-control-plane
    • let podman start such containers on VM boot (restart=always alone does NOT — it only restarts on crash while podman is already running): podman machine ssh 'sudo systemctl enable podman-restart.service'
  • a login LaunchAgent boots the podman VM (it does not auto-start on macOS):
    cp scripts/com.origoss.podman-machine.plist ~/Library/LaunchAgents/
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.origoss.podman-machine.plist
    

On login: VM boots → node restarts → Argo CD reconciles the stack. PVC data is preserved as long as the node container is restarted (not recreated).

Repo layout

CONTEXT.md                     glossary / ubiquitous language
docs/adr/                      architecture decision records
Makefile                       make up / down / status / password
kind/cluster.yaml              cluster + extraPortMappings (4317/4318/3000)
bootstrap/argocd/root-app.yaml the app-of-apps root Application
apps/*.yaml                    one Argo Application per component
manifests/networking/          Alloy OTLP NodePort Service
manifests/dashboards/          Grafana dashboard ConfigMaps (sidecar-loaded)

Status of first-sync verifications

Resolved during bring-up against a live claude -p run:

  • ✅ Service DNS — VM service is victoriametrics (not …-server); Alloy + Grafana corrected.
  • ✅ Alloy NodePort selector — labels confirmed; OTLP reachable at localhost:4317/4318.
  • ✅ Metric naming — confirmed claude_code_*_<unit>_total with job="claude-code".
  • ✅ Dashboard bundle — ColeMurray/claude-code-otel adopted and adapted (job label + datasource uids); see the ConfigMap header.
  • ✅ Delta vs cumulative — Claude defaults to delta temporality, which the Prometheus/VM path silently drops. The env snippet above sets OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative.

Also resolved:

  • ✅ Chart versions — pinned to the live-synced versions (no more "*"); Argo CD pinned to v3.4.3.
  • ✅ Client-agnostic metrics — Alloy runs otelcol.processor.deltatocumulative, so metrics land even from clients that don't set the cumulative env var.
  • ✅ Reproducible dashboards — scripts/adapt-{colemurray,24640,25255}.rb regenerate each ConfigMap from the vendored dashboards/upstream/ JSON.
  • ✅ Two community dashboards added — 24640 (VictoriaStack) + 25255 (Prometheus), each on its native stack; see ADR 0003.

Still open:

  • Sparse panels — commit/PR/lines-of-code panels stay empty until a session actually does that work.
Ver o original no GitHub

Bom para

Relacionados