Claude Agent Observability
origoss-labs/claude-agent-observability
Observabilidade completa para agentes Claude com stack OpenTelemetry
Ver no GitHubPlataforma 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-observability1 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
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 │
└──────────────────────────────────────────────────┘
| Stack | Metrics | Logs | Dashboards |
|---|---|---|---|
| Prometheus | Prometheus | Loki | 25255, ColeMurray |
| Victoria | VictoriaMetrics | VictoriaLogs | 24640 |
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 setsKIND_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 therepoURLinbootstrap/argocd/root-app.yaml,apps/networking.yaml, andapps/grafana-dashboards.yamlmatches 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'
- mark it:
- 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>_totalwithjob="claude-code". - ✅ Dashboard bundle — ColeMurray/claude-code-otel adopted and adapted
(
joblabel + 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 tov3.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}.rbregenerate each ConfigMap from the vendoreddashboards/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.