Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clawker.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

Egress traffic visibility dashboard

​
Architecture

The monitoring stack runs as six 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
Promtailgrafana/promtail9080Collects firewall container logs (Envoy + CoreDNS) via Docker socket and ships to Loki
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.

​
Egress Traffic Visibility

When the firewall is enabled, the dashboard includes an Egress Traffic row at the bottom with real-time visibility into network activity:
  • Envoy Traffic — streaming log of all outbound connections through the proxy, showing domain, protocol, HTTP method/path (for inspected traffic), response codes, and response flags
  • DNS Lookups — streaming log of all DNS queries through CoreDNS, showing queried domain, query type, response code (NOERROR for allowed, NXDOMAIN for blocked), and resolution time
  • Top Blocked Domains — table of the most frequently blocked domains (denied by Envoy or NXDOMAIN from CoreDNS)
  • Egress Over Time — time series of outbound request volume by protocol type
Egress logs are collected by Promtail, which auto-discovers the firewall containers by their Docker labels and ships structured logs to Loki. No additional configuration is needed — clawker monitor init generates the Promtail configuration automatically.

​
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 six 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
  • promtail-config.yaml — Promtail configuration for firewall log collection
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).