Gateway

Métriques Prometheus

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.

Pour les traces, les journaux, le push OTLP et les attributs sémantiques OpenTelemetry GenAI, consultez l’export OpenTelemetry.

Démarrage rapide

Installer le plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

Activer le plugin

Configuration

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

CLI

openclaw plugins enable diagnostics-prometheus

Redémarrer le Gateway

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

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

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"]

Métriques exportées

Métrique	Type	Étiquettes
`openclaw_run_completed_total`	counter	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	histogram	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	counter	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	histogram	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_tokens_total`	counter	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	histogram	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	counter	`agent`, `channel`, `model`, `provider`
`openclaw_tool_execution_total`	counter	`error_category`, `outcome`, `params_kind`, `tool`
`openclaw_tool_execution_duration_seconds`	histogram	`error_category`, `outcome`, `params_kind`, `tool`
`openclaw_harness_run_total`	counter	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_harness_run_duration_seconds`	histogram	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_message_processed_total`	counter	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	histogram	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	counter	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	counter	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	histogram	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	counter	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_event_duration_seconds`	histogram	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_audio_bytes`	histogram	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_queue_lane_size`	gauge	`lane`
`openclaw_queue_lane_wait_seconds`	histogram	`lane`
`openclaw_session_state_total`	counter	`reason`, `state`
`openclaw_session_queue_depth`	gauge	`state`
`openclaw_session_recovery_total`	counter	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	histogram	`action`, `active_work_kind`, `state`, `status`
`openclaw_memory_bytes`	gauge	`kind`
`openclaw_memory_rss_bytes`	histogram	aucun
`openclaw_memory_pressure_total`	counter	`level`, `reason`
`openclaw_telemetry_exporter_total`	counter	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	counter	aucun

Politique des étiquettes

Étiquettes bornées et à faible cardinalité

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.

Plafond des séries et comptabilisation des dépassements

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.

Ce qui n’apparaît jamais dans la sortie Prometheus

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

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.

diagnostics-prometheus

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.

diagnostics-otel

Modèle push : OpenClaw envoie OTLP/HTTP à un collecteur ou à un backend compatible OTLP.
La surface inclut métriques, traces et journaux.
Fait le pont vers Prometheus via un OpenTelemetry Collector (exportateur prometheus ou prometheusremotewrite) lorsque vous avez besoin des deux.
Consultez Export OpenTelemetry pour le catalogue complet.

Dépannage

Corps de réponse vide

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.

401 / non autorisé

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é.

`openclaw_prometheus_series_dropped_total` augmente

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.

Prometheus affiche des séries obsolètes après un redémarrage

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

Export des diagnostics — archive ZIP de diagnostics locale pour les paquets d’assistance
Santé et disponibilité — sondes /healthz et /readyz
Journalisation — journalisation basée sur des fichiers
Export OpenTelemetry — envoi OTLP pour les traces, les métriques et les journaux

# Démarrage rapide

Installer le plugin

Activer le plugin

Configuration

CLI

Redémarrer le Gateway

Scraper la route protégée

Configurer Prometheus

# Métriques exportées

# Politique des étiquettes

# Recettes PromQL

# Choisir entre l’export Prometheus et OpenTelemetry

diagnostics-prometheus

diagnostics-otel

# Dépannage

# Connexe

Démarrage rapide

Métriques exportées

Politique des étiquettes

Recettes PromQL

Choisir entre l’export Prometheus et OpenTelemetry

Dépannage

Connexe