Vai al contenuto principale
OpenClaw può esporre metriche di diagnostica tramite il Plugin ufficiale diagnostics-prometheus. Ascolta la diagnostica attendibile e gli eventi di stabilità del Gateway emessi dal core, quindi produce un endpoint di testo Prometheus in: 
GET /api/diagnostics/prometheus
Il tipo di contenuto è text/plain; version=0.0.4; charset=utf-8, il formato di esposizione Prometheus standard.
La rotta usa l’autenticazione del Gateway (ambito operatore). Non esporla come endpoint /metrics pubblico non autenticato. Eseguine lo scraping tramite lo stesso percorso di autenticazione che usi per le altre API operatore.
Per tracce, log, push OTLP e attributi semantici GenAI di OpenTelemetry, vedi 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 rotta HTTP viene registrata all’avvio del Plugin, quindi ricarica dopo l’abilitazione.
4

Esegui lo scraping della rotta 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 impostazione, il Plugin registra comunque la route HTTP ma nessun evento diagnostico arriva all’esportatore, quindi la risposta è vuota.

​
Metriche esportate

MetricaTipoEtichette
openclaw_run_completed_totalcontatorechannel, model, outcome, provider, trigger
openclaw_run_duration_secondsistogrammachannel, model, outcome, provider, trigger
openclaw_model_call_totalcontatoreapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondsistogrammaapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcontatorefrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcontatoreagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usageistogrammamodel, provider, token_type
openclaw_model_cost_usd_totalcontatoreagent, channel, model, provider
openclaw_skill_used_totalcontatoreactivation, agent, skill, source
openclaw_tool_execution_totalcontatoreerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondsistogrammaerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcontatoredenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcontatorechannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondsistogrammachannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcontatorechannel, webhook
openclaw_webhook_error_totalcontatorechannel, webhook
openclaw_webhook_duration_secondsistogrammachannel, webhook
openclaw_message_received_totalcontatorechannel, source
openclaw_message_dispatch_started_totalcontatorechannel, source
openclaw_message_dispatch_completed_totalcontatorechannel, outcome, reason, source
openclaw_message_dispatch_duration_secondsistogrammachannel, outcome, reason, source
openclaw_message_processed_totalcontatorechannel, outcome, reason
openclaw_message_processed_duration_secondsistogrammachannel, outcome, reason
openclaw_message_delivery_started_totalcontatorechannel, delivery_kind
openclaw_message_delivery_totalcontatorechannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondsistogrammachannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcontatorebrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondsistogrammabrain, event_type, mode, provider, transport
openclaw_talk_audio_bytesistogrammabrain, event_type, mode, provider, transport
openclaw_queue_lane_sizeindicatorelane
openclaw_queue_lane_wait_secondsistogrammalane
openclaw_session_state_totalcontatorereason, state
openclaw_session_queue_depthindicatorestate
openclaw_session_turn_created_totalcontatoreagent, channel, trigger
openclaw_session_stuck_totalcontatorereason, state
openclaw_session_stuck_age_secondsistogrammareason, state
openclaw_session_recovery_totalcontatoreaction, active_work_kind, state, status
openclaw_session_recovery_age_secondsistogrammaaction, active_work_kind, state, status
openclaw_liveness_warning_totalcontatorereason
openclaw_liveness_sessionsindicatorestate
openclaw_liveness_event_loop_delay_p99_secondsistogrammareason
openclaw_liveness_event_loop_delay_max_secondsistogrammareason
openclaw_liveness_event_loop_utilization_ratioistogrammareason
openclaw_liveness_cpu_core_ratioistogrammareason
openclaw_payload_large_totalcontatoreaction, channel, plugin, reason, surface
openclaw_payload_large_bytesistogrammaaction, channel, plugin, reason, surface
openclaw_memory_bytesindicatorekind
openclaw_memory_rss_bytesistogrammanessuna
openclaw_memory_pressure_totalcontatorelevel, reason
openclaw_telemetry_exporter_totalcontatoreexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcontatorenessuna

​
Criterio 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 oscurati e devono corrispondere al criterio di OpenClaw per caratteri a bassa cardinalità. I valori che non soddisfano il criterio vengono sostituiti con unknown, other o none, a seconda della metrica. Anche le etichette che sembrano chiavi di sessione agente con ambito vengono sostituite con unknown.
L’esportatore limita le serie temporali mantenute in memoria a 2048 serie complessive tra contatori, indicatori e istogrammi. Le nuove serie oltre tale limite vengono scartate e openclaw_prometheus_series_dropped_total viene incrementato di uno ogni volta.Monitora questo contatore come segnale forte che un attributo a monte sta perdendo valori ad alta cardinalità. L’esportatore non aumenta mai automaticamente il limite; se cresce, correggi l’origine invece di disabilitare il limite.
  • testo del prompt, testo della risposta, input degli strumenti, output degli strumenti, prompt di sistema
  • trascrizioni Talk, payload audio, ID chiamata, ID stanza, token di handoff, ID turno e ID sessione grezzi
  • ID richiesta provider grezzi (solo hash limitati, ove 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

# 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
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 eseguirne una, entrambe o nessuna.
  • Modello Pull: Prometheus esegue lo scrape di /api/diagnostics/prometheus.
  • Non richiede un collector esterno.
  • Autenticato 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 elevata e correggila alla fonte. L’exporter elimina 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 tornano a zero e i gauge ripartono dal successivo valore riportato. Usa rate() e increase() di PromQL per gestire i reset in modo pulito.

​
Correlati