47 lines
1.4 KiB
Markdown
47 lines
1.4 KiB
Markdown
# Cthulhu Logging Guidelines
|
|
|
|
This document defines the preferred format for debug logging in Cthulhu.
|
|
The goal is to keep logs consistent, searchable, and easy to scan.
|
|
|
|
## Helpers
|
|
|
|
Use the helpers in `cthulhu.debug` for new logs:
|
|
|
|
- `debug.print_log(level, prefix, message, reason=None, timestamp=False, stack=False)`
|
|
- `debug.print_log_tokens(level, prefix, tokens, reason=None, timestamp=False, stack=False)`
|
|
|
|
These helpers ensure the prefix and optional reason tag are formatted consistently.
|
|
Timestamps are appended at the end of the message when enabled.
|
|
|
|
## Prefixes
|
|
|
|
Use short, uppercase prefixes that identify the subsystem:
|
|
|
|
- `EVENT MANAGER`
|
|
- `FOCUS MANAGER`
|
|
- `INPUT EVENT`
|
|
- `SCRIPT MANAGER`
|
|
- `WEB`
|
|
|
|
## Messages
|
|
|
|
- Keep messages short and action-focused.
|
|
- Do not include the prefix in the message.
|
|
- Prefer consistent verbs (e.g., "Not using …", "Setting …", "Ignoring …").
|
|
|
|
## Reason Tags
|
|
|
|
Use reason tags to explain decisions or early exits.
|
|
|
|
- Lowercase with hyphens (e.g., `focus-mode`, `no-active-script`).
|
|
- Use a short phrase rather than a full sentence.
|
|
- If a human-readable reason is already available, it can be used directly.
|
|
|
|
## Examples
|
|
|
|
```text
|
|
WEB: Not using caret navigation (reason=disabled)
|
|
FOCUS MANAGER: Setting locus of focus to existing locus of focus (reason=no-change)
|
|
SCRIPT MANAGER: Setting active script to [script] (reason=focus: active-window)
|
|
```
|