# Logbook

# 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:

- log records that were redirected from a different logging system such as the standard library’s `logging` module or the `warnings` module.

- log records that came from different processes and do not have a dispatcher equivalent in the current process.

- log records that came from over the network.

## 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:

1. 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 the `TestHandler` so that unittests can still access interpreter frames and traceback objects if necessary.

2. 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()`).

3. 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 the `MultiProcessingHandler` to send information between processes.