49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
|
# 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.
|