observability

Use createPluginLogger from @side-quest/core/logging with a plugin name and subsystem list, then call initLogger before any logging. It configures LogTape with JSONL output, file rotation, and hierarchical categories automatically.

Create a sessionCid at the top-level operation, generate a unique cid per operation, and pass parentCid to child operations. Include all three IDs in structured log properties so you can grep the full trace later.

Use DEBUG for detailed diagnostics like retries and loops, INFO for milestones and summaries, WARN for degraded operation or fallbacks, and ERROR for failures and exceptions. This keeps log volume manageable while preserving diagnostic value.

Filter logs with jq select expressions on properties, such as jq 'select(.properties.durationMs > 1000)' for slow operations. Combine grep for correlation IDs with jq for timeline views and error grouping.

Logs will not appear until initLogger is called, so verify it runs at startup. Also check that lowestLevel is not filtering out your messages, confirm the log directory is writable, and inspect the file directly with tail.

No, tests should assert functional behavior rather than log output because LogTape logging is asynchronous and log assertions are fragile. Only test logging infrastructure itself, such as MetricsCollector aggregation logic.