Stories

Pin local observability in 60 seconds

defenseclaw setup local-observability up brings the bundled OTel Collector + Prom/Loki/Tempo/Grafana stack online and points the gateway's OTLP exporter at it. One command, five containers, three signals.

DefenseClaw's runtime is designed to land in your existing telemetry stack — Splunk, OTLP, webhooks. But for the first 60 seconds of operating it, you want to see what it's doing without wiring up production. That's the local stack.

The 60-second tour: defenseclaw setup local-observability up → containers warm up → Grafana populates with live gateway events.

For the full deep-dive on flags, dashboards, and tear-down, see Observability → Local stack.

What you get

Prometheus

Metrics: requests, blocks, judge latency, sandbox events.

Loki

Logs: every audit row, with structured labels for connector + severity.

Tempo

Traces: hook → gateway → policy → sink, end-to-end.

Grafana

Pre-built dashboard with the four signals operators actually look at.

Run it

Bring up the stack

defenseclaw setup local-observability up

Brings up five containers via Docker Compose:

  • otel-collector on :4317 (gRPC) / :4318 (HTTP) — the OTLP receiver that fans out to Prom/Loki/Tempo
  • prometheus:latest on :9090
  • loki:latest on :3100
  • tempo:latest on :3200
  • grafana:latest on :3000

Point the gateway at the OTLP collector

defenseclaw setup guardrail \
  --connector codex \
  --restart

Replace codex with another connector you have wired, such as claudecode. Setup detects the local stack on 127.0.0.1:4317 and creates or updates the named local-observability route in otel.destinations[]. On a multi-connector host, that route is shared; use --connector only when you also want to reconcile that connector's hook wiring.

Open Grafana

Visit http://localhost:3000 (default credentials are surfaced by the up command). The pre-installed defenseclaw-overview dashboard shows:

  • Requests per second by connector
  • Block rate by severity
  • p50 / p95 / p99 judge latency
  • Recent CRITICAL findings, with click-through to the Loki log line

Tear it down

defenseclaw setup local-observability down

Stops the containers and unwires the OTLP endpoint. Your audit DB is untouched.

Architecture

metrics
logs
traces
Control planedefenseclaw-gateway
Evidence storePrometheus:9090
Evidence storeLoki:3100
Evidence storeTempo:3200
Evidence storeGrafana:3000
The gateway exports three signals. The local stack receives all three and Grafana joins them.

When to graduate to your own stack

The local stack is for building intuition. For production, replace each component with the equivalent in your existing telemetry estate:

  • Prometheus → your metrics platform (Datadog, New Relic, Honeycomb, ...).
  • Loki → your log aggregator (Splunk, Datadog Logs, ...).
  • Tempo → your tracing backend (Honeycomb, Tempo, Jaeger, ...).
  • Grafana → whatever your team already uses for dashboards.

Point the gateway's OTLP exporter at your collector and DefenseClaw's signals land alongside the rest of your telemetry. See the Reference / Configuration page for the full env-var list.

Approve risky tool calls before they fire

Use a safe synthetic secret file to verify native HITL approval on Claude Code, then understand the non-pausing fallback on connectors without native ask.

Add a connector without losing audit history

Use defenseclaw setup <connector> to add or reconfigure agent wiring while preserving audit history for every connector.