Logging¶

Logging configuration utilities for console, file, and JSON output.

Logging configuration utilities for happysimulator.

This module provides helper functions to configure logging for the library. By default, happysimulator is silent (uses NullHandler). Users must explicitly enable logging using the functions provided here.

Example usage

import happysimulator

Simple console logging¶

happysimulator.enable_console_logging(level="DEBUG")

Rotating file logging (prevents disk space issues)¶

happysimulator.enable_file_logging("simulation.log", max_bytes=10_000_000)

JSON logging for log aggregation (ELK, Datadog, etc.)¶

happysimulator.enable_json_logging()

Configure from environment variables¶

happysimulator.configure_from_env()

Environment variables

HS_LOGGING: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) HS_LOG_FILE: Path to log file (enables rotating file logging) HS_LOG_JSON: Set to "1" for JSON output

JsonFormatter ¶

Bases: Formatter

Formats log records as JSON for structured logging.

Output is compatible with ELK stack, Datadog, and other log aggregators.

Example output

{"timestamp": "2024-01-15T10:30:00.123456Z", "level": "INFO", "logger": "happysimulator.core.simulation", "message": "Simulation started"}

format ¶

format(record: LogRecord) -> str

Format the log record as a JSON string.

enable_console_logging ¶

enable_console_logging(
    level: LogLevel | int = "INFO",
    format: str = DEFAULT_FORMAT,
    date_format: str = DEFAULT_DATE_FORMAT,
) -> logging.StreamHandler

Enable console (stderr) logging for happysimulator.

Parameters:

Name	Type	Description	Default
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	`'INFO'`
`format`	`str`	Log message format string.	`DEFAULT_FORMAT`
`date_format`	`str`	Date format string for %(asctime)s.	`DEFAULT_DATE_FORMAT`

Returns:

Type	Description
`StreamHandler`	The created StreamHandler.

Example

import happysimulator happysimulator.enable_console_logging(level="DEBUG")

enable_file_logging ¶

enable_file_logging(
    path: str | Path,
    level: LogLevel | int = "INFO",
    max_bytes: int = DEFAULT_MAX_BYTES,
    backup_count: int = DEFAULT_BACKUP_COUNT,
    format: str = DEFAULT_FORMAT,
    date_format: str = DEFAULT_DATE_FORMAT,
) -> RotatingFileHandler

Enable rotating file logging for happysimulator.

Uses RotatingFileHandler to prevent unbounded disk usage. When the log file reaches max_bytes, it is renamed with a numeric suffix and a new file is created. Up to backup_count old files are kept.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the log file. Parent directories are created automatically.	required
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	`'INFO'`
`max_bytes`	`int`	Maximum size of each log file in bytes. Default 10 MB.	`DEFAULT_MAX_BYTES`
`backup_count`	`int`	Number of backup files to keep. Default 5.	`DEFAULT_BACKUP_COUNT`
`format`	`str`	Log message format string.	`DEFAULT_FORMAT`
`date_format`	`str`	Date format string for %(asctime)s.	`DEFAULT_DATE_FORMAT`

Returns:

Type	Description
`RotatingFileHandler`	The created RotatingFileHandler.

Example

