daiquiri – Python logging setup helper

Build Status Latest Version

The daiquiri library provides an easy way to configure logging. It also provides some custom formatters and handlers.

Installation

pip install daiquiri

If you want to enable support of JSON output, you must also install the json flavor:

pip install daiquiri[json]

If you want to enable systemd support, you must install the systemd flavor:

pip install daiquiri[systemd]

Usage

The basic usage of daiquiri is to call the daiquiri.setup function that will setup logging with the options passed as keyword arguments. If no arguments are passed, the default will log to stderr. If stderr is a terminal, the output will use colors.

import logging

import daiquiri

daiquiri.setup(level=logging.INFO)

logger = daiquiri.getLogger(__name__)
logger.info("It works and log to stderr by default with color!")

You can specify different outputs with different formatters. The daiquiri.output module provides a collection of Output classes that you can use to your liking to configure the logging output. Any number of output can be configured.

import logging
import sys

import daiquiri

# Log both to stdout and as JSON in a file called /dev/null. (Requires
# `python-json-logger`)
daiquiri.setup(level=logging.INFO, outputs=(
    daiquiri.output.Stream(sys.stdout),
    daiquiri.output.File("/dev/null",
                         formatter=daiquiri.formatter.JSON_FORMATTER),
    ))

logger = daiquiri.getLogger(__name__, subsystem="example")
logger.info("It works and log to stdout and /dev/null with JSON")

If the default output configurations suit your needs, then for convenience you may pass the name of an output as a string rather than needing to import the class and produce an instance.

import logging

import daiquiri

daiquiri.setup(level=logging.INFO, outputs=('stdout', 'stderr'))

logger = daiquiri.getLogger(__name__)
logger.info("It works and logs to both stdout and stderr!")

At the moment the names ‘stderr’, ‘stdout’, ‘syslog’, and ‘journal’ are available, assuming the underlying handler is available.

Picking format

You can configure the format of any output by passing a formatter as the formatter argument to the contructor. Two default formatters are available: daiquiri.formatter.TEXT_FORMATTER which prints log messages as text, and the daiquiri.formatter.JSON_FORMATTER which prints log messages as parsable JSON (requires python-json-logger).

You can provide any class of type logging.Formatter as a formatter.

import logging

import daiquiri
import daiquiri.formatter

daiquiri.setup(level=logging.INFO, outputs=(
    daiquiri.output.Stream(formatter=daiquiri.formatter.ColorFormatter(
        fmt="%(asctime)s [PID %(process)d] [%(levelname)s] "
        "%(name)s -> %(message)s")),
    ))

logger = daiquiri.getLogger(__name__)
logger.info("It works with a custom format!")

Python warning support

The Python warnings module is sometimes used by applications and libraries to emit warnings. By default, they are printed on stderr. Daiquiri overrides this by default and log warnings to the py.warnings logger.

This can be disabled by passing the capture_warnings=False argument to daiquiri.setup.

Extra usage

While it’s not mandatory to use daiquiri.getLogger to get a logger instead of logging.getLogger, it is recommended as daiquiri provides an enhanced version of the logger object. It allows any keyword argument to be passed to the logging method and that will be available as part of the record.

import logging

import daiquiri
import daiquiri.formatter

daiquiri.setup(level=logging.INFO, outputs=(
    daiquiri.output.Stream(formatter=daiquiri.formatter.ColorFormatter(
        fmt=(daiquiri.formatter.DEFAULT_FORMAT +
             " [%(subsystem)s is %(mood)s]"))),
    ))

logger = daiquiri.getLogger(__name__, subsystem="example")
logger.info("It works and log to stderr by default with color!",
            mood="happy")

Syslog support

The daiquiri.output.Syslog output provides syslog output.

Systemd journal support

The daiquiri.output.Journal output provides systemd journal support. All the extra arguments passed to the logger will be shipped as extra keys to the journal.

File support

The daiquiri.output.File output class provides support to log into a file.

daiquiri.output.RotatingFile class logs to a file that rotates when a maximum file size has been reached.

daiquiri.output.TimedRotatingFile will rotate the log file on a fixed interval.

import datetime
import logging

import daiquiri

daiquiri.setup(
    level=logging.DEBUG,
    outputs=(
        daiquiri.output.File('errors.log', level=logging.ERROR),
        daiquiri.output.TimedRotatingFile(
            'everything.log',
            level=logging.DEBUG,
            interval=datetime.timedelta(hours=1))
    )
)

logger = daiquiri.getLogger(__name__)

logger.info('only to rotating file logger')
logger.error('both log files, including errors only')

API

Output

Handlers

Formatter