---

summary: "Export OpenClaw diagnostics to any OpenTelemetry collector via the diagnostics-otel plugin (OTLP/HTTP)"

summary: "Export OpenClaw diagnostics to OpenTelemetry collectors or stdout JSONL via the diagnostics-otel plugin"

title: "OpenTelemetry export"

read_when:

- You want to send OpenClaw model usage, message flow, or session metrics to an OpenTelemetry collector

---

OpenClaw exports diagnostics through the official `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](/logging).

using **OTLP/HTTP (protobuf)**. Logs can also be written as stdout JSONL for

container and sandbox log pipelines. Any collector or backend that accepts

OTLP/HTTP works without code changes. For local file logs and how to read them,

see [Logging](/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.

- **`diagnostics-otel` plugin** subscribes to those events and exports them as

OpenTelemetry **metrics**, **traces**, and **logs** over OTLP/HTTP.

OpenTelemetry **metrics**, **traces**, and **logs** over OTLP/HTTP. It can

also mirror diagnostic log records to stdout JSONL.

- **Provider calls** receive a W3C `traceparent` header from OpenClaw's

trusted model-call span context when the provider transport accepts custom

headers. Plugin-emitted trace context is not propagated.

| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

| **Metrics** | Counters and histograms for token usage, cost, run duration, failover, skill usage, message flow, Talk events, queue lanes, session state/recovery, tool execution, oversized payloads, exec, and memory pressure. |

| **Traces** | Spans for model usage, model calls, harness lifecycle, skill usage, tool execution, exec, webhook/message processing, context assembly, and tool loops. |

| **Logs** | Structured `logging.file` records exported over OTLP when `diagnostics.otel.logs` is enabled; log bodies are withheld unless content capture is explicitly enabled. |

| **Logs** | Structured `logging.file` records exported over OTLP or stdout JSONL when `diagnostics.otel.logs` is enabled; log bodies are withheld unless content capture is explicitly enabled. |

Toggle `traces`, `metrics`, and `logs` independently. Traces and metrics

default to on when `diagnostics.otel.enabled` is true. Logs default to off and

are exported only when `diagnostics.otel.logs` is explicitly `true`.

are exported only when `diagnostics.otel.logs` is explicitly `true`. Log export

defaults to OTLP; set `diagnostics.otel.logsExporter` to `stdout` for JSONL on

stdout, or `both` to send each diagnostic log record to OTLP and stdout.

## Configuration reference

traces: true,

metrics: true,

logs: true,

logsExporter: "otlp", // otlp | stdout | both

sampleRate: 0.2, // root-span sampler, 0.0..1.0

flushIntervalMs: 60000, // metric export interval (min 1000ms)

captureContent: {

- **Logs:** OTLP logs respect `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.

Set `diagnostics.otel.logsExporter: "stdout"` when your platform already

ships stdout/stderr to a log processor and you do not have an OTLP logs

collector. Stdout records are one JSON object per line with `ts`, `signal`,

`service.name`, severity, body, redacted attributes, and trusted trace fields

when available.

- **File-log correlation:** JSONL file logs include top-level `traceId`,

`spanId`, `parentSpanId`, and `traceFlags` when the log call carries a valid

diagnostic trace context, which lets log processors join local log lines with