import happysimulator happysimulator.enable_file_logging( ... "logs/simulation.log", ... max_bytes=50_000_000, # 50 MB ... backup_count=10, ... )

enable_timed_file_logging ¶

enable_timed_file_logging(
    path: str | Path,
    level: LogLevel | int = "INFO",
    when: str = "midnight",
    interval: int = 1,
    backup_count: int = DEFAULT_BACKUP_COUNT,
    format: str = DEFAULT_FORMAT,
    date_format: str = DEFAULT_DATE_FORMAT,
) -> TimedRotatingFileHandler

Enable time-based rotating file logging for happysimulator.

Uses TimedRotatingFileHandler to rotate logs at specified intervals.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the log file. Parent directories are created automatically.	required
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	`'INFO'`
`when`	`str`	Rotation interval type. Options: - 'S': Seconds - 'M': Minutes - 'H': Hours - 'D': Days - 'midnight': Roll over at midnight - 'W0'-'W6': Roll over on weekday (0=Monday)	`'midnight'`
`interval`	`int`	Interval count (e.g., interval=2, when='D' means every 2 days).	`1`
`backup_count`	`int`	Number of backup files to keep. Default 5.	`DEFAULT_BACKUP_COUNT`
`format`	`str`	Log message format string.	`DEFAULT_FORMAT`
`date_format`	`str`	Date format string for %(asctime)s.	`DEFAULT_DATE_FORMAT`

Returns:

Type	Description
`TimedRotatingFileHandler`	The created TimedRotatingFileHandler.

Example

import happysimulator happysimulator.enable_timed_file_logging( ... "logs/simulation.log", ... when="midnight", ... backup_count=30, # Keep 30 days ... )

enable_json_logging ¶

enable_json_logging(
    level: LogLevel | int = "INFO",
) -> logging.StreamHandler

Enable JSON console logging for happysimulator.

Outputs structured JSON logs to stderr, suitable for log aggregation systems like ELK stack, Datadog, Splunk, etc.

Parameters:

Name	Type	Description	Default
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	`'INFO'`

Returns:

Type	Description
`StreamHandler`	The created StreamHandler with JsonFormatter.

Example

import happysimulator happysimulator.enable_json_logging()

Output:¶

enable_json_file_logging ¶

enable_json_file_logging(
    path: str | Path,
    level: LogLevel | int = "INFO",
    max_bytes: int = DEFAULT_MAX_BYTES,
    backup_count: int = DEFAULT_BACKUP_COUNT,
) -> RotatingFileHandler

Enable JSON rotating file logging for happysimulator.

Combines rotating file handler with JSON formatting for structured logs that can be processed by log aggregation pipelines.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the log file. Parent directories are created automatically.	required
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	`'INFO'`
`max_bytes`	`int`	Maximum size of each log file in bytes. Default 10 MB.	`DEFAULT_MAX_BYTES`
`backup_count`	`int`	Number of backup files to keep. Default 5.	`DEFAULT_BACKUP_COUNT`

Returns:

Type	Description
`RotatingFileHandler`	The created RotatingFileHandler with JsonFormatter.

Example

import happysimulator happysimulator.enable_json_file_logging("logs/simulation.json")

configure_from_env ¶

configure_from_env() -> None

Configure logging from environment variables.

Reads the following environment variables

HS_LOGGING: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
HS_LOG_FILE: Path to log file (enables rotating file logging)
HS_LOG_JSON: Set to "1" for JSON output format

If no environment variables are set, this function does nothing.

Example

In shell:¶

export HS_LOGGING=DEBUG export HS_LOG_FILE=simulation.log

In Python:¶

import happysimulator happysimulator.configure_from_env()

set_level ¶

set_level(level: LogLevel | int) -> None

Set the global log level for happysimulator.

Parameters:

Name	Type	Description	Default
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	required

Example

import happysimulator happysimulator.enable_console_logging() happysimulator.set_level("DEBUG")

set_module_level ¶

set_module_level(
    module: str, level: LogLevel | int
) -> None

Set the log level for a specific happysimulator submodule.

Allows fine-grained control over which parts of the library produce logs.

Parameters:

Name	Type	Description	Default
`module`	`str`	Module name relative to happysimulator (e.g., "core.simulation").	required
`level`	`LogLevel \| int`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int.	required

Example

import happysimulator happysimulator.enable_console_logging(level="INFO") happysimulator.set_module_level("core.simulation", "DEBUG") # Verbose sim happysimulator.set_module_level("distributions", "WARNING") # Quiet dists

disable_logging ¶

disable_logging() -> None

Completely disable logging for happysimulator.

Removes all handlers and sets level to CRITICAL+1 to silence all output.

Example

import happysimulator happysimulator.enable_console_logging()

... some logging happens ...¶

happysimulator.disable_logging() # Silence