oizom_logger

Structured logging framework for Oizom IoT edge devices.

Provides a centralized, configurable logging stack with context-based filtering, timezone-aware timestamps, ANSI color output, and safe rotating file handlers used by every module in the Oizom hardware codebase.

The logging pipeline is built from composable components that can be used independently or combined through the OizomLogger public wrapper:

  • LoggerConfig – immutable dataclass holding all configuration

  • ContextFilter – injects a context token (e.g. "INIT", "READ") into every logging.LogRecord for easy grep-based filtering of logs.

  • StructuredFormatter – pipe-delimited format with optional timezone conversion and country indicators (emoji or code).

  • ColorFormatter – ANSI color wrapper that respects NO_COLOR and FORCE_COLOR environment variables plus TTY detection.

  • SafeRotatingFileHandler – rotation that tolerates missing backup files and transient OSError on rename/remove.

  • OizomLogger – public API combining all of the above.

Example

Create a logger and emit a context-tagged message:

from utils.oizom_logger import OizomLogger

context_logger = OizomLogger(__name__)
context_logger.info_with_context("INIT", "Sensor setup complete")

basic_logger = OizomLogger(__name__).get()
basic_logger.info("Standard log message")

Note

This module is imported by nearly every file in the codebase. It must remain free of circular imports – in particular it must not import from Sensor, Manager, or any OzWrapper module.

Classes

OizomLogger

High-level logger wrapper backed by LoggerConfig.

Functions

apply_logger_config(→ None)

Re-apply a configuration dictionary to every existing logger.

Module Contents

oizom_logger.apply_logger_config(config_dict: dict[str, Any]) → None

Re-apply a configuration dictionary to every existing logger.

Walks logging.Logger.manager.loggerDict, rebuilding the handler stack of any logger that already has at least one handler attached (i.e. has been configured through OizomLogger). Useful for honouring runtime configuration reloads (e.g. when the operator updates logger_config.json on the device).

Parameters:

config_dict – Mapping accepted by LoggerConfig.from_dict(); the same options used at OizomLogger construction time.

Returns:

None.

Raises:

OSError – Propagated from _build_file_handler() if the new log path cannot be opened.

Example

>>> apply_logger_config({"console_level": "WARNING"})

Note

Loggers that have never been touched (no handlers) are skipped to avoid materializing accidental noise from imported modules.