fagfunksjoner.log package

fagfunksjoner.log.statlogger module

StatLogger module.

This module is designed to set up and manage logging within an application. The StatLogger class is meant to be the root-level logger in the application, that receives log messages from all other modules. It formats the messages in a uniform way and directs the messages to the specified outputs (console, file, etc.).

It supports four types of loggers:

  • CONSOLE: A logger that writes colored logs to the console.

  • FILE: A logger that writes logs to a file in the same format as the CONSOLE logger.

  • JSONL: A logger that writes logs to a file in JSON Lines format, including message, timestamp, severity level and an optional extra data field.

  • JSONL_EXTRA_ONLY: A logger that writes only information from the extra data field in JSON Lines format. Used for logging process and quality data. The CONSOLE and FILE loggers are enabled by default.

The JSONL and JSONL_EXTRA_ONLY loggers can log extra data by sending a dictionary with the extra data to the data extra parameter. See example below.

Examples

Create an instance of the StatLogger at the start of your application. That is in the main program or at the top of your Jupyter notebook. From then on you can use standard python logging to log from your code.

Normal setup:

>>> from fagfunksjoner.log.statlogger import StatLogger
>>> import logging
>>>
>>> root_logger = StatLogger()

Setup with different loggers and a custom filename:

>>> from fagfunksjoner.log.statlogger import StatLogger, LoggerType
>>> import logging
>>>
>>> loggers = [LoggerType.CONSOLE, LoggerType.FILE, LoggerType.JSONL]
>>> root_logger = StatLogger(loggers=loggers, log_file="custom_log_file.log")

Create log messages in your code:

>>> import logging
>>>
>>> logger = logging.getLogger(__name__)
>>> logger.info("This is an info message")
>>> logger.warning("This is a warning message")
>>>
>>> example_data = {"event": "user_login", "user_id": 123, "success": True}
>>> logger.info("Logging example data", extra={"data": example_data})

Example output:

2025-01-31T17:34:28+0100   INFO   This is an info message < log_demo.main #L34
2025-01-31T17:34:28+0100 WARNING  This is a warning message < log_demo.main #L35
2025-01-31T17:34:28+0100   INFO   Logging example data < log_demo.main #L38
class JsonlFormatter(fmt=None, datefmt=None, style='%', extra_only=False)

Bases: Formatter

Handles the formatting of log records into JSON Lines format.

This class formats log records into JSON Lines format. Basic log information like time, level, and message are included in the formatted output.

Additionally, if the log record has extra data defined in a ‘data’ attribute, it integrates it into the JSON log record. This formatter is particularly useful for structured logging or log aggregation systems that consume JSON logs.

Example

>>> logger = logging.getLogger(__name__)
>>> example_data = {"event": "user_login", "user_id": 123, "success": True}
>>> logger.info("Logging example data", extra={"data": example_data})

Initializes the JSONL formatter class.

Parameters:

  • fmt (str | None) – Format string for the log message, or None to use the default format.

  • datefmt (str | None) – Format string for the date/time, or None to use the default date/time format.

  • style (Literal['%', '{', '$']) – Style indicator for formatting. It must be one of “%”, “{”, or “$”.

  • extra_only (bool) – Boolean indicating whether to include only the extra data attribute in the log output.

format(record)

Formats a logging record into a JSON string.

Parameters:

record (LogRecord) – The log record to be formatted.

Return type:

str

Returns:

A JSON-formatted string representing the log record. Returns an empty string if no fields are included in the log record.

class LoggerType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Represents the types of loggers you can add to StatLogger.

CONSOLE = 1

A logger that writes colored logs to the console.

FILE = 2

A logger that writes logs to a file in the same format as the CONSOLE logger.

JSONL = 3

A logger that writes logs in JSON Lines format, including message, timestamp, severity level and an optional extra field.

JSONL_EXTRA_ONLY = 4

A logger that writes only information from the extra field information in JSON Lines format. Used for logging process and quality data.

class NoEmptyExtraLogsFilter(name='')

Bases: Filter

Filter to exclude log messages that would produce empty JSON.

Initialize a filter.

Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.

filter(record)

Reject records without an extra data field.

Return type:

bool

Parameters:

record (LogRecord)

class SingletonMeta

Bases: type

A thread-safe implementation of the Singleton pattern.

By using this as a class’s metaclass, we ensure that there is only one instance of the class.

class StatLogger(log_level=10, log_file='app.log', loggers=(LoggerType.CONSOLE, LoggerType.FILE))

Bases: object

A root logger class that facilitates logging to console and files.

This class is meant to be the root-level logger in an application, that receives log messages from all other modules. It formats the messages in a uniform way and directs the messages to the specified outputs (console, file, etc.)

There is only one instance of this class, ensured by a singelton pattern implementation.

Initialize the StatLogger class.

Parameters:

  • log_level (int) – The logging level. Defaults to logging.DEBUG.

  • log_file (str | Path) – The file where logs will be written. Defaults to ‘app.log’.

  • loggers (Iterable[LoggerType]) – Optional list of LoggerTypes that should be added. Defaults to LoggerType.CONSOLE and LoggerType.FILE.

  • args (Any)

  • kwargs (Any)

Raises:

TypeError – If not all loggers have type LoggerType.

Return type:

Any

getLogger()

Returns the configured logger instance.

Return type:

Logger

log_function_enter_exit(func)

Decorator that logs the entry and exit of a function.

Example:

@log_function_enter_exit
def my_local_function(a: int, b: int) -> int:
    product = a * b
    return product

Result:

2025-01-31T18:06:30+0100   INFO   -> Entering my_local_function with args: (2, 3), kwargs: {} < statlogger.wrapper #L277
2025-01-31T18:06:30+0100   INFO   <- Exiting my_local_function with result: 6 < statlogger.wrapper #L279
Return type:

TypeVar(F, bound= Callable[..., Any])

Parameters:

func (F)