Formatters

The purpose of a formatter is to convert a BurinLogRecord into (typically) a textual representation of the logging event according to a specified format.

A BurinFormatter should be set on every handler, but if a handler doesn’t have one then a very simple formatter will be used instead.

If multiple logs need to be formatted in a batch for a custom handler then a BurinBufferingFormatter can be used or a subclass of it can be created to meet those needs.

BurinFormatter

The BurinFormatter is derived from logging.Formatter and should function identically in almost all use cases.

Note

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

class burin.BurinFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Formatter for converting a log record for output.

Note

This is a subclass of logging.Formatter but has some minor changes (such as raising FormatError instead of ValueError).

These changes shouldn’t impact normal usage when compared with the standard logging library.

Formatters are responsible for converting a log record into (usually) a string which can then be output by a handler.

Below is the attributes of a log record that could be useful to log. Any of these can be added to the format string in whatever formatting style that is selected.

asctime

Time the log record was created in a human readable format.

created

Time the log record was created as returned by time.time()

filename

Filename from where the logging call was issued.

Note

This is only the filename part; for the whole path see pathname

funcName

Name of the function where the logging call was issued.

levelname

Text name for the logging level of the record.

levelno

Numeric value for logging level of the record.

lineno

Line number where the logging call was issued.

message

Log message as processed by BurinLogRecord.get_message() method.

This is set on the record when BurinFormatter.format() is called.

module

Module name where the logging call was issued.

msecs

Millisecond portion of the time when the log record was created.

name

Name of the logger that was called.

pathname

Full pathname of the source file where the logging call was issued.

process

Process Id

processName

Process name

relativeCreated

Time in milliseconds from when the log record was created since the Burin package was loaded.

taskName

Asyncio task name.

Note

In Python 3.12 this was added to the standard library; it is supported here for all versions of Python compatible with Burin (including versions below 3.12).

However; this will always be None in Python 3.7 as Task names were added in Python 3.8.

thread

Thread Id

threadName

Thread name

Note

Some of the attributes may not have values depending on the Python implementation used or the values of logMultiprocessing, logProcesses, and logThreads.

Note

There are other attributes of log records which are part of its operation and should not need to be formatted. It is recommended to stick to the list above.

The formatter will use the format string and specified style.

You can use datefmt to change how the time and date are formatted, otherwise the default is an ISO8601-like format.

If no format string is provided a simple style-dependent default is used which just includes the message from the log record.

Note

In Python 3.8 validate was added to the standard logging.Formatter; it is supported here for all versions of Python compatible with Burin (including versions below 3.8).

In Python 3.10 defaults was added to the standard logging.Formatter; it is supported here for all versions of Python compatible with Burin (including versions below 3.10).

Parameters:

  • fmt (str) – The format string to use when formatting a log record. If this is None then a default style-specific format string will be used that has just the log message.

  • datefmt (str) – The date/time format to use (as accepted by time.strftime()). If this is None then a default format similar to the ISO8601 standard is used.

  • style (str) – The type of formatting to use for the format string. Possible values are ‘%’ for %-formatting, ‘{’ for str.format() formatting, and ‘$’ for string.Template formatting. (Default = ‘%’)

  • validate (bool) – Whether the format should be validated against the style to protect again misconfiguration. (Default = True)

  • defaults (dict{str: Any}) – A dictionary that provides default values for custom fields. This is a keyword only argument and cannot be passed as a positional argument.

Raises:

FormatError – If there are errors with the format or style, or if validate is True and validation fails.

format(record)

Format the record as text.

The record’s attribute dictionary is used for the string formatting operation.

Before the formatting occurs some other steps are taken such as calling BurinLogRecord.get_message() to get the complete log message, any time formatting that may be needed, and exception formatting if necessary.

Parameters:

record (BurinLogRecord) – The log record to format.

Returns:

The log record formatted to text.

Return type:

str

format_time(record, datefmt=None)

Gets the creation time of the specified log record as formatted text.

This should be called by the formatter itself within BurinFormatter.format(); it is separated here to simplify overriding how the time is formatted.

Note

In Python 3.9 this method was changed on the standard logging.Formatter so that the class attribute default_msec_format is optional. This is supported here for all versions of Python compatible with Burin (including versions below 3.9).

Parameters:

  • record (BurinLogRecord) – The log record to get the time from.

  • datefmt (str) – The date/time format to use (as accepted by time.strftime()). If None then the datefmt passed in during initialization of the BurinFormatter instance is used.

Returns:

The formatted date and time of the log record.

Return type:

str

BurinBufferingFormatter

This cannot be used by any built-in handlers but provides a class that can be used for formatting a batch of log records at once if needed by a custom handler.

class burin.BurinBufferingFormatter(linefmt=None)

A formatter that can be used for formatting multiple records in a batch.

Note

This is a subclass of logging.BufferingFormatter and functions identically to it in normal use cases.

This will set a formatter to use for every record.

If no formatter is set then a default formatter is used.

Parameters:

linefmt (BurinFormatter) – The formatter to use. If this is None then a default formatter will be used. (Default = None)