Logging Style Guide

This document defines a consistent logging style for all bot modules, covering levels silly, debug, info, warn, and error.

1. Message Structure

• Prepend a component tag in square brackets (e.g. [init], [cmd:exit], [module:responsesPrompt], [PB]). • Follow with a concise verb phrase. Capitalize the first letter. No trailing period. • Embed variable IDs or names in backticks.

Example:

[cmd:status] Generated status for client `IO3`
[PB] Missing record for clientId=`ASOP`, creating new one
[module:responses] Fetched 24 messages from channel `123456789012345678` in 120ms

2. Level Guidelines

error: Unrecoverable failures. Include operation, relevant IDs, and err.message.
warn: Recoverable issues or unexpected states (fallbacks, missing optional config).
info: High-level lifecycle events and successful actions (login, module load, command registration).
debug: Detailed internal state and computation values for troubleshooting.
silly: Very verbose, lowest priority; use sparingly for deep diagnostics.

3. Where to Log

In every catch block: use logger.error with context and message. Optional stack at debug.
On module initialization: logger.info “Module X loaded”.
When registering slash commands: logger.info for each command.
Before/after major API calls (PocketBase, OpenAI): logger.debug with parameters and durations.
On unexpected user input or missing resources: logger.warn.
On successful command execution: optional logger.info.
In background jobs (cron, cycles): logger.info at start/stop, logger.error on failure.

4. Examples

[init] Initializing responsesPrompt module for client `IO3`
[cmd:prompt] URL update requested; fetching https://example.com/prompt.txt
[PB] Upsert `responses_prompts` record id=`abc123` for clientId=`IO3`
[onMessage] Should respond? mention=false reply=true
[sendNarrative] Calling AI with model `gpt-4o-mini`, instructions length=512
Error: [sendNarrative] HTTP 502 Bad Gateway
[cron] Scheduled score decay: `0 0 * * 0`

5. Implementation Notes

Winston logger is configured to include timestamp, client ID, and level.
Always use logger.<level>(message) instead of console.log.
Reserve info for user-facing or operational milestones.
Use debug/silly for verbose, development-only details.
Update or remove non-conforming logs during code refactoring.

2.4 KiB Raw Blame History