git:20260311.02fbfa4 to git:20260713.a7b0546

- # Logging System — Implementation Details

-

- For log locations and CLI commands, see project `CLAUDE.md`.

-

- ## Using Loggers in Code

-

- ```typescript

- import { log } from '../logging/index.js';

-

- // Use pre-created loggers

- log.bus.info('event emitted', { name: 'task:created', traceId: 'abc123' });

- log.agent.error('tool failed', { toolName: 'search', error: err.message });

-

- // Create child loggers for sub-modules

- const loopLog = log.agent.child('loop');

- loopLog.info('round 3/10'); // → tag: agent/loop

- ```

-

- Call `initLogging()` once at startup (creates the log directory, prunes old files). After that, use `log.<subsystem>` anywhere.

-

- ## Log Levels

-

- | Level | Label | Color | Severity |

- |---|---|---|---|

- | `trace` | TRC | gray | 0 (lowest) |

- | `debug` | DBG | cyan | 1 |

- | `info` | INF | green | 2 |

- | `warn` | WRN | yellow | 3 |

- | `error` | ERR | red | 4 |

- | `fatal` | FTL | bg-red | 5 (highest) |

-

- ## Redaction

-

- All log lines pass through `redactSensitiveText()` before being written to the file. The following patterns are automatically replaced with `[REDACTED]`:

-

- - **API keys**: OpenAI / Anthropic `sk-...` keys

- - **AWS credentials**: `AKIA...` access key IDs, `aws_secret_access_key`, `aws_session_token`

- - **Bearer tokens**: `Authorization: Bearer <token>`

- - **PEM blocks**: `-----BEGIN ... PRIVATE KEY-----` through `-----END ... PRIVATE KEY-----`

- - **Generic secrets**: Values after `password=`, `secret=`, `token=`, `api_key=`, `apikey=`

-

- ## Browser Console Log Persistence

-

- Browser-side `console.log/info/warn/error` are intercepted and persisted to the same log file with `subsystem: 'browser'`. This is critical for debugging frontend issues — browser console is lost on refresh, but these logs survive.

-

- ### How to investigate frontend issues

-

- ```bash

- # View all browser logs

- walnut logs -s browser

-

- # Follow browser logs in real-time

- walnut logs -f -s browser

-

- # Filter browser errors only

- walnut logs -s browser --json | jq 'select(.level == "error")'

-

- # Search for a specific error

- walnut logs -s browser --json | jq 'select(.message | contains("TypeError"))'

- ```

-

- ### Architecture

-

- ```

- Browser console.log() → monkey-patch (preserves DevTools output)

- → Ring buffer (max 200 entries, dedup consecutive identical messages)

- → Flush every 2s or when 50 entries buffered

- → WebSocket RPC 'browser:logs' { entries[] }

- → On page unload: sendBeacon POST /api/browser-logs (fallback)

- → Backend: writeLogEntry({ subsystem: 'browser', ... })

- → /tmp/walnut/walnut-YYYY-MM-DD.log (same file as server logs)

- ```

-

- ### Log entry format

-

- Each browser log entry in the JSON log file has:

- - `subsystem: "browser"` — filter key

- - `level` — mapped from browser: `log`→`info`, `warn`→`warn`, `error`→`error`

- - `browserLevel` — original browser level (e.g. `"log"` vs `"info"`)

- - `message` — first argument stringified (max 2000 chars)

- - `args` — remaining arguments (max 1000 chars, optional)

- - `url` — page pathname (optional)

- - `count` — dedup count when same message repeated consecutively (optional)

-

- ### Key files

-

- | File | Purpose |

- |------|---------|

- | `web/src/utils/browser-logger.ts` | Frontend interceptor: monkey-patch, ring buffer, WS send, sendBeacon fallback |

- | `src/web/routes/browser-logs.ts` | Backend: WS RPC handler + REST endpoint, rate limiting, writeLogEntry |

-

- ### Safety mechanisms

- - **No recursion**: `console.debug` is NOT intercepted (WS client uses debug for its own logging)

- - **Rate limiting**: 500 entries per 10s window per WS client (backend silently drops excess)

- - **Ring buffer**: Max 200 entries in memory — no unbounded growth when WS is disconnected

- - **Truncation**: message ≤ 2000 chars, args ≤ 1000 chars (both frontend and backend enforce)

- - **Serialization safety**: Handles circular refs, DOM nodes, Error objects, functions — all wrapped in try-catch

- ## File Structure

- ```

- src/logging/

- ├── levels.ts # Log level types and severity ordering

- ├── logger.ts # File transport (JSON lines, daily rolling, auto-prune after 3 days)

- ├── subsystem.ts # createSubsystemLogger() factory + colored stderr output

- ├── redact.ts # Sensitive data masking (runs before every file write)

- └── index.ts # Barrel: pre-created loggers (log.*) + initLogging()

- ```