The Design Explained¶
This part of the documentation explains the design of Logbook in detail. This is not strictly necessary to make use of Logbook but might be helpful when writing custom handlers for Logbook or when using it in a more complex environment.
Dispatchers and Channels¶
Logbook does not use traditional loggers, instead a logger is internally
named as RecordDispatcher
. While a logger also has
methods to create new log records, the base class for all record
dispatchers itself only has ways to dispatch LogRecord
s
to the handlers. A log record itself might have an attribute that points
to the dispatcher that was responsible for dispatching, but it does not
have to be.
If a log record was created from the builtin Logger
it
will have the channel set to the name of the logger. But that itself is
no requirement. The only requirement for the channel is that it’s a
string with some human readable origin information. It could be
'Database'
if the database issued the log record, it could be
'Process-4223'
if the process with the pid 4223 issued it etc.
For example if you are logging from the logbook.log()
function they
will have a cannel set, but no dispatcher:
>>> from logbook import TestHandler, warn
>>> handler = TestHandler()
>>> handler.push_application()
>>> warn('This is a warning')
>>> handler.records[0].channel
'Generic'
>>> handler.records[0].dispatcher is None
True
If you are logging from a custom logger, the channel attribute points to the logger for as long this logger class is not garbage collected:
>>> from logbook import Logger, TestHandler
>>> logger = Logger('Console')
>>> handler = TestHandler()
>>> handler.push_application()
>>> logger.warn('A warning')
>>> handler.records[0].dispatcher is logger
True
You don’t need a record dispatcher to dispatch a log record though. The
default dispatching can be triggered from a function
dispatch_record()
:
>>> from logbook import dispatch_record, LogRecord, INFO, StreamHandler
>>> import sys
>>> record = LogRecord('My channel', INFO, 'Hello World!')
>>> dispatch_record(record)
[2015-10-05 19:18:52.211472] INFO: My channel: Hello World!
It is pretty common for log records to be created without a dispatcher. Here some common use cases for log records without a dispatcher:
The Log Record Container¶
The LogRecord
class is a simple container that
holds all the information necessary for a log record. Usually they are
created from a Logger
or one of the default log
functions (logbook.warn()
etc.) and immediately dispatched to the
handlers. The logger will apply some additional knowledge to figure out
where the record was created from and if a traceback information should be
attached.
Normally if log records are dispatched they will be closed immediately after all handlers had their chance to write it down. On closing, the interpreter frame and traceback object will be removed from the log record to break up circular dependencies.
Sometimes however it might be necessary to keep log records around for a longer time. Logbook provides three different ways to accomplish that:
Handlers can set the
keep_open
attribute of a log record to True so that the record dispatcher will not close the object. This is for example used by theTestHandler
so that unittests can still access interpreter frames and traceback objects if necessary.Because some information on the log records depends on the interpreter frame (such as the location of the log call) it is possible to pull that related information directly into the log record so that it can safely be closed without losing that information (see
pull_information()
).Last but not least, log records can be converted to dictionaries and recreated from these. It is also possible to make these dictionaries safe for JSON export which is used by the
TicketingHandler
to store information in a database or theMultiProcessingHandler
to send information between processes.