logging

Add @side-quest/core as a dependency, create a logger module calling createPluginLogger with your plugin name and subsystems, then call initLogger at entry points. Export subsystem loggers and use template literal syntax like logger.info`message ${cid}`.

Generate a correlation ID with createCorrelationId at the start of each operation, then pass it through every function call and include it in all log messages. This lets you filter logs by ID to reconstruct a complete operation trace.

Logs are written to ~/.<plugin-name>/logs/<plugin-name>.jsonl in JSON Lines format. Files rotate automatically at 1 MiB by default, keeping up to 5 rotated files, both configurable in createPluginLogger options.

Use jq to filter the JSONL log file, for example jq 'select(.level == "error")' for errors or jq 'select(.category[1] == "scraper")' for a subsystem. Use grep with a correlation ID to trace a single operation.

Logs are not created when initLogger() is not called before any logging calls, or when async operations are not awaited. Verify initLogger runs at the start of CLI tools and MCP server startup.

Set lowestLevel to "info" in the createPluginLogger configuration to skip debug logs in production. You can also reduce maxFiles or maxSize if disk usage from rotated logs becomes a concern.