English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

OpenTelemetry-export

OpenClaw exporteert diagnostiek via de officiële diagnostics-otel plugin met OTLP/HTTP (protobuf). Elke collector of backend die OTLP/HTTP accepteert, werkt zonder codewijzigingen. Zie Logging voor lokale bestandslogs en hoe je ze leest.

Hoe het samenhangt

  • Diagnostiek-events zijn gestructureerde records binnen het proces die worden uitgezonden door de Gateway en gebundelde plugins voor modelruns, berichtstroom, sessies, wachtrijen en exec.
  • De diagnostics-otel plugin abonneert zich op die events en exporteert ze als OpenTelemetry metrics, traces en logs via OTLP/HTTP.
  • Providercalls ontvangen een W3C traceparent-header van OpenClaw's vertrouwde spancontext voor modelcalls wanneer het providertransport aangepaste headers accepteert. Door plugins uitgezonden tracecontext wordt niet doorgegeven.
  • Exporters worden alleen gekoppeld wanneer zowel het diagnostiekoppervlak als de plugin zijn ingeschakeld, zodat de kosten binnen het proces standaard bijna nul blijven.

Snel starten

Installeer bij pakketinstallaties eerst de 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,
    },
  },
}

Je kunt de plugin ook inschakelen via de CLI:

openclaw plugins enable diagnostics-otel

Geëxporteerde signalen

Signaal Wat erin terechtkomt
Metrics Counters en histogrammen voor tokengebruik, kosten, run-duur, berichtstroom, Talk-events, wachtrijlanes, sessiestatus/-herstel, exec en geheugendruk.
Traces Spans voor modelgebruik, modelcalls, harness-lifecycle, tooluitvoering, exec, webhook-/berichtverwerking, contextopbouw en toollussen.
Logs Gestructureerde logging.file-records die via OTLP worden geëxporteerd wanneer diagnostics.otel.logs is ingeschakeld.

Schakel traces, metrics en logs onafhankelijk van elkaar in of uit. Alle drie staan standaard aan wanneer diagnostics.otel.enabled true is.

Configuratiereferentie

{
  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,
      },
    },
  },
}

Omgevingsvariabelen

Variabele Doel
OTEL_EXPORTER_OTLP_ENDPOINT Overschrijft diagnostics.otel.endpoint. Als de waarde al /v1/traces, /v1/metrics of /v1/logs bevat, wordt deze ongewijzigd gebruikt.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Signaalspecifieke endpoint-overschrijvingen die worden gebruikt wanneer de bijbehorende configuratiesleutel diagnostics.otel.*Endpoint niet is ingesteld. Signaalspecifieke configuratie wint van signaalspecifieke env, die wint van het gedeelde endpoint.
OTEL_SERVICE_NAME Overschrijft diagnostics.otel.serviceName.
OTEL_EXPORTER_OTLP_PROTOCOL Overschrijft het wire-protocol (vandaag wordt alleen http/protobuf gehonoreerd).
OTEL_SEMCONV_STABILITY_OPT_IN Stel in op gen_ai_latest_experimental om het nieuwste experimentele GenAI-spanattribuut (gen_ai.provider.name) uit te zenden in plaats van de verouderde gen_ai.system. GenAI-metrics gebruiken altijd begrensde semantische attributen met lage cardinaliteit.
OPENCLAW_OTEL_PRELOADED Stel in op 1 wanneer een andere preload of hostproces de globale OpenTelemetry SDK al heeft geregistreerd. De plugin slaat dan zijn eigen NodeSDK-lifecycle over, maar koppelt nog steeds diagnostieklisteners en respecteert traces/metrics/logs.

Privacy en contentopname

