From 2194a8c64caa5bdbbe8347d9882ccf1a501a2b5c Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 26 Apr 2026 13:59:32 -0700 Subject: [PATCH] docs(logging): document request trace scopes --- CHANGELOG.md | 1 + docs/gateway/opentelemetry.md | 4 ++++ docs/logging.md | 7 +++++++ 3 files changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2243ebfd2eb..36215c8a7fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Fixes +- 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. - Logging: write validated diagnostic trace context as top-level `traceId`, `spanId`, `parentSpanId`, and `traceFlags` fields in file-log JSONL records so traced requests and model calls are easier to correlate in log processors. Refs #40353. Thanks @liangruochong44-ui. - Logging/sessions: apply configured redaction patterns to persisted session transcript text and accept escaped character classes in safe custom redaction regexes, so transcript JSONL no longer keeps matching sensitive text in the clear. Fixes #42982. Thanks @panpan0000. diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md index 5614f8e4c00..7e1fa390e0d 100644 --- a/docs/gateway/opentelemetry.md +++ b/docs/gateway/opentelemetry.md @@ -154,6 +154,10 @@ When any subkey is enabled, model and tool spans get bounded, redacted `spanId`, `parentSpanId`, and `traceFlags` when the log call carries a valid diagnostic trace context, which lets log processors join local log lines with exported spans. +- **Request correlation:** Gateway HTTP requests and WebSocket frames create an + internal request trace scope. Logs and diagnostic events inside that scope + inherit the request trace by default, while agent run and model-call spans are + created as children so provider `traceparent` headers stay on the same trace. ## Exported metrics diff --git a/docs/logging.md b/docs/logging.md index 9b09b55c8a8..6941aaf0781 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -164,6 +164,13 @@ OpenClaw writes the trace fields as top-level JSON keys (`traceId`, `spanId`, `parentSpanId`, `traceFlags`) so external log processors can correlate the line with OTEL spans and provider `traceparent` propagation. +Gateway HTTP requests and Gateway WebSocket frames establish an internal request +trace scope. Logs and diagnostic events emitted inside that async scope inherit +the request trace when they do not pass an explicit trace context. Agent run and +model-call traces become children of the active request trace, so local logs, +diagnostic snapshots, OTEL spans, and trusted provider `traceparent` headers can +be joined by `traceId` without logging raw request or model content. + ### Model call size and timing Model-call diagnostics record bounded request/response measurements without