How to Export OpenClaw OpenTelemetry to Grafana

OpenTelemetry is the better fit when you want traces and logs alongside metrics, or when your company already sends everything to Grafana, Datadog, Honeycomb, New Relic, Tempo, or an OTLP collector. OpenClaw supports this through the diagnostics-otel plugin, which subscribes to Gateway diagnostics and exports metrics, traces, and logs over OTLP/HTTP.

30-second answer

Install and enable clawhub:@openclaw/diagnostics-otel, set diagnostics.enabled and diagnostics.otel.enabled to true, point endpoint to your OTLP/HTTP collector, and keep content capture disabled unless your retention policy allows prompts, responses, tool inputs, or system prompts. The documented protocol is http/protobuf, with traces, metrics, and logs toggled independently.

When this pays off

Use OTLP when a single failed customer support reply needs a trace, not just a counter; when you want model-call latency next to tool execution spans; or when engineering already uses a collector pipeline. This is a buyer-intent feature because serious operators need proof, not vibes, before they let an AI gateway touch customer workflows.

Operator runbook

1. Install the plugin with openclaw plugins install clawhub:@openclaw/diagnostics-otel and enable it. Like Prometheus, the exporter only attaches when both the diagnostics surface and plugin are enabled. That keeps default overhead low but means config must be complete before you expect data.
2. Configure the OTLP endpoint. The docs show diagnostics.otel.endpoint such as http://otel-collector:4318 and protocol http/protobuf. You can also use tracesEndpoint, metricsEndpoint, and logsEndpoint separately. Environment overrides like OTEL_EXPORTER_OTLP_ENDPOINT are supported when config fields are unset.
3. Name the service clearly. Set diagnostics.otel.serviceName or OTEL_SERVICE_NAME to something like openclaw-gateway. If you run multiple Gateways, include environment or role in the service naming strategy so traces from a rescue bot do not mix with production customer support.
4. Keep content capture off by default. OpenClaw does not export raw prompts, responses, tool inputs, tool outputs, or system prompts unless diagnostics.otel.captureContent enables specific subkeys. Turn those on only after the collector, retention, and access controls are approved for that data class.
5. Tune sampling and flush behavior. diagnostics.otel.sampleRate controls root-span tracing, while flushIntervalMs controls metrics export interval. High-volume installs should prefer collector-side filtering and sampling instead of flooding every downstream tool with full-fidelity traces.
6. Use traces to debug revenue-critical paths. Follow a message from webhook receipt through queue, model call, tool execution, and delivery. When a buyer asks why the bot missed a lead or why support latency spiked, a trace gives you an answer faster than reading a wall of logs.

Verification

A clean verification path is: Gateway starts without exporter errors, the collector receives service openclaw-gateway, one test chat produces model and run spans, metrics show token and duration data, and logs correlate with traceId/spanId when file-log correlation is enabled. Then confirm no raw prompt text appears unless you intentionally enabled content capture.

Common mistakes

Do not set captureContent because traces look empty. The default privacy model is a feature. Also avoid assuming grpc works because your collector supports it; the OpenClaw docs say the plugin honors http/protobuf today. Finally, do not forget diagnostics.enabled, or the exporter can be configured but starved of events.

Turn it into a repeatable operating system

The Playbook turns traces into operating practice: which spans matter, which errors page a human, which model failures trigger fallback, and when observability data is too sensitive for a shared vendor account. OTLP gives you the data pipe; the Playbook gives you the judgment layer.

Before rollout

Before rollout, confirm the collector workspace is approved for the metadata you export. Even without prompt capture, traces reveal provider choices, channel flow, tool names, and timing. Give the dashboard a clear owner and keep production, staging, and rescue Gateways separated in service names. Add one sample trace to the runbook so future debugging starts from a known healthy shape.