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.
`redact_params`(params)	Redact sensitive values from a parameters dictionary.
`redact_url`(url)	Redact sensitive query parameters from a URL.
`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)[source]

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)[source]

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='')[source]

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)[source]

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()[source]

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)[source]

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()[source]

Clear all log context fields.

Return type:: None

babylon.utils.log.log_context_scope(**kwargs)[source]

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]

babylon.utils.log.redact_url(url)[source]

Redact sensitive query parameters from a URL.

Parameters:: url (str) – URL string that may contain API keys in query params.
Return type:: str
Returns:: URL with sensitive parameter values replaced by ‘***’.

Example

>>> redact_url("https://api.census.gov/data?key=SECRET&get=NAME")
'https://api.census.gov/data?key=***&get=NAME'

babylon.utils.log.redact_params(params)[source]

Redact sensitive values from a parameters dictionary.

Parameters:: params (dict[str, Any]) – Dictionary of parameters that may contain API keys.
Return type:: dict[str, Any]
Returns:: Dictionary with sensitive values replaced by ‘***’.

Example

>>> redact_params({"key": "SECRET", "state": "06"})
{'key': '***', 'state': '06'}