babylon.utils.log

Custom logging utilities for Babylon.

Logging is the nervous system of the simulation. Every action must be traceable, every decision auditable.

This module provides: - JSONFormatter: Dependency-free JSON Lines formatter - TRACE level: Ultra-verbose debugging (level=5) - LogContext: Context propagation for correlation IDs and tick numbers

Module Attributes

TRACE

Ultra-verbose tracing level for deep debugging.

Functions

clear_log_context()	Clear all log context fields.
get_log_context()	Get the current log context.
log_context_scope(**kwargs)	Context manager for scoped log context.
set_log_context(**kwargs)	Set log context fields.

Classes

ContextAwareFilter([name])	Logging filter that injects context fields into LogRecords.
JSONFormatter([fmt, datefmt, style, ...])	JSON Lines formatter - zero external dependencies.

babylon.utils.log.TRACE: int = 5

Ultra-verbose tracing level for deep debugging.

NEVER enable in production. For materialist microscopy only.

class babylon.utils.log.JSONFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

JSON Lines formatter - zero external dependencies.

Produces machine-parseable JSONL output suitable for log aggregation. Each log record becomes a single JSON object on one line.

Output format:

{“ts”:”2025-01-09T14:23:45.123Z”,”level”:”ERROR”,”logger”:”babylon.rag”,…}

Extra fields (tick, correlation_id, exception, etc.) are automatically included from the LogRecord’s __dict__.

STANDARD_FIELDS: frozenset[str] = frozenset({'args', 'created', 'exc_info', 'exc_text', 'filename', 'funcName', 'levelname', 'levelno', 'lineno', 'message', 'module', 'msecs', 'msg', 'name', 'pathname', 'process', 'processName', 'relativeCreated', 'stack_info', 'taskName', 'thread', 'threadName'})

format(record)

Format log record as JSON.

Parameters:

record (LogRecord) – The LogRecord to format.

Return type:

str

Returns:

JSON string representing the log entry.

class babylon.utils.log.ContextAwareFilter(name='')

Bases: Filter

Logging filter that injects context fields into LogRecords.

Automatically adds fields from the current log context (tick, simulation_id, correlation_id, etc.) to every log record.

Usage:

handler.addFilter(ContextAwareFilter())

filter(record)

Add context fields to the log record.

Parameters:

record (LogRecord) – The LogRecord to modify.

Return type:

bool

Returns:

True (always passes the record through).

babylon.utils.log.get_log_context()

Get the current log context.

Return type:

dict[str, Any]

Returns:

Dictionary containing context fields (tick, simulation_id, etc.).

babylon.utils.log.set_log_context(**kwargs)

Set log context fields.

These fields will be automatically included in log entries when using the ContextAwareFilter.

Parameters:

**kwargs (Any) – Context fields to set (tick, simulation_id, correlation_id, etc.).

Return type:

None

babylon.utils.log.clear_log_context()

Clear all log context fields.

Return type:

None

babylon.utils.log.log_context_scope(**kwargs)

Context manager for scoped log context.

Context fields are automatically restored when exiting the scope.

Usage:

with log_context_scope(tick=42, simulation_id=”abc”):

logger.info(“Tick complete”) # Includes tick and simulation_id

Parameters:

**kwargs (Any) – Context fields to set within the scope.

Yields:

None

Return type:

Generator[None, None, None]