Ruwe model-/toolcontent wordt standaard niet geëxporteerd. Spans bevatten begrensde identifiers (kanaal, provider, model, foutcategorie, request-id's met alleen hash) en bevatten nooit prompttekst, antwoordtekst, toolinputs, tooloutputs of sessiesleutels. Talk-metrics exporteren alleen begrensde eventmetadata zoals modus, transport, provider en eventtype. Ze bevatten geen transcripties, audiopayloads, sessie-id's, turn-id's, call-id's, room-id's of handoff-tokens.

Uitgaande modelrequests kunnen een W3C traceparent-header bevatten. Die header wordt alleen gegenereerd uit door OpenClaw beheerde diagnostische tracecontext voor de actieve modelcall. Bestaande door de caller aangeleverde traceparent-headers worden vervangen, zodat plugins of aangepaste provideropties geen cross-service trace-afkomst kunnen spoofen.

Stel diagnostics.otel.captureContent.* alleen in op true wanneer je collector en retentiebeleid zijn goedgekeurd voor prompt-, antwoord-, tool- of system-prompttekst. Elke subsleutel is afzonderlijk opt-in:

  • inputMessages - inhoud van gebruikersprompt.
  • outputMessages - inhoud van modelantwoord.
  • toolInputs - payloads met toolargumenten.
  • toolOutputs - payloads met toolresultaten.
  • systemPrompt - samengestelde system-/developerprompt.

Wanneer een subsleutel is ingeschakeld, krijgen model- en toolspans alleen voor die klasse begrensde, geredigeerde openclaw.content.*-attributen.

Sampling en flushen

  • Traces: diagnostics.otel.sampleRate (alleen root-span, 0.0 laat alles vallen, 1.0 behoudt alles).
  • Metrics: diagnostics.otel.flushIntervalMs (minimum 1000).
  • Logs: OTLP-logs respecteren logging.level (bestandslogniveau). Ze gebruiken het redactiepad voor diagnostische logrecords, niet consoleformattering. Installaties met hoog volume moeten OTLP-collector-sampling/filtering verkiezen boven lokale sampling.
  • Correlatie met bestandslogs: JSONL-bestandslogs bevatten top-level traceId, spanId, parentSpanId en traceFlags wanneer de logcall een geldige diagnostische tracecontext bevat, waardoor logprocessors lokale logregels kunnen koppelen aan geëxporteerde spans.
  • Requestcorrelatie: Gateway-HTTP-requests en WebSocket-frames maken een interne request-tracescope aan. Logs en diagnostiek-events binnen die scope erven standaard de requesttrace, terwijl agent-run- en modelcall-spans worden aangemaakt als children zodat provider-traceparent-headers op dezelfde trace blijven.

Geëxporteerde metrics

Modelgebruik

  • openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
  • openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
  • gen_ai.client.token.usage (histogram, GenAI-semantic-conventions-metric, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
  • gen_ai.client.operation.duration (histogram, seconden, GenAI-semantic-conventions-metric, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, optioneel error.type)
  • openclaw.model_call.duration_ms (histogram, attrs: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, plus openclaw.errorCategory en openclaw.failureKind bij geclassificeerde fouten)
  • openclaw.model_call.request_bytes (histogram, UTF-8-bytegrootte van de uiteindelijke payload voor het modelrequest; geen ruwe payloadcontent)
  • openclaw.model_call.response_bytes (histogram, UTF-8-bytegrootte van gestreamde modelresponse-events; geen ruwe responsecontent)
  • openclaw.model_call.time_to_first_byte_ms (histogram, verstreken tijd vóór het eerste gestreamde response-event)

Berichtstroom

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

Talk

  • openclaw.talk.event (counter, attrs: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
  • openclaw.talk.event.duration_ms (histogram, attrs: hetzelfde als openclaw.talk.event; uitgezonden wanneer een Talk-event duur rapporteert)
  • openclaw.talk.audio.bytes (histogram, attrs: hetzelfde als openclaw.talk.event; uitgezonden voor Talk-audioframe-events die bytelengte rapporteren)

Wachtrijen en sessies

  • openclaw.queue.lane.enqueue (teller, attributen: openclaw.lane)
  • openclaw.queue.lane.dequeue (teller, attributen: openclaw.lane)
  • openclaw.queue.depth (histogram, attributen: openclaw.lane of openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (histogram, attributen: openclaw.lane)
  • openclaw.session.state (teller, attributen: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (teller, attributen: openclaw.state; alleen uitgezonden voor verouderde sessieboekhouding zonder actief werk)
  • openclaw.session.stuck_age_ms (histogram, attributen: openclaw.state; alleen uitgezonden voor verouderde sessieboekhouding zonder actief werk)
  • openclaw.session.recovery.requested (teller, attributen: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.completed (teller, attributen: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.age_ms (histogram, attributen: hetzelfde als de bijbehorende herstelteller)
  • openclaw.run.attempt (teller, attributen: openclaw.attempt)

Telemetrie voor sessie-levendheid

diagnostics.stuckSessionWarnMs is de leeftijdsdrempel zonder voortgang voor sessie-levendheidsdiagnostiek. Een processing-sessie veroudert niet richting deze drempel zolang OpenClaw voortgang observeert in antwoorden, tools, status, blokken of de ACP-runtime. Typing-keepalives tellen niet als voortgang, zodat een stil model of harnas nog steeds kan worden gedetecteerd.

OpenClaw classificeert sessies op basis van het werk dat het nog kan observeren:

  • session.long_running: actief ingebed werk, modelaanroepen of toolaanroepen maken nog steeds voortgang.
  • session.stalled: actief werk bestaat, maar de actieve run heeft geen recente voortgang gerapporteerd. Vastgelopen ingebedde runs blijven eerst alleen-observeren en gaan daarna na diagnostics.stuckSessionAbortMs zonder voortgang naar abort-drain, zodat wachtrijbeurten achter de lane kunnen worden hervat. Wanneer niet ingesteld, gebruikt de afbreekdrempel standaard het veiligere uitgebreide venster van minstens 10 minuten en 5x diagnostics.stuckSessionWarnMs.
  • session.stuck: verouderde sessieboekhouding zonder actief werk. Dit geeft de betrokken sessie-lane onmiddellijk vrij.

Herstel zendt gestructureerde session.recovery.requested- en session.recovery.completed-gebeurtenissen uit. De diagnostische sessiestatus wordt pas als inactief gemarkeerd na een muterende hersteluitkomst (aborted of released) en alleen als dezelfde verwerkingsgeneratie nog steeds actueel is.

Alleen session.stuck zendt de teller openclaw.session.stuck, het histogram openclaw.session.stuck_age_ms en de span openclaw.session.stuck uit. Herhaalde session.stuck-diagnostiek gebruikt back-off zolang de sessie ongewijzigd blijft, dus dashboards moeten waarschuwen op aanhoudende stijgingen in plaats van op elke heartbeat-tick. Zie voor de configuratieknop en standaardwaarden de Configuratiereferentie.

Levenscyclus van het harnas

  • openclaw.harness.duration_ms (histogram, attributen: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase bij fouten)

Exec

  • openclaw.exec.duration_ms (histogram, attributen: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

Interne diagnostiek (geheugen en tool-lus)

  • openclaw.memory.heap_used_bytes (histogram, attributen: openclaw.memory.kind)
  • openclaw.memory.rss_bytes (histogram)
  • openclaw.memory.pressure (teller, attributen: openclaw.memory.level)
  • openclaw.tool.loop.iterations (teller, attributen: openclaw.toolName, openclaw.outcome)
  • openclaw.tool.loop.duration_ms (histogram, attributen: openclaw.toolName, openclaw.outcome)

Geëxporteerde spans

  • openclaw.model.usage
    • openclaw.channel, openclaw.provider, openclaw.model
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
    • standaard gen_ai.system, of gen_ai.provider.name wanneer de nieuwste semantische GenAI-conventies zijn ingeschakeld
    • 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
    • standaard gen_ai.system, of gen_ai.provider.name wanneer de nieuwste semantische GenAI-conventies zijn ingeschakeld
    • gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
    • openclaw.errorCategory en optioneel openclaw.failureKind bij fouten
    • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
    • openclaw.provider.request_id_hash (begrensde op SHA gebaseerde hash van de request-id van de upstream-provider; ruwe id's worden niet geëxporteerd)
  • openclaw.harness.run
    • openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
    • Bij voltooiing: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
    • Bij fout: openclaw.harness.phase, openclaw.errorCategory, optioneel openclaw.harness.cleanup_failed
  • 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 (geen prompt-, geschiedenis-, antwoord- of sessiesleutelinhoud)
  • openclaw.tool.loop
    • openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (geen lusberichten, params of tooluitvoer)
  • openclaw.memory.pressure
    • openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Wanneer inhoudsvastlegging expliciet is ingeschakeld, kunnen model- en tool-spans ook begrensde, geredigeerde openclaw.content.*-attributen bevatten voor de specifieke inhoudsklassen waarvoor je hebt gekozen.

Catalogus van diagnostische gebeurtenissen

De onderstaande gebeurtenissen ondersteunen de metrics en spans hierboven. Plugins kunnen zich er ook rechtstreeks op abonneren zonder OTLP-export.

Modelgebruik

  • model.usage - tokens, kosten, duur, context, provider/model/kanaal, sessie-id's. usage is provider-/turn-boekhouding voor kosten en telemetrie; context.used is de huidige prompt-/contextsnapshot en kan lager zijn dan provider usage.total wanneer gecachte input of tool-lusaanroepen betrokken zijn.

Berichtenstroom

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

Wachtrij en sessie

  • queue.lane.enqueue / queue.lane.dequeue
  • session.state / session.long_running / session.stalled / session.stuck
  • run.attempt / run.progress
  • diagnostic.heartbeat (geaggregeerde tellers: webhooks/wachtrij/sessie)

Levenscyclus van het harnas

  • harness.run.started / harness.run.completed / harness.run.error - levenscyclus per run voor het agentharnas. Bevat harnessId, optioneel pluginId, provider/model/kanaal en run-id. Voltooiing voegt durationMs, outcome, optioneel resultClassification, yieldDetected en itemLifecycle-aantallen toe. Fouten voegen phase (prepare/start/send/resolve/cleanup), errorCategory en optioneel cleanupFailed toe.

Exec

  • exec.process.completed - terminale uitkomst, duur, doel, modus, exitcode en foutsoort. Commandotekst en werkmappen worden niet opgenomen.

Zonder exporter

Je kunt diagnostische gebeurtenissen beschikbaar houden voor Plugins of aangepaste sinks zonder diagnostics-otel uit te voeren:

{
  diagnostics: { enabled: true },
}

Gebruik diagnostische flags voor gerichte debuguitvoer zonder logging.level te verhogen. Flags zijn hoofdletterongevoelig en ondersteunen jokertekens (bijv. telegram.* of *):

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

Of als een eenmalige env-override:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

Flaguitvoer gaat naar het standaardlogbestand (logging.file) en wordt nog steeds geredigeerd door logging.redactSensitive. Volledige handleiding: Diagnostische flags.

Uitschakelen

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

Je kunt diagnostics-otel ook buiten plugins.allow laten, of openclaw plugins disable diagnostics-otel uitvoeren.

Gerelateerd