1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
=======================================
daiquiri -- Python logging setup helper
=======================================
.. image:: https://circleci.com/gh/jd/daiquiri.svg?style=svg
:target: https://circleci.com/gh/jd/daiquiri
.. image:: https://img.shields.io/pypi/v/daiquiri.svg
:target: https://pypi.python.org/pypi/daiquiri
:alt: Latest Version
The daiquiri library provides an easy way to configure logging. It also
provides some custom formatters and handlers.
* Free software: Apache license
* Source: https://github.com/jd/daiquiri
Installation
============
pip install daiquiri
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.
.. literalinclude:: ../../examples/basic.py
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.
.. literalinclude:: ../../examples/output.py
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.
.. literalinclude:: ../../examples/stringnames.py
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.
.. literalinclude:: ../../examples/formatter.py
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.
.. literalinclude:: ../../examples/extra.py
Advanced Extra usage
-----------
The enhanced logger object provided by `daiquiri.getLogger` is also capable of
supporting keyword arguments to the logging method without the logger itself
having been configured to expect those specific keywords. This requires the
use of the ExtrasFormatter or the ColorExtrasFormatter classes. The
documentation for the ExtrasFormatter specifies the various options you can
configure on it.
.. literalinclude:: ../../examples/advanced_extra.py
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.
.. literalinclude:: ../../examples/files.py
Excepthook Integration
----------------------
The `daiquiri.setup` method accepts an optional `set_excepthook` keyword argument
(defaults to `True`) which controls whether or not Daiquiri will override the
global `sys.excepthook`. Disabling this can be useful when using Daiquiri alongside
another library which requires setting the excepthook, e.g. an error reporting
library.
.. literalinclude:: ../../examples/excepthook.py
API
===
.. automodule:: daiquiri
:members:
Output
------
.. automodule:: daiquiri.output
:members:
Handlers
--------
.. automodule:: daiquiri.handlers
:members:
Formatter
---------
.. automodule:: daiquiri.formatter
:members:
|
