Logging to Tickets

Logbook supports the concept of creating unique tickets for log records and keeping track of the number of times these log records were created. The default implementation logs into a relational database, but there is a baseclass that can be subclassed to log into existing ticketing systems such as trac or other data stores.

The ticketing handlers and store backends are all implemented in the module logbook.ticketing.

How does it work?

When a ticketing handler is used each call to a logbook logger is assigned a unique hash that is based on the name of the logger, the location of the call as well as the level of the message. The message itself is not taken into account as it might be changing depending on the arguments passed to it.

Once that unique hash is created the database is checked if there is already a ticket for that hash. If there is, a new occurrence is logged with all details available. Otherwise a new ticket is created.

This makes it possible to analyze how often certain log messages are triggered and over what period of time.

Why should I use it?

The ticketing handlers have the big advantage over a regular log handler that they will capture the full data of the log record in machine processable format. Whatever information was attached to the log record will be send straight to the data store in JSON.

This makes it easier to track down issues that might happen in production systems. Due to the higher overhead of ticketing logging over a standard logfile or something comparable it should only be used for higher log levels (WARNING or higher).

Common Setups

The builtin ticketing handler is called TicketingHandler. In the default configuration it will connect to a relational database with the help of SQLAlchemy and log into two tables there: tickets go into ${prefix}tickets and occurrences go into ${prefix}occurrences. The default table prefix is 'logbook_' but can be overriden. If the tables do not exist already, the handler will create them.

Here an example setup that logs into a postgres database:

from logbook import ERROR
from logbook.ticketing import TicketingHandler
handler = TicketingHandler('postgres://localhost/database',
                                   level=ERROR)
with handler:
    # everything in this block and thread will be handled by
    # the ticketing database handler
    ...

Alternative backends can be swapped in by providing the backend parameter. There is a second implementation of a backend that is using MongoDB: MongoDBBackend.