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
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
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
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.channel 'Generic' >>> handler.records.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.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
>>> 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¶
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
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
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_openattribute of a log record to True so that the record dispatcher will not close the object. This is for example used by the
TestHandlerso 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
- 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
TicketingHandlerto store information in a database or the
MultiProcessingHandlerto send information between processes.