Gateway

Export OpenTelemetry

OpenClaw exporte des diagnostics via le Plugin officiel diagnostics-otel avec OTLP/HTTP (protobuf). Tout collecteur ou backend qui accepte OTLP/HTTP fonctionne sans modification de code. Pour les journaux locaux dans des fichiers et la manière de les lire, consultez Journalisation.

Fonctionnement général

Les événements de diagnostic sont des enregistrements structurés, en processus, émis par le Gateway et les plugins intégrés pour les exécutions de modèles, le flux de messages, les sessions, les files d’attente et exec.
Le Plugin diagnostics-otel s’abonne à ces événements et les exporte sous forme de métriques, traces et journaux OpenTelemetry via OTLP/HTTP.
Les appels fournisseur reçoivent un en-tête W3C traceparent depuis le contexte de span d’appel de modèle approuvé d’OpenClaw lorsque le transport du fournisseur accepte les en-têtes personnalisés. Le contexte de trace émis par les Plugins n’est pas propagé.
Les exportateurs ne s’attachent que lorsque la surface de diagnostics et le Plugin sont tous deux activés, de sorte que le coût en processus reste proche de zéro par défaut.

Démarrage rapide

Pour les installations packagées, installez d’abord le Plugin :

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

Vous pouvez aussi activer le Plugin depuis la CLI :

openclaw plugins enable diagnostics-otel

Signaux exportés

Signal	Ce qu’il contient
Métriques	Compteurs et histogrammes pour l’utilisation des tokens, les coûts, la durée d’exécution, le flux de messages, les événements Talk, les files d’attente, l’état/la récupération des sessions, exec et la pression mémoire.
Traces	Spans pour l’utilisation des modèles, les appels de modèles, le cycle de vie du harnais, l’exécution d’outils, exec, le traitement des webhooks/messages, l’assemblage du contexte et les boucles d’outils.
Journaux	Enregistrements `logging.file` structurés exportés via OTLP lorsque `diagnostics.otel.logs` est activé.

Activez ou désactivez traces, metrics et logs indépendamment. Les trois sont activés par défaut lorsque diagnostics.otel.enabled vaut true.

Référence de configuration

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

Variables d’environnement

Variable	Objectif
`OTEL_EXPORTER_OTLP_ENDPOINT`	Remplace `diagnostics.otel.endpoint`. Si la valeur contient déjà `/v1/traces`, `/v1/metrics` ou `/v1/logs`, elle est utilisée telle quelle.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Remplacements de point de terminaison propres au signal, utilisés lorsque la clé de configuration `diagnostics.otel.*Endpoint` correspondante n’est pas définie. La configuration propre au signal l’emporte sur l’environnement propre au signal, qui l’emporte sur le point de terminaison partagé.
`OTEL_SERVICE_NAME`	Remplace `diagnostics.otel.serviceName`.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Remplace le protocole filaire (seul `http/protobuf` est pris en compte aujourd’hui).
`OTEL_SEMCONV_STABILITY_OPT_IN`	Définissez sur `gen_ai_latest_experimental` pour émettre le dernier attribut expérimental de span GenAI (`gen_ai.provider.name`) au lieu de l’ancien `gen_ai.system`. Les métriques GenAI utilisent toujours des attributs sémantiques bornés et à faible cardinalité.
`OPENCLAW_OTEL_PRELOADED`	Définissez sur `1` lorsqu’un autre préchargement ou processus hôte a déjà enregistré le SDK OpenTelemetry global. Le Plugin ignore alors son propre cycle de vie NodeSDK, mais câble toujours les écouteurs de diagnostics et respecte `traces`/`metrics`/`logs`.

Confidentialité et capture de contenu

Le contenu brut des modèles/outils n’est pas exporté par défaut. Les spans transportent des identifiants bornés (canal, fournisseur, modèle, catégorie d’erreur, identifiants de requête sous forme de hash uniquement) et n’incluent jamais le texte des prompts, le texte des réponses, les entrées d’outils, les sorties d’outils ni les clés de session. Les métriques Talk n’exportent que des métadonnées d’événement bornées telles que le mode, le transport, le fournisseur et le type d’événement. Elles n’incluent pas les transcriptions, charges utiles audio, identifiants de session, identifiants de tour, identifiants d’appel, identifiants de salon ni jetons de transfert.

Les requêtes sortantes vers les modèles peuvent inclure un en-tête W3C traceparent. Cet en-tête est généré uniquement à partir du contexte de trace de diagnostic appartenant à OpenClaw pour l’appel de modèle actif. Les en-têtes traceparent fournis par l’appelant existant sont remplacés, de sorte que les Plugins ou options de fournisseur personnalisées ne peuvent pas usurper l’ascendance de trace interservices.

