Passer au contenu principal

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 peut exposer des métriques de diagnostic au moyen du plugin officiel diagnostics-prometheus. Il écoute les diagnostics internes de confiance et rend un point de terminaison 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 Prometheus standard.
La route utilise l’authentification du Gateway (portée opérateur). Ne l’exposez pas comme point de terminaison /metrics public non authentifié. Scrapez-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 l’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

Scraper 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

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 cette option, le plugin enregistre quand même la route HTTP, mais aucun événement de diagnostic ne circule vers l’exporteur ; la réponse est donc vide.

​
Métriques exportées

MétriqueTypeÉtiquettes
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_byteshistogramaucun
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounteraucun

​
Politique des étiquettes

Les étiquettes Prometheus restent bornées et à faible cardinalité. L’exporteur n’émet pas d’identifiants de diagnostic bruts tels que runId, sessionKey, sessionId, callId, toolCallId, des ID de message, des ID de conversation ou des ID de requête fournisseur.Les valeurs des étiquettes sont expurgées et doivent correspondre à 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’exportateur plafonne les séries temporelles conservées en mémoire à 2048 séries, compteurs, jauges et histogrammes confondus. Les nouvelles séries au-delà de ce plafond sont supprimé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 ne relève jamais le plafond automatiquement ; s’il augmente, corrigez la source au lieu de désactiver le plafond.
  • texte de prompt, texte de réponse, entrées d’outil, sorties d’outil, prompts système
  • transcriptions Talk, charges utiles audio, identifiants d’appel, identifiants de salon, jetons de transfert, identifiants de tour et identifiants de session bruts
  • identifiants 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 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

# 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 multi-fournisseurs : 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, l’autre, les deux ou aucune.
  • Modèle pull : Prometheus collecte /api/diagnostics/prometheus.
  • Aucun collecteur externe requis.
  • Authentification via l’authentification Gateway normale.
  • La surface contient 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 le plafond de 2048 séries. Inspectez les métriques récentes pour repérer un label à cardinalité anormalement élevée et corrigez-le à la source. L’exportateur supprime intentionnellement les nouvelles séries au lieu de réécrire silencieusement les labels.
Le plugin conserve l’état uniquement en mémoire. Après un redémarrage du Gateway, les compteurs reviennent à zéro et les jauges reprennent à leur prochaine valeur rapportée. Utilisez rate() et increase() dans PromQL pour gérer proprement les réinitialisations.

​
Connexe