Logger

veltix.logger.core.Logger

Thread-safe singleton logger backed by stdlib logging.

The logger is implemented as a singleton: calling Logger() or Logger.get_instance() always returns the same object. Passing a :class:LoggerConfig to either call re-configures the singleton in place and resets the level counters, exactly like configure().

Typical usage::

from veltix import Logger

logger = Logger.get_instance()
logger.info("Server started")

get_instance classmethod

get_instance(config: LoggerConfig | None = None) -> Logger

Get the singleton, optionally reconfiguring it with config.

Passing a config re-applies it to the existing instance (handlers are rebuilt and the level counters reset), exactly like configure().

Parameters:

Name	Type	Description	Default
config	LoggerConfig | None	Optional configuration to apply to the singleton.	None

Returns:

Type	Description
Logger	The shared :class:Logger instance.

configure

configure(config: LoggerConfig) -> None

Reconfigure the logger with a new config.

reset_instance classmethod

reset_instance() -> None

Reset the singleton (mainly for testing).

trace

trace(message: str, *args: object) -> None

Log a TRACE-level message (severity 5).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

debug

debug(message: str, *args: object) -> None

Log a DEBUG-level message (severity 10).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

info

info(message: str, *args: object) -> None

Log an INFO-level message (severity 20).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

success

success(message: str, *args: object) -> None

Log a SUCCESS-level message (severity 25).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

warning

warning(message: str, *args: object) -> None

Log a WARNING-level message (severity 30).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

error

error(message: str, *args: object) -> None

Log an ERROR-level message (severity 40).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

critical

critical(message: str, *args: object) -> None

Log a CRITICAL-level message (severity 50).

Parameters:

Name	Type	Description	Default
message	str	The log message, with %-style placeholders when *args are provided.	required
*args	object	Optional formatting arguments, like stdlib logging.	()

set_level

set_level(level: LogLevel) -> None

Change the minimum log level at runtime.

Parameters:

Name	Type	Description	Default
level	LogLevel	The new minimum :class:LogLevel.	required

enable

enable() -> None

Enable log output.

disable

disable() -> None

Disable all log output.

get_stats

get_stats() -> dict[LogLevel, int]

Return per-level message counts since the last reset.

Counts are best-effort: under heavy multi-thread contention a few increments may be lost (no lock on the hot path), so treat them as an approximation rather than an exact tally.

Returns:

Type	Description
dict[LogLevel, int]	A dictionary mapping each :class:LogLevel to the number of
dict[LogLevel, int]	messages logged at that level.

veltix.logger.config.LoggerConfig dataclass

Configuration for Veltix logger.

Attributes:

Name	Type	Description
level	LogLevel	Minimum log level to display
enabled	bool	Enable/disable all logging
use_colors	bool	Enable colored output for console
show_timestamp	bool	Show timestamp in logs
show_level	bool	Show log level name
show_caller	bool	Show caller file and line number (e.g. server.py:42)
file_path	str | Path | None	Path to log file
file_rotation_size	int	Max file size in bytes before rotation
file_backup_count	int	Number of backup files to keep
stream	TextIO	Output stream for console logs

__post_init__

__post_init__() -> None

Validate and normalize configuration.

veltix.logger.levels.LogLevel

Bases: IntEnum

Log severity levels.

Levels are ordered by severity, allowing simple filtering: - TRACE: Detailed debugging information - DEBUG: General debugging information - INFO: Informational messages - SUCCESS: Successful operations (between INFO and WARNING) - WARNING: Warning messages for potential issues - ERROR: Error messages for failures - CRITICAL: Critical errors requiring immediate attention

__str__

__str__() -> str

Return level name.