6.28.3 Formatter Objects

Formatters have the following attributes and methods. They are responsible for converting a LogRecord to (usually) a string which can be interpreted by either a human or an external system. The base Formatter allows a formatting string to be specified. If none is supplied, the default value of '%(message)s\' is used.

A Formatter can be initialized with a format string which makes use of knowledge of the LogRecord attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a LogRecord's message attribute. This format string contains standard python %-style mapping keys. See section 2.2.6, ``String Formatting Operations,'' for more information on string formatting.

Currently, the useful mapping keys in a LogRecord are:

Format Description

%(name)s Name of the logger (logging channel).
%(levelno)s Numeric logging level for the message (DEBUG, INFO, WARNING, ERROR, CRITICAL).
%(levelname)s Text logging level for the message ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
%(pathname)s Full pathname of the source file where the logging call was issued (if available).
%(filename)s Filename portion of pathname.
%(module)s Module (name portion of filename).
%(lineno)d Source line number where the logging call was issued (if available).
%(created)f Time when the LogRecord was created (as returned by time.time()).
%(asctime)s Human-readable time when the LogRecord was created. By default this is of the form ``2003-07-08 16:49:45,896'' (the numbers after the comma are millisecond portion of the time).
%(msecs)d Millisecond portion of the time when the LogRecord was created.
%(thread)d Thread ID (if available).
%(process)d Process ID (if available).
%(message)s The logged message, computed as msg % args.

Format	Description
`%(name)s`	Name of the logger (logging channel).
`%(levelno)s`	Numeric logging level for the message (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).
`%(levelname)s`	Text logging level for the message (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
`%(pathname)s`	Full pathname of the source file where the logging call was issued (if available).
`%(filename)s`	Filename portion of pathname.
`%(module)s`	Module (name portion of filename).
`%(lineno)d`	Source line number where the logging call was issued (if available).
`%(created)f`	Time when the LogRecord was created (as returned by `time.time()`).
`%(asctime)s`	Human-readable time when the LogRecord was created. By default this is of the form ``2003-07-08 16:49:45,896'' (the numbers after the comma are millisecond portion of the time).
`%(msecs)d`	Millisecond portion of the time when the `LogRecord` was created.
`%(thread)d`	Thread ID (if available).
`%(process)d`	Process ID (if available).
`%(message)s`	The logged message, computed as `msg % args`.

class Formatter( [fmt[, datefmt]]): Returns a new instance of the Formatter class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, '%(message)s' is used. If no datefmt is specified, the ISO8601 date format is used.

format( record): The record's attribute dictionary is used as the operand to a string formatting operation. Returns the resulting string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using msg % args. If the formatting string contains '(asctime)', formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatTime( record[, datefmt]): This method should be called from format() by a formatter which wants to make use of a formatted time. This method can be overridden in formatters to provide for any specific requirement, but the basic behavior is as follows: if datefmt (a string) is specified, it is used with time.strftime() to format the creation time of the record. Otherwise, the ISO8601 format is used. The resulting string is returned.

formatException( exc_info): Formats the specified exception information (a standard exception tuple as returned by sys.exc_info()) as a string. This default implementation just uses traceback.print_exception(). The resulting string is returned.

See About this document... for information on suggesting changes.