Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

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

OpenClaw kan diagnostische metrics beschikbaar maken via de officiële diagnostics-prometheus-plugin. Deze luistert naar vertrouwde interne diagnostiek en geeft een Prometheus-teksteindpunt weer 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-geverifieerd /metrics-eindpunt. Scrape deze via hetzelfde authenticatiepad dat je gebruikt voor andere operator-API’s.
Voor traces, logs, OTLP-push en OpenTelemetry GenAI-semantische attributen, zie OpenTelemetry-export.

​
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 starten van de plugin, dus laad opnieuw na het inschakelen.
4

Scrape de beveiligde route

Stuur dezelfde gateway-authenticatie mee die je operator-clients gebruiken:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Koppel Prometheus

# 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 de respons 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_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_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
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_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_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
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 lage cardinaliteit. De exporter geeft geen onbewerkte diagnostische identifiers weer, zoals runId, sessionKey, sessionId, callId, toolCallId, bericht-ID’s, chat-ID’s of provider-request-ID’s.Labelwaarden worden geredigeerd en moeten voldoen aan OpenClaw’s tekenbeleid voor lage cardinaliteit. Waarden die niet aan het beleid voldoen, worden vervangen door unknown, other of none, afhankelijk van de metric.
De exporteur beperkt bewaarde tijdreeksen in het geheugen tot 2048 reeksen in totaal voor 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 duidelijk signaal dat een bovenliggend attribuut waarden met hoge cardinaliteit lekt. De exporteur verhoogt de limiet nooit automatisch; als deze oploopt, los dan de bron op 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 provider-aanvraag-id’s (alleen begrensde hashes, waar van toepassing, op spans — nooit op metrics)
  • 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

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

​
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 scrapt /api/diagnostics/prometheus.
  • Geen externe collector vereist.
  • Geauthenticeerd via normale Gateway-authenticatie.
  • Oppervlak is alleen metrics (geen traces of logs).
  • Beste keuze voor stacks die al zijn gestandaardiseerd op Prometheus + Grafana.

​
Probleemoplossing

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

​
Gerelateerd