Passer au contenu principal
OpenClaw peut exposer des métriques de diagnostic via le Plugin officiel diagnostics-prometheus. Il écoute les diagnostics approuvés ainsi que les événements de stabilité du Gateway émis par le noyau, puis affiche un point de terminaison texte Prometheus à : 
GET /api/diagnostics/prometheus
Le type de contenu est text/plain; version=0.0.4; charset=utf-8, le format d’exposition Prometheus standard.
La route utilise l’authentification Gateway (portée opérateur). Ne l’exposez pas comme un point de terminaison /metrics public non authentifié. Collectez-la via le même chemin d’authentification que celui que vous utilisez pour les autres API opérateur.
Pour les traces, les journaux, le push OTLP et les attributs sémantiques OpenTelemetry GenAI, consultez Export OpenTelemetry.

​
Démarrage rapide

1

Installer le Plugin

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

Activer le Plugin

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

Redémarrer le Gateway

La route HTTP est enregistrée au démarrage du Plugin ; rechargez donc après l’activation.
4

Collecter la route protégée

Envoyez la même authentification Gateway que celle utilisée par vos clients opérateur :
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Câbler 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 est requis. Sans cela, le Plugin enregistre toujours la route HTTP, mais aucun événement de diagnostic n’arrive dans l’exportateur ; la réponse est donc vide.

​
Métriques exportées

MétriqueTypeÉtiquettes
openclaw_run_completed_totalcompteurchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogrammechannel, model, outcome, provider, trigger
openclaw_model_call_totalcompteurapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogrammeapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcompteurfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcompteuragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammemodel, provider, token_type
openclaw_model_cost_usd_totalcompteuragent, channel, model, provider
openclaw_skill_used_totalcompteuractivation, agent, skill, source
openclaw_tool_execution_totalcompteurerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogrammeerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcompteurdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcompteurchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogrammechannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcompteurchannel, webhook
openclaw_webhook_error_totalcompteurchannel, webhook
openclaw_webhook_duration_secondshistogrammechannel, webhook
openclaw_message_received_totalcompteurchannel, source
openclaw_message_dispatch_started_totalcompteurchannel, source
openclaw_message_dispatch_completed_totalcompteurchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogrammechannel, outcome, reason, source
openclaw_message_processed_totalcompteurchannel, outcome, reason
openclaw_message_processed_duration_secondshistogrammechannel, outcome, reason
openclaw_message_delivery_started_totalcompteurchannel, delivery_kind
openclaw_message_delivery_totalcompteurchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogrammechannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcompteurbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrammebrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrammebrain, event_type, mode, provider, transport
openclaw_queue_lane_sizejaugelane
openclaw_queue_lane_wait_secondshistogrammelane
openclaw_session_state_totalcompteurreason, state
openclaw_session_queue_depthjaugestate
openclaw_session_turn_created_totalcompteuragent, channel, trigger
openclaw_session_stuck_totalcompteurreason, state
openclaw_session_stuck_age_secondshistogrammereason, state
openclaw_session_recovery_totalcompteuraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogrammeaction, active_work_kind, state, status
openclaw_liveness_warning_totalcompteurreason
openclaw_liveness_sessionsjaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogrammereason
openclaw_liveness_event_loop_delay_max_secondshistogrammereason
openclaw_liveness_event_loop_utilization_ratiohistogrammereason
openclaw_liveness_cpu_core_ratiohistogrammereason
openclaw_payload_large_totalcompteuraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogrammeaction, channel, plugin, reason, surface
openclaw_memory_bytesjaugekind
openclaw_memory_rss_byteshistogrammeaucune
openclaw_memory_pressure_totalcompteurlevel, reason
openclaw_telemetry_exporter_totalcompteurexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcompteuraucune

​
Politique des étiquettes

Les étiquettes Prometheus restent bornées et à faible cardinalité. L’exportateur n’émet pas d’identifiants de diagnostic bruts tels que runId, sessionKey, sessionId, callId, toolCallId, les ID de message, les ID de discussion ou les ID de requête fournisseur.Les valeurs d’étiquette sont expurgées et doivent respecter la politique de caractères à faible cardinalité d’OpenClaw. Les valeurs qui ne respectent pas cette politique sont remplacées par unknown, other ou none, selon la métrique. Les étiquettes qui ressemblent à des clés de session d’agent délimitées sont également remplacées par unknown.
L’exportateur plafonne les séries temporelles conservées en mémoire à 2048 séries au total, compteurs, jauges et histogrammes confondus. Les nouvelles séries au-delà de ce plafond sont abandonnées, et openclaw_prometheus_series_dropped_total est incrémenté de un à chaque fois.Surveillez ce compteur comme un signal fort indiquant qu’un attribut en amont laisse fuiter des valeurs à forte cardinalité. L’exportateur n’augmente jamais automatiquement le plafond ; s’il monte, corrigez la source plutôt que de désactiver le plafond.
  • texte d’invite, texte de réponse, entrées d’outils, sorties d’outils, invites système
  • transcriptions de conversation, charges audio, identifiants d’appel, identifiants de salle, jetons de transfert, identifiants de tour et identifiants de session bruts
  • identifiants de requête de fournisseur bruts (uniquement des hachages bornés, le cas échéant, sur les spans — jamais sur les métriques)
  • clés de session et identifiants de session
  • noms d’hôte, chemins de fichiers, valeurs secrètes

​
Recettes 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
Préférez gen_ai_client_token_usage pour les tableaux de bord multifournisseurs : il suit les conventions sémantiques OpenTelemetry GenAI et reste cohérent avec les métriques des services GenAI non OpenClaw.

​
Choisir entre l’export Prometheus et OpenTelemetry

OpenClaw prend en charge les deux surfaces indépendamment. Vous pouvez utiliser l’une, les deux ou aucune.
  • Modèle pull : Prometheus collecte /api/diagnostics/prometheus.
  • Aucun collecteur externe requis.
  • Authentifié via l’authentification Gateway normale.
  • La surface expose uniquement des métriques (pas de traces ni de journaux).
  • Idéal pour les piles déjà standardisées sur Prometheus + Grafana.

​
Dépannage

  • Vérifiez diagnostics.enabled: true dans la configuration.
  • Confirmez que le Plugin est activé et chargé avec openclaw plugins list --enabled.
  • Générez du trafic ; les compteurs et les histogrammes n’émettent des lignes qu’après au moins un événement.
Le point de terminaison nécessite le périmètre opérateur Gateway (auth: "gateway" avec gatewayRuntimeScopeSurface: "trusted-operator"). Utilisez le même jeton ou mot de passe que Prometheus utilise pour toute autre route opérateur Gateway. Il n’existe aucun mode public non authentifié.
Un nouvel attribut dépasse la limite de 2048 séries. Inspectez les métriques récentes pour repérer une étiquette à cardinalité anormalement élevée et corrigez-la à la source. L’exportateur supprime intentionnellement les nouvelles séries au lieu de réécrire silencieusement les étiquettes.
Le Plugin conserve l’état uniquement en mémoire. Après un redémarrage du Gateway, les compteurs sont remis à zéro et les jauges redémarrent à leur prochaine valeur signalée. Utilisez rate() et increase() PromQL pour gérer proprement les réinitialisations.

​
Connexe