Log Records

A log record represents a logging event and all of the values associated with that event.

When a logger is processing a logging event it will create a new log record, the class used for creating the record is referred to as a log record factory.

Unlike the standard logging package Burin allows for multiple log record factories to be set at once. The factory that is used can be set on a per logger basis using the BurinLogger.msgStyle property; this should be the factoryKey of the record.

The built-in log record factories for Burin are focused on allowing different styles of deferred formatting which is demonstrated in the Deferred Formatting Styles section.

Custom log record factories can be added though and offer a lot flexibility in how a log message is processed. An example of this is demonstrated in the Customisable Log Records section.

Note

Only methods defined within each Burin log record class are documented here. All log records inherit from the BurinLogRecord class.

All methods of the log record classes with an underscore_separated name also have a camelCase alias name which matches the names used in the standard logging library.

BurinLogRecord

This is the base log record; and is not used as a log record factory. It is meant to be subclassed by other log records. No formatting is done to the message.

All other Burin log record classes are derived from this class.

class burin.BurinLogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

Represents all of the values of a logging event.

Note

Unlike the builtin logging.LogRecord this does not perform any formatting of the log message. It is instead intended to just be a base class to be inherited from.

The BurinPercentLogRecord instead provides the same printf (% style) formatting of the Python builtin LogRecord.

Note

In Python 3.12 the taskName attribute was added to the standard logging.LogRecord class; it is supported here for all versions of Python compatible with Burin (including versions below 3.12).

However; names were added to asyncio.Task objects in Python 3.8, so in Python 3.7 the taskName attribute on a log record will always be None.

Custom log record factories that are created should inherit from this and typically only override the BurinLogRecord.get_message() method.

This initializes the log record and stores all relevant values.

Unlike the standard library logging.LogRecord this also stores all extra kwargs that were not used in the logging call. These can then be used later when formatting the log message.

Parameters:

name (str) – The name of the logger that was called.
level (int) – The level for the log message.
pathname (str) – The full pathname of the file where the logging call was made.
lineno (int) – The line number of where the logging call was made.
msg (str) – The logging message.
args (tuple(Any) | None) – Additional positional arguments passed with the logging call.
exc_info (tuple(type, Exception, traceback)) – Exception information related to the logging call.
func (str) – The name of the function where the logging call was made.
sinfo (str) – Text of the stack information from where the logging call was made.

get_message()

This returns the log message.

This should be overridden in subclasses to provide additional formatting or other modifications to the log message.

Returns:: The log message.
Return type:: str

BurinBraceLogRecord

This log record can be used for str.format() style formatting.

class burin.BurinBraceLogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

A log record that will be formatted in str.format() ({ style).

This allows for deferred formatting using positional and/or keyword arguments that are passed in during log record creation.

This is derived from BurinLogRecord.

factoryKey = '{': This is the key used for the class as a log record factory. This is updated automatically when the class is set using set_log_record_factory().

get_message()

This formats the log message.

All additional args and kwargs that were part of the log record creation are used for the formatting of the log message.

Returns:: The formatted log message.
Return type:: str

BurinDollarLogRecord

This log record can be used for string.Template style formatting.

class burin.BurinDollarLogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

A log record that will be formatted in string.Template ($ style).

This allows for deferred formatting using keyword arguments that are passed in during log record creation.

This is derived from BurinLogRecord.

factoryKey = '$': This is the key used for the class as a log record factory. This is updated automatically when the class is set using set_log_record_factory().

get_message()

This formats the log message.

All additional kwargs that were part of the log record creation are used for the formatting of the log message.

string.Template.safe_substitute() so no exceptions are raised if keys and format placeholders don’t all match.

Returns:: The formatted log message.
Return type:: str

BurinPercentLogRecord

This is the default log record factory and uses printf style formatting.

This should behave identically to logging.LogRecord.

class burin.BurinPercentLogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

A log record that will be formatted like printf (% style).

This allows for deferred formatting using positional arguments that are passed in during log record creation.

This should behave identically to the Python builtin logging.LogRecord in normal use cases.

This is derived from BurinLogRecord.

factoryKey = '%': This is the key used for the class as a log record factory. This is updated automatically when the class is set using set_log_record_factory().

get_message()

This formats the log message.

All additional args that were part of the log record creation are used for the formatting of the log message.

Returns:: The formatted log message.
Return type:: str