Vai al contenuto principale
OpenClaw può esporre metriche diagnostiche tramite il Plugin incluso diagnostics-prometheus. Il Plugin ascolta la diagnostica interna attendibile e rende disponibile un endpoint testuale Prometheus su: 
GET /api/diagnostics/prometheus
Il content type è text/plain; version=0.0.4; charset=utf-8, il formato di esposizione standard di Prometheus.
La route usa l’autenticazione del Gateway (scope operatore). Non esporla come endpoint pubblico /metrics senza autenticazione. Esegui lo scraping tramite lo stesso percorso auth che usi per le altre API operatore.
Per trace, log, push OTLP e attributi semantici GenAI di OpenTelemetry, consulta OpenTelemetry export.

​
Avvio rapido

1

Abilita il Plugin

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

Riavvia il Gateway

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

Esegui lo scraping della route protetta

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

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 di esso, il Plugin registra comunque la route HTTP ma nessun evento diagnostico fluisce verso l’exporter, quindi la risposta è vuota.

​
Metriche esportate

MetricaTipoLabel
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

​
Policy delle label

Le label Prometheus restano limitate e a bassa cardinalità. L’exporter non emette identificatori diagnostici grezzi come runId, sessionKey, sessionId, callId, toolCallId, ID messaggio, ID chat o ID richiesta del provider.I valori delle label vengono redatti e devono rispettare la policy dei caratteri a bassa cardinalità di OpenClaw. I valori che non la rispettano vengono sostituiti con unknown, other o none, a seconda della metrica.
L’exporter limita le serie temporali mantenute in memoria a 2048 serie complessive tra counter, gauge e histogram. Le nuove serie oltre questo limite vengono scartate e openclaw_prometheus_series_dropped_total aumenta di uno ogni volta.Monitora questo counter come segnale forte che un attributo upstream sta lasciando passare valori ad alta cardinalità. L’exporter non alza 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, system prompt
  • ID richiesta grezzi del provider (solo hash limitati, dove applicabile, negli span — mai nelle metriche)
  • chiavi di sessione e ID sessione
  • hostname, percorsi file, valori segreti

​
Ricette PromQL

# Token al minuto, suddivisi per provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spesa (USD) nell'ultima ora, per modello
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95° percentile della durata di esecuzione del modello
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO del tempo di attesa in coda (95p sotto 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Serie Prometheus scartate (allarme cardinalità)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Preferisci gen_ai_client_token_usage per dashboard cross-provider: segue le convenzioni semantiche GenAI di OpenTelemetry ed è coerente con le metriche di servizi GenAI non OpenClaw.

​
Scegliere tra esportazione Prometheus e OpenTelemetry

OpenClaw supporta entrambe le superfici in modo indipendente. Puoi usare una sola, entrambe o nessuna.
  • Modello pull: Prometheus esegue lo scraping di /api/diagnostics/prometheus.
  • Non richiede un collector esterno.
  • Autenticato tramite la normale auth del Gateway.
  • La superficie include solo metriche (nessuna trace o log).
  • Ideale per stack già standardizzati su Prometheus + Grafana.

​
Risoluzione dei problemi

  • Controlla diagnostics.enabled: true nella config.
  • Conferma che il Plugin sia abilitato e caricato con openclaw plugins list --enabled.
  • Genera un po’ di traffico; counter e histogram emettono righe solo dopo almeno un evento.
L’endpoint richiede lo scope 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 senza autenticazione.
Un nuovo attributo sta superando il limite di 2048 serie. Ispeziona le metriche recenti per trovare una label con cardinalità inaspettatamente alta e correggila alla sorgente. L’exporter scarta intenzionalmente le nuove serie invece di riscrivere silenziosamente le label.
Il Plugin mantiene lo stato solo in memoria. Dopo un riavvio del Gateway, i counter vengono azzerati e i gauge ripartono dal loro successivo valore riportato. Usa PromQL rate() e increase() per gestire i reset in modo pulito.

​
Correlati