Use this file to discover all available pages before exploring further.

OpenTelemetry export

OpenClaw exports diagnostics through the bundled

text

diagnostics-otel

plugin using OTLP/HTTP (protobuf). Any collector or backend that accepts OTLP/HTTP works without code changes. For local file logs and how to read them, see Logging.

How it fits together

Diagnostics events are structured, in-process records emitted by the Gateway and bundled plugins for model runs, message flow, sessions, queues, and exec.
text
diagnostics-otel
plugin subscribes to those events and exports them as OpenTelemetry metrics, traces, and logs over OTLP/HTTP.
Provider calls receive a W3C
text
traceparent
header from OpenClaw's trusted model-call span context when the provider transport accepts custom headers. Plugin-emitted trace context is not propagated.
Exporters only attach when both the diagnostics surface and the plugin are enabled, so the in-process cost stays near zero by default.

Quick start


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

You can also enable the plugin from the CLI:


bash
openclaw plugins enable diagnostics-otel

note

`protocol` currently supports `http/protobuf` only. `grpc` is ignored.

Signals exported

Signal	What goes in it
Metrics	Counters and histograms for token usage, cost, run duration, message flow, queue lanes, session state, exec, and memory pressure.
Traces	Spans for model usage, model calls, harness lifecycle, tool execution, exec, webhook/message processing, context assembly, and tool loops.
Logs	Structured text `logging.file` records exported over OTLP when text `diagnostics.otel.logs` is enabled.

Toggle

text

traces

text

metrics

, and

text

logs

independently. All three default to on when

text

diagnostics.otel.enabled

is true.

Configuration reference


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

Environment variables

