Module

utils.logger

Structured logging system for Bengal SSG.

Provides phase-aware logging with context propagation, timing, and structured event emission. Designed for observability into the 22-phase build pipeline.

Example:

from bengal.utils.logger import get_logger

logger = get_logger(__name__)

with logger.phase("discovery", page_count=100):
    logger.info("discovered_content", files=len(files))
    logger.debug("parsed_frontmatter", page=page.path, keys=list(metadata.keys()))
View source
4 Classes 8 Functions

Classes

LogLevel
Log levels in order of severity.
0

Log levels in order of severity.

Inherits from Enum
LogEvent dataclass
Structured log event with context.
2

Structured log event with context.

Attributes

Name Type Description
timestamp str
level str
logger_name str
event_type str
message str
phase str | None
phase_depth int
duration_ms float | None
memory_mb float | None
peak_memory_mb float | None
context dict[str, Any]

Methods 2

to_dict
Convert to dictionary for JSON serialization.
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Convert to dictionary for JSON serialization.

Returns

dict[str, Any]

format_console
Format for console output using Rich markup.
1 str 
def format_console(self, verbose: bool = False) -> str

Format for console output using Rich markup.

Parameters 1
verbose bool
Returns

str

BengalLogger
Phase-aware structured logger for Bengal builds. Tracks build phases, emits structured events, and…
14

Phase-aware structured logger for Bengal builds.

Tracks build phases, emits structured events, and provides timing information. All logs are written to both console and a build log file.

Methods 10

phase
Context manager for tracking build phases with timing and memory.
1 Any 
def phase(self, name: str, **context: Any) -> Any

Context manager for tracking build phases with timing and memory.

Parameters 1
name str

Phase name **context: Additional context to attach to all events in phase
Returns

Any

debug
Log debug event.
1 None 
def debug(self, message: str, **context: Any) -> None

Log debug event.

Parameters 1
message str
info
Log info event.
1 None 
def info(self, message: str, **context: Any) -> None

Log info event.

Parameters 1
message str
warning
Log warning event.
1 None 
def warning(self, message: str, **context: Any) -> None

Log warning event.

Parameters 1
message str
error
Log error event.
1 None 
def error(self, message: str, **context: Any) -> None

Log error event.

Parameters 1
message str
critical
Log critical event.
1 None 
def critical(self, message: str, **context: Any) -> None

Log critical event.

Parameters 1
message str
get_events
Get all logged events.
0 list[LogEvent] 
def get_events(self) -> list[LogEvent]

Get all logged events.

Returns

list[LogEvent]

get_phase_timings
Extract phase timings from events.
0 dict[str, float] 
def get_phase_timings(self) -> dict[str, float]

Extract phase timings from events.

Returns

dict[str, float] —

Dict mapping phase names to duration in milliseconds

print_summary
Print timing summary of all phases.
0 None 
def print_summary(self) -> None

Print timing summary of all phases.

close
Close log file handle.
0 None 
def close(self) -> None

Close log file handle.

Internal Methods 4
__init__
Initialize logger.
5 None 
def __init__(self, name: str, level: LogLevel = LogLevel.INFO, log_file: Path | None = None, verbose: bool = False, quiet_console: bool = False)

Initialize logger.

Parameters 5
name str

Logger name (typically name)
level LogLevel

Minimum log level to emit
log_file Path | None

Path to log file (optional)
verbose bool

Whether to show verbose output
quiet_console bool

Suppress console output (for live progress mode)
_emit
Emit a log event.
2 None 
def _emit(self, level: LogLevel, message: str, **context: Any) -> None

Emit a log event.

Parameters 2
level LogLevel

Log level
message str

Human-readable message **context: Additional context data
__enter__
Context manager entry.
0 BengalLogger 
def __enter__(self) -> BengalLogger

Context manager entry.

Returns

BengalLogger

__exit__
Context manager exit.
1 None 
def __exit__(self, exc_type: type[BaseException] | None, *args: Any) -> None

Context manager exit.

Parameters 1
exc_type type[BaseException] | None
_GlobalConfig
0
Inherits from TypedDict

Attributes

Name Type Description
level LogLevel
log_file Path | None
verbose bool
quiet_console bool

Functions

truncate_str
Truncate a string if it exceeds max_len characters.
3 str 
def truncate_str(s: str, max_len: int = 500, suffix: str = ' ... (truncated)') -> str

Truncate a string if it exceeds max_len characters.

Parameters 3

Name Type Default Description
s str —
max_len int 500
suffix str ' ... (truncated)'

Returns

str

truncate_error
Safely truncate an exception string representation.
2 str 
def truncate_error(e: Exception, max_len: int = 500) -> str

Safely truncate an exception string representation.

Parameters 2

Name Type Default Description
e Exception —
max_len int 500

Returns

str

configure_logging
Configure global logging settings.
4 None 
def configure_logging(level: LogLevel = LogLevel.INFO, log_file: Path | None = None, verbose: bool = False, track_memory: bool = False) -> None

Configure global logging settings.

Parameters 4

Name Type Default Description
level LogLevel LogLevel.INFO

Minimum log level to emit
log_file Path | None None

Path to log file
verbose bool False

Show verbose output
track_memory bool False

Enable memory profiling (adds overhead)
get_logger
Get or create a logger instance.
1 BengalLogger 
def get_logger(name: str) -> BengalLogger

Get or create a logger instance.

Parameters 1

Name Type Default Description
name str —

Logger name (typically name)

Returns

BengalLogger —

BengalLogger instance

set_console_quiet
Enable or disable console output for all loggers. Used by live progress manager to suppress struct…
1 None 
def set_console_quiet(quiet: bool = True) -> None

Enable or disable console output for all loggers.

Used by live progress manager to suppress structured log events while preserving file logging for debugging.

Parameters 1

Name Type Default Description
quiet bool True

If True, suppress console output; if False, enable it
close_all_loggers
Close all logger file handles.
0 None 
def close_all_loggers() -> None

Close all logger file handles.

reset_loggers
Close all loggers and clear the registry (for testing).
0 None 
def reset_loggers() -> None

Close all loggers and clear the registry (for testing).

print_all_summaries
Print timing and memory summaries from all loggers.
0 None 
def print_all_summaries() -> None

Print timing and memory summaries from all loggers.