Vai al contenuto principale

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 può esporre metriche diagnostiche tramite il plugin ufficiale diagnostics-prometheus. Ascolta diagnostica interna attendibile e restituisce un endpoint di testo Prometheus a: 
GET /api/diagnostics/prometheus
Il tipo di contenuto è text/plain; version=0.0.4; charset=utf-8, il formato standard di esposizione Prometheus.
La route usa l’autenticazione del Gateway (ambito operatore). Non esporla come endpoint /metrics pubblico non autenticato. Esegui lo scraping tramite lo stesso percorso di autenticazione che usi per le altre API operatore.
Per tracce, log, push OTLP e attributi semantici OpenTelemetry GenAI, consulta esportazione OpenTelemetry.

​
Avvio rapido

1

Installa il plugin

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

Abilita il plugin

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

Riavvia il Gateway

La route HTTP viene registrata all’avvio del plugin, quindi ricarica dopo l’abilitazione.
4

Esegui lo scraping della route protetta

Invia la stessa autenticazione del Gateway usata dai tuoi client operatore:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Collega 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 è obbligatorio. Senza questa opzione, il plugin registra comunque la route HTTP, ma nessun evento diagnostico arriva all’esportatore, quindi la risposta è vuota.

​
Metriche esportate

MetricaTipoEtichette
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_byteshistogramnessuna
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternessuna

​
Criteri per le etichette

Le etichette Prometheus restano limitate e a bassa cardinalità. L’esportatore non emette identificatori diagnostici grezzi come runId, sessionKey, sessionId, callId, toolCallId, ID dei messaggi, ID delle chat o ID delle richieste del provider.I valori delle etichette vengono redatti e devono rispettare i criteri di OpenClaw per i caratteri a bassa cardinalità. I valori che non soddisfano i criteri vengono sostituiti con unknown, other o none, a seconda della metrica.
L’esportatore limita le serie temporali mantenute in memoria a 2048 serie complessive tra contatori, gauge e istogrammi. Le nuove serie oltre questo limite vengono scartate e openclaw_prometheus_series_dropped_total aumenta di uno ogni volta.Monitora questo contatore come segnale forte che un attributo a monte sta lasciando trapelare valori ad alta cardinalità. L’esportatore non aumenta mai automaticamente il limite; se cresce, correggi la sorgente invece di disabilitare il limite.
  • testo del prompt, testo della risposta, input degli strumenti, output degli strumenti, prompt di sistema
  • trascrizioni delle conversazioni, payload audio, ID chiamata, ID stanza, token di passaggio, ID turno e ID sessione grezzi
  • ID richiesta provider grezzi (solo hash limitati, dove applicabile, sugli span — mai sulle metriche)
  • chiavi di sessione e ID sessione
  • nomi host, percorsi file, valori segreti

​
Ricette PromQL

# 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
Preferisci gen_ai_client_token_usage per dashboard multi-provider: segue le convenzioni semantiche OpenTelemetry GenAI ed è coerente con le metriche dei servizi GenAI non OpenClaw.

​
Scegliere tra esportazione Prometheus e OpenTelemetry

OpenClaw supporta entrambe le superfici in modo indipendente. Puoi eseguirne una, entrambe o nessuna.
  • Modello pull: Prometheus esegue lo scraping di /api/diagnostics/prometheus.
  • Non è richiesto alcun collector esterno.
  • Autenticazione tramite la normale autenticazione del Gateway.
  • La superficie include solo metriche (nessuna traccia o log).
  • Ideale per stack già standardizzati su Prometheus + Grafana.

​
Risoluzione dei problemi

  • Controlla diagnostics.enabled: true nella configurazione.
  • Conferma che il Plugin sia abilitato e caricato con openclaw plugins list --enabled.
  • Genera un po’ di traffico; contatori e istogrammi emettono righe solo dopo almeno un evento.
L’endpoint richiede l’ambito operatore del Gateway (auth: "gateway" con gatewayRuntimeScopeSurface: "trusted-operator"). Usa lo stesso token o la stessa password che Prometheus usa per qualsiasi altra route operatore del Gateway. Non esiste una modalità pubblica non autenticata.
Un nuovo attributo sta superando il limite di 2048 serie. Ispeziona le metriche recenti per individuare un’etichetta con cardinalità inaspettatamente alta e correggila alla sorgente. L’esportatore scarta intenzionalmente le nuove serie invece di riscrivere silenziosamente le etichette.
Il Plugin mantiene lo stato solo in memoria. Dopo un riavvio del Gateway, i contatori vengono reimpostati a zero e i gauge ripartono dal successivo valore riportato. Usa PromQL rate() e increase() per gestire correttamente i reset.

​
Correlati