Variable	Purpose
text `OTEL_EXPORTER_OTLP_ENDPOINT`	Override text `diagnostics.otel.endpoint` . If the value already contains text `/v1/traces` , text `/v1/metrics` , or text `/v1/logs` , it is used as-is.
text `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / text `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / text `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Signal-specific endpoint overrides used when the matching text `diagnostics.otel.*Endpoint` config key is unset. Signal-specific config wins over signal-specific env, which wins over the shared endpoint.
text `OTEL_SERVICE_NAME`	Override text `diagnostics.otel.serviceName` .
text `OTEL_EXPORTER_OTLP_PROTOCOL`	Override the wire protocol (only text `http/protobuf` is honored today).
text `OTEL_SEMCONV_STABILITY_OPT_IN`	Set to text `gen_ai_latest_experimental` to emit the latest experimental GenAI span attribute ( text `gen_ai.provider.name` ) instead of the legacy text `gen_ai.system` . GenAI metrics always use bounded, low-cardinality semantic attributes regardless.
text `OPENCLAW_OTEL_PRELOADED`	Set to text `1` when another preload or host process already registered the global OpenTelemetry SDK. The plugin then skips its own NodeSDK lifecycle but still wires diagnostic listeners and honors text `traces` / text `metrics` / text `logs` .

Privacy and content capture

Raw model/tool content is not exported by default. Spans carry bounded identifiers (channel, provider, model, error category, hash-only request ids) and never include prompt text, response text, tool inputs, tool outputs, or session keys.

Outbound model requests may include a W3C

text

traceparent

header. That header is generated only from OpenClaw-owned diagnostic trace context for the active model call. Existing caller-supplied

text

traceparent

headers are replaced, so plugins or custom provider options cannot spoof cross-service trace ancestry.

Set

text

diagnostics.otel.captureContent.*

text

true

only when your collector and retention policy are approved for prompt, response, tool, or system-prompt text. Each subkey is opt-in independently:

text
inputMessages
— user prompt content.
text
outputMessages
— model response content.
text
toolInputs
— tool argument payloads.
text
toolOutputs
— tool result payloads.
text
systemPrompt
— assembled system/developer prompt.

When any subkey is enabled, model and tool spans get bounded, redacted

text

openclaw.content.*

attributes for that class only.

Sampling and flushing

Traces:
text
diagnostics.otel.sampleRate
(root-span only,
text
0.0
drops all,
text
1.0
keeps all).
Metrics:
text
diagnostics.otel.flushIntervalMs
(minimum
text
1000
).
Logs: OTLP logs respect
text
logging.level
(file log level). They use the diagnostic log-record redaction path, not console formatting. High-volume installs should prefer OTLP collector sampling/filtering over local sampling.
File-log correlation: JSONL file logs include top-level
text
traceId
,
text
spanId
,
text
parentSpanId
, and
text
traceFlags
when the log call carries a valid diagnostic trace context, which lets log processors join local log lines with exported spans.
Request correlation: Gateway HTTP requests and WebSocket frames create an internal request trace scope. Logs and diagnostic events inside that scope inherit the request trace by default, while agent run and model-call spans are created as children so provider
text
traceparent
headers stay on the same trace.

Exported metrics

Model usage

text
openclaw.tokens
(counter, attrs:
text
openclaw.token
,
text
openclaw.channel
,
text
openclaw.provider
,
text
openclaw.model
,
text
openclaw.agent
)
text
openclaw.cost.usd
(counter, attrs:
text
openclaw.channel
,
text
openclaw.provider
,
text
openclaw.model
)
text
openclaw.run.duration_ms
(histogram, attrs:
text
openclaw.channel
,
text
openclaw.provider
,
text
openclaw.model
)
text
openclaw.context.tokens
(histogram, attrs:
text
openclaw.context
,
text
openclaw.channel
,
text
openclaw.provider
,
text
openclaw.model
)
text
gen_ai.client.token.usage
(histogram, GenAI semantic-conventions metric, attrs:
text
gen_ai.token.type
=
text
input
/
text
output
,
text
gen_ai.provider.name
,
text
gen_ai.operation.name
,
text
gen_ai.request.model
)
text
gen_ai.client.operation.duration
(histogram, seconds, GenAI semantic-conventions metric, attrs:
text
gen_ai.provider.name
,
text
gen_ai.operation.name
,
text
gen_ai.request.model
, optional
text
error.type
)
text
openclaw.model_call.duration_ms
(histogram, attrs:
text
openclaw.provider
,
text
openclaw.model
,
text
openclaw.api
,
text
openclaw.transport
, plus
text
openclaw.errorCategory
and
text
openclaw.failureKind
on classified errors)
text
openclaw.model_call.request_bytes
(histogram, UTF-8 byte size of the final model request payload; no raw payload content)
text
openclaw.model_call.response_bytes
(histogram, UTF-8 byte size of streamed model response events; no raw response content)
text
openclaw.model_call.time_to_first_byte_ms
(histogram, elapsed time before the first streamed response event)

Message flow

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

Queues and sessions

text
openclaw.queue.lane.enqueue
(counter, attrs:
text
openclaw.lane
)
text
openclaw.queue.lane.dequeue
(counter, attrs:
text
openclaw.lane
)
text
openclaw.queue.depth
(histogram, attrs:
text
openclaw.lane
or
text
openclaw.channel=heartbeat
)
text
openclaw.queue.wait_ms
(histogram, attrs:
text
openclaw.lane
)
text
openclaw.session.state
(counter, attrs:
text
openclaw.state
,
text
openclaw.reason
)
text
openclaw.session.stuck
(counter, attrs:
text
openclaw.state
)
text
openclaw.session.stuck_age_ms
(histogram, attrs:
text
openclaw.state
)
text
openclaw.run.attempt
(counter, attrs:
text
openclaw.attempt
)

Harness lifecycle

text
openclaw.harness.duration_ms
(histogram, attrs:
text
openclaw.harness.id
,
text
openclaw.harness.plugin
,
text
openclaw.outcome
,
text
openclaw.harness.phase
on errors)

Exec

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

Diagnostics internals (memory and tool loop)

text
openclaw.memory.heap_used_bytes
(histogram, attrs:
text
openclaw.memory.kind
)
text
openclaw.memory.rss_bytes
(histogram)
text
openclaw.memory.pressure
(counter, attrs:
text
openclaw.memory.level
)
text
openclaw.tool.loop.iterations
(counter, attrs:
text
openclaw.toolName
,
text
openclaw.outcome
)
text
openclaw.tool.loop.duration_ms
(histogram, attrs:
text
openclaw.toolName
,
text
openclaw.outcome
)

Exported spans

text
openclaw.model.usage
- text
  openclaw.channel
  ,
  text
  openclaw.provider
  ,
  text
  openclaw.model
- text
  openclaw.tokens.*
  (input/output/cache_read/cache_write/total)
- text
  gen_ai.system
  by default, or
  text
  gen_ai.provider.name
  when the latest GenAI semantic conventions are opted in
- text
  gen_ai.request.model
  ,
  text
  gen_ai.operation.name
  ,
  text
  gen_ai.usage.*
text
openclaw.run
- text
  openclaw.outcome
  ,
  text
  openclaw.channel
  ,
  text
  openclaw.provider
  ,
  text
  openclaw.model
  ,
  text
  openclaw.errorCategory
text
openclaw.model.call
- text
  gen_ai.system
  by default, or
  text
  gen_ai.provider.name
  when the latest GenAI semantic conventions are opted in
- text
  gen_ai.request.model
  ,
  text
  gen_ai.operation.name
  ,
  text
  openclaw.provider
  ,
  text
  openclaw.model
  ,
  text
  openclaw.api
  ,
  text
  openclaw.transport
- text
  openclaw.errorCategory
  and optional
  text
  openclaw.failureKind
  on errors
- text
  openclaw.model_call.request_bytes
  ,
  text
  openclaw.model_call.response_bytes
  ,
  text
  openclaw.model_call.time_to_first_byte_ms
- text
  openclaw.provider.request_id_hash
  (bounded SHA-based hash of the upstream provider request id; raw ids are not exported)
text
openclaw.harness.run
- text
  openclaw.harness.id
  ,
  text
  openclaw.harness.plugin
  ,
  text
  openclaw.outcome
  ,
  text
  openclaw.provider
  ,
  text
  openclaw.model
  ,
  text
  openclaw.channel
- On completion:
  text
  openclaw.harness.result_classification
  ,
  text
  openclaw.harness.yield_detected
  ,
  text
  openclaw.harness.items.started
  ,
  text
  openclaw.harness.items.completed
  ,
  text
  openclaw.harness.items.active
- On error:
  text
  openclaw.harness.phase
  ,
  text
  openclaw.errorCategory
  , optional
  text
  openclaw.harness.cleanup_failed
text
openclaw.tool.execution
- text
  gen_ai.tool.name
  ,
  text
  openclaw.toolName
  ,
  text
  openclaw.errorCategory
  ,
  text
  openclaw.tool.params.*
text
openclaw.exec
- text
  openclaw.exec.target
  ,
  text
  openclaw.exec.mode
  ,
  text
  openclaw.outcome
  ,
  text
  openclaw.failureKind
  ,
  text
  openclaw.exec.command_length
  ,
  text
  openclaw.exec.exit_code
  ,
  text
  openclaw.exec.timed_out
text
openclaw.webhook.processed
- text
  openclaw.channel
  ,
  text
  openclaw.webhook
  ,
  text
  openclaw.chatId
text
openclaw.webhook.error
- text
  openclaw.channel
  ,
  text
  openclaw.webhook
  ,
  text
  openclaw.chatId
  ,
  text
  openclaw.error
text
openclaw.message.processed
- text
  openclaw.channel
  ,
  text
  openclaw.outcome
  ,
  text
  openclaw.chatId
  ,
  text
  openclaw.messageId
  ,
  text
  openclaw.reason
text
openclaw.message.delivery
- text
  openclaw.channel
  ,
  text
  openclaw.delivery.kind
  ,
  text
  openclaw.outcome
  ,
  text
  openclaw.errorCategory
  ,
  text
  openclaw.delivery.result_count
text
openclaw.session.stuck
- text
  openclaw.state
  ,
  text
  openclaw.ageMs
  ,
  text
  openclaw.queueDepth
text
openclaw.context.assembled
- text
  openclaw.prompt.size
  ,
  text
  openclaw.history.size
  ,
  text
  openclaw.context.tokens
  ,
  text
  openclaw.errorCategory
  (no prompt, history, response, or session-key content)
text
openclaw.tool.loop
- text
  openclaw.toolName
  ,
  text
  openclaw.outcome
  ,
  text
  openclaw.iterations
  ,
  text
  openclaw.errorCategory
  (no loop messages, params, or tool output)
text
openclaw.memory.pressure
- text
  openclaw.memory.level
  ,
  text
  openclaw.memory.heap_used_bytes
  ,
  text
  openclaw.memory.rss_bytes

When content capture is explicitly enabled, model and tool spans can also include bounded, redacted

text

openclaw.content.*

attributes for the specific content classes you opted into.

Diagnostic event catalog

The events below back the metrics and spans above. Plugins can also subscribe to them directly without OTLP export.

Model usage

text
model.usage
— tokens, cost, duration, context, provider/model/channel, session ids.
text
usage
is provider/turn accounting for cost and telemetry;
text
context.used
is the current prompt/context snapshot and can be lower than provider
text
usage.total
when cached input or tool-loop calls are involved.

Message flow

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

Queue and session

text
queue.lane.enqueue
/
text
queue.lane.dequeue
text
session.state
/
text
session.stuck
text
run.attempt
text
diagnostic.heartbeat
(aggregate counters: webhooks/queue/session)

Harness lifecycle

text
harness.run.started
/
text
harness.run.completed
/
text
harness.run.error
— per-run lifecycle for the agent harness. Includes
text
harnessId
, optional
text
pluginId
, provider/model/channel, and run id. Completion adds
text
durationMs
,
text
outcome
, optional
text
resultClassification
,
text
yieldDetected
, and
text
itemLifecycle
counts. Errors add
text
phase
(
text
prepare
/
text
start
/
text
send
/
text
resolve
/
text
cleanup
),
text
errorCategory
, and optional
text
cleanupFailed
.

Exec

text
exec.process.completed
— terminal outcome, duration, target, mode, exit code, and failure kind. Command text and working directories are not included.

Without an exporter

You can keep diagnostics events available to plugins or custom sinks without running

text

diagnostics-otel


json5
{
  diagnostics: { enabled: true },
}

For targeted debug output without raising

text

logging.level

, use diagnostics flags. Flags are case-insensitive and support wildcards (e.g.

text

telegram.*

text

*


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

Or as a one-off env override:


bash
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

Flag output goes to the standard log file (

text

logging.file

) and is still redacted by

text

logging.redactSensitive

. Full guide: Diagnostics flags.

Disable


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

You can also leave

text

diagnostics-otel

out of

text

plugins.allow

, or run

text

openclaw plugins disable diagnostics-otel

Logging — file logs, console output, CLI tailing, and the Control UI Logs tab
Gateway logging internals — WS log styles, subsystem prefixes, and console capture
Diagnostics flags — targeted debug-log flags
Diagnostics export — operator support-bundle tool (separate from OTEL export)
Configuration reference — full
text
diagnostics.*
field reference

OpenClaw Docs

OpenTelemetry export

How it fits together

Quick start

note

Signals exported

Configuration reference

Environment variables

Privacy and content capture

Sampling and flushing

Exported metrics

Model usage

Message flow

Queues and sessions

Harness lifecycle

Exec

Diagnostics internals (memory and tool loop)

Exported spans

Diagnostic event catalog

Without an exporter

Disable

Related