Définissez diagnostics.otel.captureContent.* sur true uniquement lorsque votre collecteur et votre politique de rétention sont approuvés pour le texte des prompts, réponses, outils ou prompts système. Chaque sous-clé est activable indépendamment :

inputMessages - contenu du prompt utilisateur.
outputMessages - contenu de la réponse du modèle.
toolInputs - charges utiles des arguments d’outil.
toolOutputs - charges utiles des résultats d’outil.
systemPrompt - prompt système/développeur assemblé.

Lorsqu’une sous-clé est activée, les spans de modèle et d’outil reçoivent des attributs openclaw.content.* bornés et expurgés pour cette classe uniquement.

Échantillonnage et vidage

Traces : diagnostics.otel.sampleRate (span racine uniquement, 0.0 supprime tout, 1.0 conserve tout).
Métriques : diagnostics.otel.flushIntervalMs (minimum 1000).
Journaux : les journaux OTLP respectent logging.level (niveau du journal fichier). Ils utilisent le chemin d’expurgation des enregistrements de journal de diagnostic, pas le formatage console. Les installations à volume élevé devraient privilégier l’échantillonnage/filtrage du collecteur OTLP plutôt que l’échantillonnage local.
Corrélation des journaux fichier : les journaux de fichier JSONL incluent traceId, spanId, parentSpanId et traceFlags au niveau supérieur lorsque l’appel de journal transporte un contexte de trace de diagnostic valide, ce qui permet aux processeurs de journaux de joindre les lignes de journal locales aux spans exportés.
Corrélation des requêtes : les requêtes HTTP du Gateway et les trames WebSocket créent une portée de trace de requête interne. Les journaux et événements de diagnostic à l’intérieur de cette portée héritent de la trace de requête par défaut, tandis que les spans d’exécution d’agent et d’appel de modèle sont créés comme enfants afin que les en-têtes traceparent du fournisseur restent sur la même trace.

Métriques exportées

Utilisation du modèle

