Metrics

Available Metrics

Prometheus Configuration

Add OpenClaw as a scrape target in your prometheus.yml:

scrape_configs:
  - job_name: 'openclaw'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:8080']   # or your OpenClaw host:port
    metrics_path: /metrics

Key Dashboard Queries

Essential PromQL queries for your Grafana dashboard:

# Task success rate (5-minute window)
rate(openclaw_tasks_total{status="completed"}[5m]) /
rate(openclaw_tasks_total[5m])

# p95 task latency
histogram_quantile(0.95, rate(openclaw_task_duration_seconds_bucket[5m]))

# LLM error rate
rate(openclaw_llm_requests_total{status=~"error.*"}[5m])

Custom Metrics

Plugin tools can register additional metrics using the openclaw.metrics module:

from openclaw.metrics import counter, histogram

db_queries = counter("my_plugin_db_queries_total", "Database queries by outcome", ["outcome"])
query_time = histogram("my_plugin_db_query_seconds", "Database query latency")

async def database_query_tool(query: str) -> dict:
    with query_time.time():
        result = await run_query(query)
    db_queries.labels(outcome="success").inc()
    return result

SLO Definition

A Service Level Objective (SLO) defines the target reliability for your production deployment. A reasonable starting SLO for OpenClaw: 95% of tasks complete successfully, and 90% complete within 120 seconds. Track these with Prometheus recording rules and burn-rate alerting. If the system fails to meet the SLO for more than 30 consecutive minutes, an alert fires and the on-call engineer investigates.

Capacity Planning with Metrics

Trend analysis on your metrics enables proactive capacity planning. Track token usage per task over time — a slow upward trend may indicate prompt bloat. Track queue depth at peak hours — if it regularly exceeds 50 waiting tasks, you need more concurrency or a faster model. Track memory growth over time — semantic memory indexes grow with usage and may require periodic compaction or a larger instance. Reserve one hour per month for capacity review, acting on trends before they become incidents.

Recording Rules for Performance

Complex PromQL queries that run on every dashboard panel load can strain Prometheus, especially at high metric cardinality. Prometheus recording rules pre-compute expensive queries and store the results as new metrics, making dashboards fast and reducing query load on Prometheus storage. Configure recording rules for your most frequently used derived metrics:

groups:
  - name: openclaw.rules
    interval: 30s
    rules:
      - record: openclaw:task_success_rate:5m
        expr: >
          rate(openclaw_tasks_total{status="completed"}[5m]) /
          rate(openclaw_tasks_total[5m])
      - record: openclaw:task_latency_p95:5m
        expr: >
          histogram_quantile(0.95,
            rate(openclaw_task_duration_seconds_bucket[5m]))

Cost Metrics

When you configure per-token pricing in OpenClaw, the system emits openclaw_estimated_cost_usd_total as an additional counter. Use it to build cost dashboards and alerts. A useful cost dashboard shows: cost per day over the past 30 days (identify growth trends), cost per task type (identify expensive agent configurations), and cumulative monthly cost vs. budget. Alert when daily cost exceeds 150% of the 7-day average — this catches sudden cost spikes without alerting on normal day-to-day variation.

Exporting to Cloud Monitoring

For teams using cloud-native monitoring (AWS CloudWatch, GCP Cloud Monitoring, Azure Monitor), the OpenTelemetry Collector can bridge Prometheus metrics to these platforms. Configure the OTEL Collector with the prometheus receiver (scraping /metrics) and the appropriate cloud exporter. This provides a single pipeline for both traces and metrics flowing to your cloud monitoring platform.

Working with Metric Labels

Labels allow you to slice metrics by dimensions — by agent name, by model, by tool, by outcome status. OpenClaw's metrics all include relevant labels for each dimension. The openclaw_tasks_total counter, for example, has agent_name and status labels, letting you compute success rate broken down by agent, or compare task volumes across agents.

Be cautious about label cardinality. High-cardinality labels (like task_id or user_id) would create millions of label combinations, consuming enormous amounts of Prometheus TSDB storage and crashing queries. OpenClaw deliberately excludes high-cardinality identifiers from metrics — use logs and traces for task-level debugging, and metrics for aggregate system-level analysis.

Full Alertmanager Configuration

Beyond the basic setup, tune Alertmanager's grouping and inhibition rules to reduce alert noise. Group related alerts (all components of the same deployment environment) into a single notification rather than sending one notification per alert. Inhibition rules suppress less-important alerts when a more important alert is already firing — if ServiceUnhealthy is firing, suppress all other alerts for that service since they're all consequences of the same root failure. This dramatically reduces notification volume during a major incident, letting you focus on root cause rather than managing alert floods.

Configure alert routing so that production alerts go directly to paging (PagerDuty), staging alerts go to Slack only, and development environment alerts are silenced entirely. Different environments have different urgency levels — a staging failure that blocks a single developer's testing should not wake anyone up at night. Route and prioritize alerts based on the severity of the impact to real users.

Metrics Summary and Next Steps

The combination of the eight core OpenClaw metrics and well-designed Grafana dashboards gives you complete operational visibility: you know task throughput, success rates, latencies, LLM provider health, queue depth, and resource utilization at a glance. From there, add custom metrics for your specific plugin tools, configure cost tracking if you're running at scale, and set up recording rules to keep dashboard queries fast as data volume grows.

Pair metrics with alerts for the critical thresholds (covered in the Alerts page) and with traces for deep task-level investigation (covered in the Tracing page). The three pillars together — metrics, logs, and traces — give you the full observability picture needed to operate an AI agent system in production with confidence.