cthulhu/docs/LOGGING.md

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

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)