mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 22:50:42 +00:00
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.
120 lines
4.2 KiB
Markdown
120 lines
4.2 KiB
Markdown
---
|
|
summary: "Logging surfaces, file logs, WS log styles, and console formatting"
|
|
read_when:
|
|
- Changing logging output or formats
|
|
- Debugging CLI or gateway output
|
|
title: "Gateway logging"
|
|
---
|
|
|
|
# Logging
|
|
|
|
For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
|
|
|
|
OpenClaw has two log “surfaces”:
|
|
|
|
- **Console output** (what you see in the terminal / Debug UI).
|
|
- **File logs** (JSON lines) written by the gateway logger.
|
|
|
|
## File-based logger
|
|
|
|
- Default rolling log file is under `/tmp/openclaw/` (one file per day): `openclaw-YYYY-MM-DD.log`
|
|
- Date uses the gateway host's local timezone.
|
|
- The log file path and level can be configured via `~/.openclaw/openclaw.json`:
|
|
- `logging.file`
|
|
- `logging.level`
|
|
|
|
The file format is one JSON object per line.
|
|
|
|
The Control UI Logs tab tails this file via the gateway (`logs.tail`).
|
|
CLI can do the same:
|
|
|
|
```bash
|
|
openclaw logs --follow
|
|
```
|
|
|
|
**Verbose vs. log levels**
|
|
|
|
- **File logs** are controlled exclusively by `logging.level`.
|
|
- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
|
|
raise the file log level.
|
|
- To capture verbose-only details in file logs, set `logging.level` to `debug` or
|
|
`trace`.
|
|
|
|
## Console capture
|
|
|
|
The CLI captures `console.log/info/warn/error/debug/trace` and writes them to file logs,
|
|
while still printing to stdout/stderr.
|
|
|
|
You can tune console verbosity independently via:
|
|
|
|
- `logging.consoleLevel` (default `info`)
|
|
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
|
|
|
|
## Tool summary redaction
|
|
|
|
Verbose tool summaries (e.g. `🛠️ Exec: ...`) can mask sensitive tokens before they hit the
|
|
console stream. This is **tools-only** and does not alter file logs.
|
|
|
|
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
|
|
- `logging.redactPatterns`: array of regex strings (overrides defaults)
|
|
- Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
|
|
- Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
|
|
- Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes.
|
|
|
|
## Gateway WebSocket logs
|
|
|
|
The gateway prints WebSocket protocol logs in two modes:
|
|
|
|
- **Normal mode (no `--verbose`)**: only “interesting” RPC results are printed:
|
|
- errors (`ok=false`)
|
|
- slow calls (default threshold: `>= 50ms`)
|
|
- parse errors
|
|
- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
|
|
|
|
### WS log style
|
|
|
|
`openclaw gateway` supports a per-gateway style switch:
|
|
|
|
- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
|
|
- `--ws-log compact`: compact output (paired request/response) when verbose
|
|
- `--ws-log full`: full per-frame output when verbose
|
|
- `--compact`: alias for `--ws-log compact`
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# optimized (only errors/slow)
|
|
openclaw gateway
|
|
|
|
# show all WS traffic (paired)
|
|
openclaw gateway --verbose --ws-log compact
|
|
|
|
# show all WS traffic (full meta)
|
|
openclaw gateway --verbose --ws-log full
|
|
```
|
|
|
|
## Console formatting (subsystem logging)
|
|
|
|
The console formatter is **TTY-aware** and prints consistent, prefixed lines.
|
|
Subsystem loggers keep output grouped and scannable.
|
|
|
|
Behavior:
|
|
|
|
- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
|
|
- **Subsystem colors** (stable per subsystem) plus level coloring
|
|
- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
|
|
- **Shortened subsystem prefixes**: drops leading `gateway/` + `channels/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
|
|
- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
|
|
- **`logRaw()`** for QR/UX output (no prefix, no formatting)
|
|
- **Console styles** (e.g. `pretty | compact | json`)
|
|
- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
|
|
- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
|
|
|
|
This keeps existing file logs stable while making interactive output scannable.
|
|
|
|
## Related
|
|
|
|
- [Logging](/logging)
|
|
- [OpenTelemetry export](/gateway/opentelemetry)
|
|
- [Diagnostics export](/gateway/diagnostics)
|