openclaw.tokens (compteur, attrs : openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
openclaw.cost.usd (compteur, attrs : openclaw.channel, openclaw.provider, openclaw.model)
openclaw.run.duration_ms (histogramme, attrs : openclaw.channel, openclaw.provider, openclaw.model)
openclaw.context.tokens (histogramme, attrs : openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
gen_ai.client.token.usage (histogramme, métrique de conventions sémantiques GenAI, attrs : gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
gen_ai.client.operation.duration (histogramme, secondes, métrique de conventions sémantiques GenAI, attrs : gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, error.type facultatif)
openclaw.model_call.duration_ms (histogramme, attrs : openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, plus openclaw.errorCategory et openclaw.failureKind sur les erreurs classifiées)
openclaw.model_call.request_bytes (histogramme, taille en octets UTF-8 de la charge utile finale de requête au modèle ; aucun contenu brut de charge utile)
openclaw.model_call.response_bytes (histogramme, taille en octets UTF-8 des événements de réponse de modèle diffusés ; aucun contenu brut de réponse)
openclaw.model_call.time_to_first_byte_ms (histogramme, temps écoulé avant le premier événement de réponse diffusé)

Flux de messages

openclaw.webhook.received (compteur, attrs : openclaw.channel, openclaw.webhook)
openclaw.webhook.error (compteur, attrs : openclaw.channel, openclaw.webhook)
openclaw.webhook.duration_ms (histogramme, attrs : openclaw.channel, openclaw.webhook)
openclaw.message.queued (compteur, attrs : openclaw.channel, openclaw.source)
openclaw.message.processed (compteur, attrs : openclaw.channel, openclaw.outcome)
openclaw.message.duration_ms (histogramme, attrs : openclaw.channel, openclaw.outcome)
openclaw.message.delivery.started (compteur, attrs : openclaw.channel, openclaw.delivery.kind)
openclaw.message.delivery.duration_ms (histogramme, attrs : openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

Talk

openclaw.talk.event (compteur, attrs : openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
openclaw.talk.event.duration_ms (histogramme, attrs : identiques à openclaw.talk.event ; émis lorsqu’un événement Talk indique une durée)
openclaw.talk.audio.bytes (histogramme, attrs : identiques à openclaw.talk.event ; émis pour les événements de trame audio Talk qui indiquent une longueur en octets)

Files d’attente et sessions

openclaw.queue.lane.enqueue (compteur, attrs : openclaw.lane)
openclaw.queue.lane.dequeue (compteur, attrs : openclaw.lane)
openclaw.queue.depth (histogramme, attrs : openclaw.lane ou openclaw.channel=heartbeat)
openclaw.queue.wait_ms (histogramme, attrs : openclaw.lane)
openclaw.session.state (compteur, attrs : openclaw.state, openclaw.reason)
openclaw.session.stuck (compteur, attrs : openclaw.state ; émis uniquement pour la tenue de session obsolète sans travail actif)
openclaw.session.stuck_age_ms (histogramme, attrs : openclaw.state ; émis uniquement pour la tenue de session obsolète sans travail actif)
openclaw.session.recovery.requested (compteur, attrs : openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
openclaw.session.recovery.completed (compteur, attrs : openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
openclaw.session.recovery.age_ms (histogramme, attrs : identiques au compteur de récupération correspondant)
openclaw.run.attempt (compteur, attrs : openclaw.attempt)

Télémétrie de disponibilité des sessions

diagnostics.stuckSessionWarnMs est le seuil d'âge sans progression pour les diagnostics de disponibilité des sessions. Une session processing ne progresse pas vers ce seuil tant qu'OpenClaw observe une progression de réponse, d'outil, d'état, de bloc ou d'exécution ACP. Les signaux de maintien de frappe ne sont pas comptés comme une progression, ce qui permet toujours de détecter un modèle ou un harnais silencieux.

OpenClaw classe les sessions selon le travail qu'il peut encore observer :

session.long_running : du travail intégré actif, des appels de modèle ou des appels d'outil progressent encore.
session.stalled : du travail actif existe, mais l'exécution active n'a pas signalé de progression récente. Les exécutions intégrées bloquées restent d'abord en observation seule, puis passent en abandon-drain après diagnostics.stuckSessionAbortMs sans progression afin que les tours en file d'attente derrière la voie puissent reprendre. Lorsque ce paramètre n'est pas défini, le seuil d'abandon prend par défaut une fenêtre étendue plus sûre d'au moins 10 minutes et 5x diagnostics.stuckSessionWarnMs.
session.stuck : tenue de session obsolète sans travail actif. Cela libère immédiatement la voie de session affectée.

La récupération émet des événements structurés session.recovery.requested et session.recovery.completed. L'état de session de diagnostic n'est marqué comme inactif qu'après un résultat de récupération modifiant l'état (aborted ou released) et uniquement si la même génération de traitement est toujours courante.

Seul session.stuck émet le compteur openclaw.session.stuck, l'histogramme openclaw.session.stuck_age_ms et le span openclaw.session.stuck. Les diagnostics session.stuck répétés appliquent un backoff tant que la session reste inchangée ; les tableaux de bord doivent donc déclencher des alertes sur des augmentations soutenues plutôt qu'à chaque tick de Heartbeat. Pour le réglage de configuration et les valeurs par défaut, consultez la référence de configuration.

Cycle de vie du harnais

openclaw.harness.duration_ms (histogramme, attrs : openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase en cas d'erreur)

Exécution

openclaw.exec.duration_ms (histogramme, attrs : openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

Internes de diagnostic (mémoire et boucle d'outils)

openclaw.memory.heap_used_bytes (histogramme, attrs : openclaw.memory.kind)
openclaw.memory.rss_bytes (histogramme)
openclaw.memory.pressure (compteur, attrs : openclaw.memory.level)
openclaw.tool.loop.iterations (compteur, attrs : openclaw.toolName, openclaw.outcome)
openclaw.tool.loop.duration_ms (histogramme, attrs : openclaw.toolName, openclaw.outcome)

Spans exportés

openclaw.model.usage
- openclaw.channel, openclaw.provider, openclaw.model
- openclaw.tokens.* (input/output/cache_read/cache_write/total)
- gen_ai.system par défaut, ou gen_ai.provider.name lorsque les dernières conventions sémantiques GenAI sont activées
- gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*
openclaw.run
- openclaw.outcome, openclaw.channel, openclaw.provider, openclaw.model, openclaw.errorCategory
openclaw.model.call
- gen_ai.system par défaut, ou gen_ai.provider.name lorsque les dernières conventions sémantiques GenAI sont activées
- gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
- openclaw.errorCategory et openclaw.failureKind facultatif en cas d'erreur
- openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
- openclaw.provider.request_id_hash (hachage borné basé sur SHA de l'identifiant de requête du fournisseur amont ; les identifiants bruts ne sont pas exportés)
openclaw.harness.run
- openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
- À la fin : openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
- En cas d'erreur : openclaw.harness.phase, openclaw.errorCategory, openclaw.harness.cleanup_failed facultatif
openclaw.tool.execution
- gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
openclaw.exec
- openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.timed_out
openclaw.webhook.processed
- openclaw.channel, openclaw.webhook
openclaw.webhook.error
- openclaw.channel, openclaw.webhook, openclaw.error
openclaw.message.processed
- openclaw.channel, openclaw.outcome, openclaw.reason
openclaw.message.delivery
- openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
openclaw.session.stuck
- openclaw.state, openclaw.ageMs, openclaw.queueDepth
openclaw.context.assembled
- openclaw.prompt.size, openclaw.history.size, openclaw.context.tokens, openclaw.errorCategory (aucun contenu d'invite, d'historique, de réponse ou de clé de session)
openclaw.tool.loop
- openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (aucun message de boucle, paramètre ou sortie d'outil)
openclaw.memory.pressure
- openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Lorsque la capture de contenu est explicitement activée, les spans de modèle et d'outil peuvent également inclure des attributs openclaw.content.* bornés et expurgés pour les classes de contenu spécifiques auxquelles vous avez souscrit.

Catalogue des événements de diagnostic

Les événements ci-dessous alimentent les métriques et spans ci-dessus. Les Plugins peuvent également s'y abonner directement sans export OTLP.

Utilisation du modèle

model.usage - jetons, coût, durée, contexte, fournisseur/modèle/canal, identifiants de session. usage correspond à la comptabilité fournisseur/tour pour le coût et la télémétrie ; context.used est l'instantané courant d'invite/contexte et peut être inférieur au usage.total du fournisseur lorsque des entrées mises en cache ou des appels de boucle d'outils sont impliqués.

Flux des messages

webhook.received / webhook.processed / webhook.error
message.queued / message.processed
message.delivery.started / message.delivery.completed / message.delivery.error

File d'attente et session

queue.lane.enqueue / queue.lane.dequeue
session.state / session.long_running / session.stalled / session.stuck
run.attempt / run.progress
diagnostic.heartbeat (compteurs agrégés : webhooks/file d'attente/session)

Cycle de vie du harnais

harness.run.started / harness.run.completed / harness.run.error - cycle de vie par exécution pour le harnais d'agent. Inclut harnessId, pluginId facultatif, fournisseur/modèle/canal et identifiant d'exécution. La fin ajoute durationMs, outcome, resultClassification facultatif, yieldDetected et les comptes itemLifecycle. Les erreurs ajoutent phase (prepare/start/send/resolve/cleanup), errorCategory et cleanupFailed facultatif.

Exécution

exec.process.completed - résultat terminal, durée, cible, mode, code de sortie et type d'échec. Le texte de commande et les répertoires de travail ne sont pas inclus.

Sans exportateur

Vous pouvez garder les événements de diagnostic disponibles pour les Plugins ou les collecteurs personnalisés sans exécuter diagnostics-otel :

{
  diagnostics: { enabled: true },
}

Pour une sortie de débogage ciblée sans augmenter logging.level, utilisez les drapeaux de diagnostic. Les drapeaux sont insensibles à la casse et prennent en charge les caractères génériques (par exemple telegram.* ou *) :

{
  diagnostics: { flags: ["telegram.http"] },
}

Ou comme surcharge d'environnement ponctuelle :

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

La sortie des drapeaux est écrite dans le fichier journal standard (logging.file) et reste expurgée par logging.redactSensitive. Guide complet : Drapeaux de diagnostic.

Désactiver

{
  diagnostics: { otel: { enabled: false } },
}

Vous pouvez également omettre diagnostics-otel de plugins.allow, ou exécuter openclaw plugins disable diagnostics-otel.

Connexe

Journalisation - journaux de fichiers, sortie console, suivi CLI et l'onglet Journaux de l'interface utilisateur de contrôle
Internes de journalisation du Gateway - styles de journaux WS, préfixes de sous-systèmes et capture de console
Drapeaux de diagnostic - drapeaux de journaux de débogage ciblés
Export de diagnostic - outil de bundle de support opérateur (distinct de l'export OTEL)
Référence de configuration - référence complète des champs diagnostics.*

# Fonctionnement général

# Démarrage rapide

# Signaux exportés

# Référence de configuration

# Variables d’environnement

# Confidentialité et capture de contenu

# Échantillonnage et vidage

# Métriques exportées

# Utilisation du modèle

# Flux de messages

# Talk

# Files d’attente et sessions

# Télémétrie de disponibilité des sessions

# Cycle de vie du harnais

# Exécution

# Internes de diagnostic (mémoire et boucle d'outils)

# Spans exportés

# Catalogue des événements de diagnostic

# Sans exportateur

# Désactiver

# Connexe

Fonctionnement général

Démarrage rapide

Signaux exportés

Référence de configuration

Variables d’environnement

Confidentialité et capture de contenu

Échantillonnage et vidage

Métriques exportées

Utilisation du modèle

Flux de messages

Talk

Files d’attente et sessions

Télémétrie de disponibilité des sessions

Cycle de vie du harnais

Exécution

Internes de diagnostic (mémoire et boucle d'outils)

Spans exportés

Catalogue des événements de diagnostic

Sans exportateur

Désactiver

Connexe