Skip to main content
Clawker includes an optional monitoring stack that collects telemetry from Claude Code agents running in containers. It provides real-time dashboards for metrics and logs — giving you visibility into what every agent is doing, how much it costs, what tools it’s calling, and whether it’s making progress. Grafana monitoring dashboard overview

​
What You Get

The pre-built Grafana dashboard gives you per-agent and per-project visibility into:
  • Cost and token usage — API call costs, input/output tokens, rate limiting
  • Coding activity — file edits, tool invocations, command executions
  • Tool usage — which tools the agent calls, how often, and how long they take
  • Session detail — full event timeline for individual agent sessions

Cost and token usage dashboard

Coding activity dashboard

Tool usage breakdown

Session detail events

​
Architecture

The monitoring stack runs as five Docker Compose services on the clawker-net network: 
Claude Code (in container)
    |
    | OTLP (HTTP/gRPC) — metrics & logs
    v
OTEL Collector ──┬──> Prometheus (metrics)
                 ├──> Loki (logs)
                 └──> Jaeger (traces — collector-ready, not yet emitted by agents)
                          |
                          v
                      Grafana (unified dashboards)

​
Services

ServiceImageDefault PortPurpose
OTEL Collectorotel/opentelemetry-collector-contrib4318 (HTTP), 4317 (gRPC)Receives telemetry from agents and routes it to storage backends
Prometheusprom/prometheus9090Time-series metrics storage — resource utilization, request counts, durations
Lokigrafana/loki3100Log aggregation — structured events with tool details, prompts, decisions
Jaegerjaegertracing/all-in-one16686Distributed tracing — collector pipeline is configured but agents don’t emit traces yet
Grafanagrafana/grafana3000Unified dashboards — pre-configured with all data sources and a Claude Code dashboard
All containers are pre-configured with labels and attached to the clawker-net network. Grafana starts with anonymous login enabled (no credentials required) and data sources pre-provisioned.

​
How Agents Connect

OTEL endpoints are baked into every Clawker image at build time. At container creation, Clawker checks whether the monitoring stack is running and conditionally enables telemetry:
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT — points to the collector’s metrics endpoint (baked into image)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT — points to the collector’s logs endpoint (baked into image)
  • CLAUDE_CODE_ENABLE_TELEMETRY — set to 1 when the otel-collector container is detected as running on clawker-net, set to 0 otherwise
  • OTEL_RESOURCE_ATTRIBUTES — tags with project= and agent= for filtering
Key behavior: Telemetry is only active when the monitoring stack is running at the time the container is created. If the stack isn’t up, Clawker explicitly disables telemetry so agents don’t waste time attempting exports to an unreachable collector. You can force-enable telemetry via agent.env in your .clawker.yaml even when the stack is down, but Claude Code won’t retry failed collector connections. Start the monitoring stack before starting your agents to ensure telemetry is captured.

​
Setup

​
1. Initialize Configuration

clawker monitor init
This scaffolds configuration files in your data directory (~/.local/share/clawker/monitor/):
  • compose.yaml — Docker Compose definition for all five services
  • otel-config.yaml — OpenTelemetry Collector pipeline configuration
  • prometheus.yaml — Prometheus scrape targets
  • grafana-datasources.yaml — Auto-provisioned Grafana data sources
  • grafana-dashboards.yaml — Dashboard provisioning config
  • grafana-dashboard.json — Pre-built Claude Code dashboard
Use --force to regenerate files if they already exist.

​
2. Start the Stack

clawker monitor up
The stack runs in the background. Service URLs are printed on startup: 
Grafana:    http://localhost:3000
Jaeger:     http://localhost:16686
Prometheus: http://localhost:9090

​
3. Run Agents

Start agents as usual — telemetry flows automatically: 
clawker run -it --agent dev @

​
4. View Dashboards

Open Grafana at http://localhost:3000. The pre-configured Claude Code dashboard shows metrics and logs with per-project and per-agent filtering.

​
Telemetry Controls

Fine-tune what telemetry is collected via settings.yaml: 
monitoring:
  telemetry:
    log_tool_details: true       # Include tool invocation details
    log_user_prompts: true       # Include user prompts in logs
    include_account_uuid: true   # Include account identifier
    include_session_id: true     # Include session identifier

​
Port Configuration

Override default ports in settings.yaml if they conflict with other services: 
monitoring:
  grafana_port: 3000
  jaeger_port: 16686
  prometheus_port: 9090
  loki_port: 3100
  otel_collector_port: 4318
  otel_grpc_port: 4317
  prometheus_metrics_port: 8889
After changing ports, regenerate config files and restart: 
clawker monitor init --force
clawker monitor down
clawker monitor up

​
Checking Status

clawker monitor status
Shows container status (running/stopped) and service URLs for running services.

​
Teardown

# Stop the stack (preserves data)
clawker monitor down

# Stop and remove all data volumes
clawker monitor down --volumes
Without --volumes, monitoring data persists across restarts. The clawker-net network is preserved for other Clawker services (firewall, agents).