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.
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()
.
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:
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()
.