feat: improve logs output and docs

2026-01-09 02:51:11 +01:00
parent e1789ba9e5
commit efa5f0bfe0
7 changed files with 368 additions and 70 deletions
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -0,0 +1,144 @@
+---
+summary: "Logging overview: file logs, console output, CLI tailing, and the Control UI"
+read_when:
+  - You need a beginner-friendly overview of logging
+  - You want to configure log levels or formats
+  - You are troubleshooting and need to find logs quickly
+---
+
+# Logging
+
+Clawdbot logs in two places:
+
+- **File logs** (JSON lines) written by the Gateway.
+- **Console output** shown in terminals and the Control UI.
+
+This page explains where logs live, how to read them, and how to configure log
+levels and formats.
+
+## Where logs live
+
+By default, the Gateway writes a rolling log file under:
+
+`/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
+
+You can override this in `~/.clawdbot/clawdbot.json`:
+
+```json
+{
+  "logging": {
+    "file": "/path/to/clawdbot.log"
+  }
+}
+```
+
+## How to read logs
+
+### CLI: live tail (recommended)
+
+Use the CLI to tail the gateway log file via RPC:
+
+```bash
+clawdbot logs --follow
+```
+
+Output modes:
+
+- **TTY sessions**: pretty, colorized, structured log lines.
+- **Non-TTY sessions**: plain text.
+- `--json`: line-delimited JSON (one log event per line).
+- `--plain`: force plain text in TTY sessions.
+- `--no-color`: disable ANSI colors.
+
+In JSON mode, the CLI emits `type`-tagged objects:
+
+- `meta`: stream metadata (file, cursor, size)
+- `log`: parsed log entry
+- `notice`: truncation / rotation hints
+- `raw`: unparsed log line
+
+If the Gateway is unreachable, the CLI prints a short hint to run:
+
+```bash
+clawdbot doctor
+```
+
+### Control UI (web)
+
+The Control UI’s **Logs** tab tails the same file using `logs.tail`.
+See [/web/control-ui](/web/control-ui) for how to open it.
+
+### Provider-only logs
+
+To filter provider activity (WhatsApp/Telegram/etc), use:
+
+```bash
+clawdbot providers logs --provider whatsapp
+```
+
+## Log formats
+
+### File logs (JSONL)
+
+Each line in the log file is a JSON object. The CLI and Control UI parse these
+entries to render structured output (time, level, subsystem, message).
+
+### Console output
+
+Console logs are **TTY-aware** and formatted for readability:
+
+- Subsystem prefixes (e.g. `gateway/providers/whatsapp`)
+- Level coloring (info/warn/error)
+- Optional compact or JSON mode
+
+Console formatting is controlled by `logging.consoleStyle`.
+
+## Configuring logging
+
+All logging configuration lives under `logging` in `~/.clawdbot/clawdbot.json`.
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "file": "/tmp/clawdbot/clawdbot-YYYY-MM-DD.log",
+    "consoleLevel": "info",
+    "consoleStyle": "pretty",
+    "redactSensitive": "tools",
+    "redactPatterns": [
+      "sk-.*"
+    ]
+  }
+}
+```
+
+### Log levels
+
+- `logging.level`: **file logs** (JSONL) level.
+- `logging.consoleLevel`: **console** verbosity level.
+
+`--verbose` only affects console output; it does not change file log levels.
+
+### Console styles
+
+`logging.consoleStyle`:
+
+- `pretty`: human-friendly, colored, with timestamps.
+- `compact`: tighter output (best for long sessions).
+- `json`: JSON per line (for log processors).
+
+### Redaction
+
+Tool summaries can redact sensitive tokens before they hit the console:
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: list of regex strings to override the default set
+
+Redaction affects **console output only** and does not alter file logs.
+
+## Troubleshooting tips
+
+- **Gateway not reachable?** Run `clawdbot doctor` first.
+- **Logs empty?** Check that the Gateway is running and writing to the file path
+  in `logging.file`.
+- **Need more detail?** Set `logging.level` to `debug` or `trace` and retry.