Passer au contenu principal
OpenClaw peut exposer les métriques de diagnostic via le Plugin intégré diagnostics-prometheus. Il écoute les diagnostics internes de confiance et génère un endpoint texte Prometheus à l’adresse : 
GET /api/diagnostics/prometheus
Le type de contenu est text/plain; version=0.0.4; charset=utf-8, le format d’exposition standard de Prometheus.
La route utilise l’authentification Gateway (portée operator). Ne l’exposez pas comme endpoint /metrics public non authentifié. Faites-la scraper via le même chemin d’authentification que celui utilisé pour vos autres API operator.
Pour les traces, journaux, envoi OTLP push et attributs sémantiques OpenTelemetry GenAI, voir OpenTelemetry export.

​
Démarrage rapide

1

Activer le Plugin

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

Redémarrer la Gateway

La route HTTP est enregistrée au démarrage du Plugin, donc rechargez après activation.
3

Scraper la route protégée

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

Configurer 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 quand même la route HTTP mais aucun événement de diagnostic n’alimente l’exporteur, donc la réponse est vide.

​
Métriques exportées

MétriqueTypeLabels
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

​
Politique de labels

Les labels Prometheus restent bornés et à faible cardinalité. L’exporteur n’émet pas d’identifiants de diagnostic bruts tels que runId, sessionKey, sessionId, callId, toolCallId, IDs de message, IDs de chat ou IDs de requête fournisseur.Les valeurs de label 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.
L’exporteur limite les séries temporelles conservées en mémoire à 2048 séries au total, compteurs, gauges et histogrammes confondus. Les nouvelles séries au-delà de ce plafond sont supprimées, et openclaw_prometheus_series_dropped_total s’incrémente de un à chaque occurrence.Surveillez ce compteur comme signal fort qu’un attribut en amont fuit des valeurs à forte cardinalité. L’exporteur ne relève jamais automatiquement ce plafond ; s’il augmente, corrigez la source au lieu de désactiver le plafond.
  • texte d’invite, texte de réponse, entrées d’outil, sorties d’outil, prompts système
  • IDs de requête fournisseur bruts (uniquement des hachages bornés, le cas échéant, sur les spans — jamais sur les métriques)
  • clés de session et IDs de session
  • noms d’hôte, chemins de fichier, valeurs secrètes

​
Recettes PromQL

# Jetons par minute, ventilés par fournisseur
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Dépenses (USD) sur la dernière heure, par modèle
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95e percentile de durée d’exécution du modèle
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO de temps d’attente en file (95p sous 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Séries Prometheus supprimées (alarme de cardinalité)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Préférez gen_ai_client_token_usage pour les tableaux de bord inter-fournisseurs : il suit les conventions sémantiques OpenTelemetry GenAI et reste cohérent avec les métriques des services GenAI non OpenClaw.

​
Choisir entre Prometheus et OpenTelemetry export

OpenClaw prend en charge les deux surfaces indépendamment. Vous pouvez exécuter l’une, l’autre, les deux ou aucune.
  • Modèle pull : Prometheus scrape /api/diagnostics/prometheus.
  • Aucun collecteur externe requis.
  • Authentifié via l’authentification Gateway normale.
  • Surface limitée aux 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 histogrammes n’émettent des lignes qu’après au moins un événement.
L’endpoint requiert la portée operator Gateway (auth: "gateway" avec gatewayRuntimeScopeSurface: "trusted-operator"). Utilisez le même jeton ou mot de passe que Prometheus utilise pour n’importe quelle autre route operator Gateway. Il n’existe pas de mode public non authentifié.
Un nouvel attribut dépasse le plafond de 2048 séries. Inspectez les métriques récentes pour détecter un label à cardinalité anormalement élevée et corrigez-le à la source. L’exporteur supprime volontairement les nouvelles séries au lieu de réécrire silencieusement les labels.
Le Plugin conserve son état uniquement en mémoire. Après un redémarrage de la Gateway, les compteurs repartent à zéro et les gauges redémarrent à leur prochaine valeur rapportée. Utilisez rate() et increase() en PromQL pour gérer proprement les remises à zéro.

​
Associé