7741dbb759
Logging.md had grown to 487 lines with ~300 lines dedicated to OpenTelemetry export — wire protocol, full metric/span catalog, env vars, captureContent shape, sampling, the diagnostic event catalog, and protocol notes — leaving the genuine logging overview buried behind exporter reference material. Move the OTEL surface to a dedicated page and slim logging.md to a focused logs overview: - Add docs/gateway/opentelemetry.md (OpenTelemetry export). Same content reorganized: how it fits together, quick start, signals, configuration reference + env vars table, privacy/captureContent, sampling/flushing, full metric and span catalog, diagnostic event catalog, no-exporter mode, diagnostics flags pointer, disable. - docs/logging.md: drop the OTEL section in favor of a short 'Diagnostics and OpenTelemetry' summary that cross-links the new page and the diagnostics-flags page. Drops 273 lines net. Also drops the redundant body H1, retitles to 'Logging' (was 'Logging overview' which mismatched sidebar usage), and refreshes the Related list. - docs/docs.json: insert gateway/opentelemetry into the 'Health and diagnostics' sidebar group, reorder pages so the user- facing health/run pages come before exporter/internals pages, and put logging next to opentelemetry where readers naturally associate them. - docs/gateway/diagnostics.md, docs/gateway/logging.md, docs/gateway/configuration-reference.md: cross-link the new page and sentence-case stale Title-Cased Related entries on diagnostics.md.
4.2 KiB
summary, title, read_when
| summary | title | read_when | |||
|---|---|---|---|---|---|
| Create shareable Gateway diagnostics bundles for bug reports | Diagnostics export |
|
OpenClaw can create a local diagnostics zip that is safe to attach to bug reports. It combines sanitized Gateway status, health, logs, config shape, and recent payload-free stability events.
Quick start
openclaw gateway diagnostics export
The command prints the written zip path. To choose a path:
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
For automation:
openclaw gateway diagnostics export --json
What the export contains
The zip includes:
summary.md: human-readable overview for support.diagnostics.json: machine-readable summary of config, logs, status, health, and stability data.manifest.json: export metadata and file list.- Sanitized config shape and non-secret config details.
- Sanitized log summaries and recent redacted log lines.
- Best-effort Gateway status and health snapshots.
stability/latest.json: newest persisted stability bundle, when available.
The export is useful even when the Gateway is unhealthy. If the Gateway cannot answer status or health requests, the local logs, config shape, and latest stability bundle are still collected when available.
Privacy model
Diagnostics are designed to be shareable. The export keeps operational data that helps debugging, such as:
- subsystem names, plugin ids, provider ids, channel ids, and configured modes
- status codes, durations, byte counts, queue state, and memory readings
- sanitized log metadata and redacted operational messages
- config shape and non-secret feature settings
The export omits or redacts:
- chat text, prompts, instructions, webhook bodies, and tool outputs
- credentials, API keys, tokens, cookies, and secret values
- raw request or response bodies
- account ids, message ids, raw session ids, hostnames, and local usernames
When a log message looks like user, chat, prompt, or tool payload text, the export keeps only that a message was omitted and the byte count.
Stability recorder
The Gateway records a bounded, payload-free stability stream by default when diagnostics are enabled. It is for operational facts, not content.
Inspect the live recorder:
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json
Inspect the newest persisted stability bundle after a fatal exit, shutdown timeout, or restart startup failure:
openclaw gateway stability --bundle latest
Create a diagnostics zip from the newest persisted bundle:
openclaw gateway stability --bundle latest --export
Persisted bundles live under ~/.openclaw/logs/stability/ when events exist.
Useful options
openclaw gateway diagnostics export \
--output openclaw-diagnostics.zip \
--log-lines 5000 \
--log-bytes 1000000
--output <path>: write to a specific zip path.--log-lines <count>: maximum sanitized log lines to include.--log-bytes <bytes>: maximum log bytes to inspect.--url <url>: Gateway WebSocket URL for status and health snapshots.--token <token>: Gateway token for status and health snapshots.--password <password>: Gateway password for status and health snapshots.--timeout <ms>: status and health snapshot timeout.--no-stability-bundle: skip persisted stability bundle lookup.--json: print machine-readable export metadata.
Disable diagnostics
Diagnostics are enabled by default. To disable the stability recorder and diagnostic event collection:
{
diagnostics: {
enabled: false,
},
}
Disabling diagnostics reduces bug-report detail. It does not affect normal Gateway logging.
Related
- Health checks
- Gateway CLI
- Gateway protocol
- Logging
- OpenTelemetry export — separate flow for streaming diagnostics to a collector