From fc0e6e4650b57119a32a611b01340d690c353e79 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 26 Apr 2026 14:51:47 -0700 Subject: [PATCH] docs(logging): document structured file fields --- CHANGELOG.md | 1 + docs/logging.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c852645601..d8d9efbfeea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ Docs: https://docs.openclaw.ai ### Fixes - Exec approvals: accept a symlinked `OPENCLAW_HOME` as the trusted approvals root while still rejecting symlinked `.openclaw` path components below it. (#64663) Thanks @FunJim. +- Logging: add top-level `hostname`, flattened `message`, and available `agent_id`, `session_id`, and `channel` fields to file-log JSONL records for multi-agent filtering without removing existing structured log arguments. Fixes #51075. Thanks @stevengonsalvez. - ACP: route server logs to stderr before Gateway config/bootstrap work so ACP stdout remains JSON-RPC only for IDE integrations. Fixes #49060. Thanks @Hollychou924. - Logging: propagate internal request trace scopes through Gateway HTTP requests and WebSocket frames so file logs, diagnostic events, agent run traces, model-call traces, OTEL spans, and trusted provider `traceparent` headers share a correlatable `traceId` without logging raw request or model content. Fixes #40353. Thanks @liangruochong44-ui. - Diagnostics/OTEL: capture privacy-safe model-call request payload bytes, streamed response bytes, first-response latency, and total duration in diagnostic events, plugin hooks, stability snapshots, and OTEL model-call spans/metrics without logging raw model content. Fixes #33832. Thanks @wwh830. diff --git a/docs/logging.md b/docs/logging.md index 6941aaf0781..68f44e3d8e7 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -103,6 +103,18 @@ openclaw channels logs --channel whatsapp 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). +File-log JSONL records also include machine-filterable top-level fields when +available: + +- `hostname`: gateway host name. +- `message`: flattened log message text for full-text search. +- `agent_id`: active agent id when the log call carries agent context. +- `session_id`: active session id/key when the log call carries session context. +- `channel`: active channel when the log call carries channel context. + +OpenClaw preserves the original structured log arguments alongside these fields +so existing parsers that read numbered tslog argument keys keep working. + ### Console output Console logs are **TTY-aware** and formatted for readability: