Logging

Owlbot logs startup information, errors, and runtime activity to help with troubleshooting and monitoring. By default, logs go to stdout, with an optional file log for persistent storage.

Log Levels

INFO logs high-level events: startup, configuration, module loading, and errors. DEBUG adds internal details like event dispatch, storage operations, and handler execution, which is useful for troubleshooting.

uv run owlbot        # INFO level
uv run owlbot -v     # DEBUG level

File Logging

Setting log_dir causes Owlbot to write an owlbot.log file to that directory in addition to stdout. The file uses the same log level and format as stdout. Logs are appended indefinitely; there is no built-in rotation or deletion.

The directory can be configured via the config file, environment variable, or CLI flag:

uv run owlbot -l logs/                   # CLI flag
OWLBOT_LOG_DIR=logs/ uv run owlbot      # environment variable

# config.yaml
owlbot:
  log_dir: "logs"

If the directory does not exist, it is created automatically. If the path is not writable, a warning is logged to stdout and the bot continues without file logging.

Logger Names

Owlbot uses a hierarchical naming scheme rooted at owlbot. Module loggers are named owlbot.modules.<module_name>, so log output from a module called ping appears as owlbot.modules.ping. This makes it straightforward to filter output with standard tools:

uv run owlbot -v | grep "owlbot.modules.ping"

Built-in Modules

Creating New Modules