Naar hoofdinhoud gaan

Documentation Index

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

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

OpenClaw kan diagnostische metrics beschikbaar maken via de gebundelde Plugin diagnostics-prometheus. Deze luistert naar vertrouwde interne diagnostiek en rendert een Prometheus-texteindpunt op: 
GET /api/diagnostics/prometheus
Het inhoudstype 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 auth-pad dat je gebruikt voor andere operator-API’s.
Voor traces, logs, OTLP-push en OpenTelemetry GenAI-semantische attributen, zie OpenTelemetry-export.

​
Snel starten

1

Schakel de Plugin in

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

Herstart de Gateway

De HTTP-route wordt geregistreerd bij het starten van de Plugin, dus herlaad na het inschakelen.
3

Scrape de beschermde route

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

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 er stromen geen diagnostische gebeurtenissen naar de exporter, waardoor de response leeg is.

​
Geëxporteerde metrics

MetriekTypeLabels
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_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
Labelbeleid

Prometheus-labels blijven begrensd en hebben lage cardinaliteit. De exporter emit geen ruwe diagnostische identificatiegegevens zoals runId, sessionKey, sessionId, callId, toolCallId, message-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 metriek.
De exporter begrenst bewaarde tijdreeksen in het geheugen op 2048 reeksen voor counters, gauges en histogrammen samen. Nieuwe reeksen boven die limiet worden gedropt, en openclaw_prometheus_series_dropped_total wordt telkens met één verhoogd.Houd deze counter in de gaten als hard signaal dat een bovenstrooms attribuut waarden met hoge cardinaliteit lekt. De exporter verhoogt de limiet nooit automatisch; als deze oploopt, los dan de bron op in plaats van de limiet uit te schakelen.
  • prompttekst, responstekst, tool-inputs, tool-outputs, systeemprompts
  • ruwe provider-request-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
Geef de voorkeur aan gen_ai_client_token_usage voor dashboards over providers heen: deze volgt de OpenTelemetry GenAI-semantische conventies 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-auth.
  • Oppervlak is alleen metrics (geen traces of logs).
  • Het meest geschikt voor stacks die al gestandaardiseerd zijn 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 emitten pas regels na minstens één gebeurtenis.
Het eindpunt vereist de Gateway-operator-scope (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 reeksen. Inspecteer recente metrics op een onverwacht label met hoge cardinaliteit en los dit bij de bron op. De exporter dropt bewust nieuwe reeksen in plaats van labels stilzwijgend te herschrijven.
De Plugin bewaart alleen state in het geheugen. Na een Gateway-herstart worden counters teruggezet naar nul en starten gauges opnieuw bij hun eerstvolgende gerapporteerde waarde. Gebruik PromQL rate() en increase() om resets netjes af te handelen.

​
Gerelateerd