Naar hoofdinhoud gaan
OpenClaw kan diagnostische metrics beschikbaar stellen via de officiële diagnostics-prometheus-plugin. Deze luistert naar vertrouwde diagnostiek plus door de kern uitgezonden Gateway-stabiliteitsgebeurtenissen en rendert vervolgens een Prometheus-teksteindpunt op: 
GET /api/diagnostics/prometheus
Het contenttype is text/plain; version=0.0.4; charset=utf-8, de standaard Prometheus-expositie-indeling.
De route gebruikt Gateway-authenticatie (operator-scope). Stel deze niet beschikbaar als openbaar, niet-geauthenticeerd /metrics-eindpunt. Scrape deze via hetzelfde authenticatiepad dat je gebruikt voor andere operator-API’s.
Zie OpenTelemetry-export voor traces, logs, OTLP-push en OpenTelemetry GenAI-semantische attributen.

​
Snel aan de slag

1

Installeer de plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

Schakel de plugin in

{
  plugins: {
    allow: ["diagnostics-prometheus"],
    entries: {
      "diagnostics-prometheus": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
  },
}
3

Herstart de Gateway

De HTTP-route wordt geregistreerd bij het opstarten van de plugin, dus herlaad na het inschakelen.
4

Scrape de beschermde route

Verstuur dezelfde Gateway-authenticatie die je operatorclients gebruiken:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Prometheus aansluiten

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]
diagnostics.enabled: true is vereist. Zonder deze instelling registreert de Plugin nog steeds de HTTP-route, maar stromen er geen diagnostische gebeurtenissen naar de exporter, waardoor het antwoord leeg is.

​
Geëxporteerde metrics

MetricTypeLabels
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcounterfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_skill_used_totalcounteractivation, agent, skill, source
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcounterdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcounterchannel, webhook
openclaw_webhook_error_totalcounterchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalcounterchannel, source
openclaw_message_dispatch_started_totalcounterchannel, source
openclaw_message_dispatch_completed_totalcounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_turn_created_totalcounteragent, channel, trigger
openclaw_session_stuck_totalcounterreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalcounterreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalcounteraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramgeen
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcountergeen

​
Labelbeleid

Prometheus-labels blijven begrensd en hebben een lage kardinaliteit. De exporter geeft geen ruwe diagnostische identifiers uit, zoals runId, sessionKey, sessionId, callId, toolCallId, bericht-ID’s, chat-ID’s of aanvraag-ID’s van providers.Labelwaarden worden geredigeerd en moeten voldoen aan OpenClaw’s tekenbeleid voor lage kardinaliteit. Waarden die niet aan het beleid voldoen, worden vervangen door unknown, other of none, afhankelijk van de metric. Labels die lijken op gescopete sessiesleutels van agents worden ook vervangen door unknown.
De exporter begrenst het aantal bewaarde tijdreeksen in het geheugen tot 2048 reeksen over counters, gauges en histogrammen samen. Nieuwe reeksen boven die limiet worden verwijderd, en openclaw_prometheus_series_dropped_total wordt telkens met één verhoogd.Houd deze counter in de gaten als hard signaal dat een bovenliggend attribuut waarden met hoge kardinaliteit lekt. De exporter verhoogt de limiet nooit automatisch; als deze oploopt, repareer dan de bron in plaats van de limiet uit te schakelen.
  • prompttekst, antwoordtekst, toolinvoer, tooluitvoer, systeemprompts
  • Talk-transcripten, audio-payloads, oproep-id’s, ruimte-id’s, overdrachtstokens, beurt-id’s en ruwe sessie-id’s
  • ruwe providerverzoek-id’s (alleen begrensde hashes, waar van toepassing, op spans — nooit op metrieken)
  • sessiesleutels en sessie-id’s
  • hostnamen, bestandspaden, geheime waarden

​
PromQL-recepten

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Geef de voorkeur aan gen_ai_client_token_usage voor dashboards over meerdere providers: deze volgt de semantische conventies van OpenTelemetry GenAI en is consistent met metrieken van niet-OpenClaw GenAI-services.

​
Kiezen tussen Prometheus- en OpenTelemetry-export

OpenClaw ondersteunt beide oppervlakken onafhankelijk. Je kunt een van beide, beide of geen van beide gebruiken.
  • Pull-model: Prometheus scrapet /api/diagnostics/prometheus.
  • Geen externe collector vereist.
  • Geauthenticeerd via normale Gateway-authenticatie.
  • Oppervlak bevat alleen metrieken (geen traces of logs).
  • Het meest geschikt voor stacks die al op Prometheus + Grafana zijn gestandaardiseerd.

​
Problemen oplossen

  • Controleer diagnostics.enabled: true in de configuratie.
  • Bevestig dat de Plugin is ingeschakeld en geladen met openclaw plugins list --enabled.
  • Genereer wat verkeer; tellers en histogrammen geven pas regels uit na ten minste één gebeurtenis.
Het eindpunt vereist de Gateway-operatorscope (auth: "gateway" met gatewayRuntimeScopeSurface: "trusted-operator"). Gebruik hetzelfde token of wachtwoord dat Prometheus gebruikt voor elke andere Gateway-operatorroute. Er is geen openbare niet-geauthenticeerde modus.
Een nieuw attribuut overschrijdt de limiet van 2048 series. Inspecteer recente metrieken op een onverwacht label met hoge kardinaliteit en los dit bij de bron op. De exporter laat nieuwe series opzettelijk vallen in plaats van labels stilzwijgend te herschrijven.
De Plugin bewaart status alleen in het geheugen. Na een herstart van de Gateway worden tellers teruggezet naar nul en starten gauges opnieuw bij hun volgende gerapporteerde waarde. Gebruik PromQL rate() en increase() om resets netjes af te handelen.

​
Gerelateerd