Debian Codegraph @

docs/howto/logging.txt

raw
1 .. _logging-how-to:
2
3 ================================
4 How to configure and use logging
5 ================================
6
7 .. seealso::
8
9 * :ref:`Django logging reference <logging-ref>`
10 * :ref:`Django logging overview <logging-explanation>`
11
12 Django provides a working :ref:`default logging configuration
13 <default-logging-configuration>` that is readily extended.
14
15 Make a basic logging call
16 =========================
17
18 To send a log message from within your code, you place a logging call into it.
19
20 .. admonition:: Don't be tempted to use logging calls in ``settings.py``.
21
22 The way that Django logging is configured as part of the ``setup()``
23 function means that logging calls placed in ``settings.py`` may not work as
24 expected, because *logging will not be set up at that point*. To explore
25 logging, use a view function as suggested in the example below.
26
27 First, import the Python logging library, and then obtain a logger instance
28 with :py:func:`logging.getLogger`. Provide the ``getLogger()`` method with a
29 name to identify it and the records it emits. A good option is to use
30 ``__name__`` (see :ref:`naming-loggers` below for more on this) which will
31 provide the name of the current Python module as a dotted path::
32
33 import logging
34
35 logger = logging.getLogger(__name__)
36
37 It's a good convention to perform this declaration at module level.
38
39 And then in a function, for example in a view, send a record to the logger::
40
41 def some_view(request):
42 ...
43 if some_risky_state:
44 logger.warning("Platform is running at risk")
45
46 When this code is executed, a :py:class:`~logging.LogRecord` containing that
47 message will be sent to the logger. If you're using Django's default logging
48 configuration, the message will appear in the console.
49
50 The ``WARNING`` level used in the example above is one of several
51 :ref:`logging severity levels <topic-logging-parts-loggers>`: ``DEBUG``,
52 ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``. So, another example might be::
53
54 logger.critical("Payment system is not responding")
55
56 .. important::
57
58 Records with a level lower than ``WARNING`` will not appear in the console
59 by default. Changing this behavior requires additional configuration.
60
61 Customize logging configuration
62 ===============================
63
64 Although Django's logging configuration works out of the box, you can control
65 exactly how your logs are sent to various destinations - to log files, external
66 services, email and so on - with some additional configuration.
67
68 You can configure:
69
70 * logger mappings, to determine which records are sent to which handlers
71 * handlers, to determine what they do with the records they receive
72 * filters, to provide additional control over the transfer of records, and
73 even modify records in-place
74 * formatters, to convert :class:`~logging.LogRecord` objects to a string or
75 other form for consumption by human beings or another system
76
77 There are various ways of configuring logging. In Django, the
78 :setting:`LOGGING` setting is most commonly used. The setting uses the
79 :ref:`dictConfig format <logging-config-dictschema>`, and extends the
80 :ref:`default logging configuration <default-logging-definition>`.
81
82 See :ref:`configuring-logging` for an explanation of how your custom settings
83 are merged with Django's defaults.
84
85 See the :mod:`Python logging documentation <python:logging.config>` for
86 details of other ways of configuring logging. For the sake of simplicity, this
87 documentation will only consider configuration via the ``LOGGING`` setting.
88
89 .. _basic-logger-configuration:
90
91 Basic logging configuration
92 ---------------------------
93
94 When configuring logging, it makes sense to
95
96 Create a ``LOGGING`` dictionary
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 In your ``settings.py``::
100
101 LOGGING = {
102 "version": 1, # the dictConfig format version
103 "disable_existing_loggers": False, # retain the default loggers
104 }
105
106 It nearly always makes sense to retain and extend the default logging
107 configuration by setting ``disable_existing_loggers`` to ``False``.
108
109 Configure a handler
110 ~~~~~~~~~~~~~~~~~~~
111
112 This example configures a single handler named ``file``, that uses Python's
113 :class:`~logging.FileHandler` to save logs of level ``DEBUG`` and higher to the
114 file ``general.log`` (at the project root):
115
116 .. code-block:: python
117 :emphasize-lines: 3-8
118
119 LOGGING = {
120 # ...
121 "handlers": {
122 "file": {
123 "class": "logging.FileHandler",
124 "filename": "general.log",
125 },
126 },
127 }
128
129 Different handler classes take different configuration options. For more
130 information on available handler classes, see the
131 :class:`~django.utils.log.AdminEmailHandler` provided by Django and the various
132 :py:mod:`handler classes <logging.handlers>` provided by Python.
133
134 Logging levels can also be set on the handlers (by default, they accept log
135 messages of all levels). Using the example above, adding:
136
137 .. code-block:: python
138 :emphasize-lines: 4
139
140 {
141 "class": "logging.FileHandler",
142 "filename": "general.log",
143 "level": "DEBUG",
144 }
145
146 would define a handler configuration that only accepts records of level
147 ``DEBUG`` and higher.
148
149 Configure a logger mapping
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~
151
152 To send records to this handler, configure a logger mapping to use it for
153 example:
154
155 .. code-block:: python
156 :emphasize-lines: 3-8
157
158 LOGGING = {
159 # ...
160 "loggers": {
161 "": {
162 "level": "DEBUG",
163 "handlers": ["file"],
164 },
165 },
166 }
167
168 The mapping's name determines which log records it will process. This
169 configuration (``''``) is *unnamed*. That means that it will process records
170 from *all* loggers (see :ref:`naming-loggers` below on how to use the mapping
171 name to determine the loggers for which it will process records).
172
173 It will forward messages of levels ``DEBUG`` and higher to the handler named
174 ``file``.
175
176 Note that a logger can forward messages to multiple handlers, so the relation
177 between loggers and handlers is many-to-many.
178
179 If you execute::
180
181 logger.debug("Attempting to connect to API")
182
183 in your code, you will find that message in the file ``general.log`` in the
184 root of the project.
185
186 Configure a formatter
187 ~~~~~~~~~~~~~~~~~~~~~
188
189 By default, the final log output contains the message part of each :class:`log
190 record <logging.LogRecord>`. Use a formatter if you want to include additional
191 data. First name and define your formatters - this example defines
192 formatters named ``verbose`` and ``simple``:
193
194 .. code-block:: python
195 :emphasize-lines: 3-12
196
197 LOGGING = {
198 # ...
199 "formatters": {
200 "verbose": {
201 "format": "{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}",
202 "style": "{",
203 },
204 "simple": {
205 "format": "{levelname} {message}",
206 "style": "{",
207 },
208 },
209 }
210
211 The ``style`` keyword allows you to specify ``{`` for :meth:`str.format` or
212 ``$`` for :class:`string.Template` formatting; the default is ``$``.
213
214 See :ref:`logrecord-attributes` for the :class:`~logging.LogRecord` attributes
215 you can include.
216
217 To apply a formatter to a handler, add a ``formatter`` entry to the handler's
218 dictionary referring to the formatter by name, for example:
219
220 .. code-block:: python
221 :emphasize-lines: 5
222
223 "handlers": {
224 "file": {
225 "class": "logging.FileHandler",
226 "filename": "general.log",
227 "formatter": "verbose",
228 },
229 }
230
231 .. _naming-loggers:
232
233 Use logger namespacing
234 ~~~~~~~~~~~~~~~~~~~~~~
235
236 The unnamed logging configuration ``''`` captures logs from any Python
237 application. A named logging configuration will capture logs only from loggers
238 with matching names.
239
240 The namespace of a logger instance is defined using
241 :py:func:`~logging.getLogger`. For example in ``views.py`` of ``my_app``::
242
243 logger = logging.getLogger(__name__)
244
245 will create a logger in the ``my_app.views`` namespace. ``__name__`` allows you
246 to organize log messages according to their provenance within your project's
247 applications automatically. It also ensures that you will not experience name
248 collisions.
249
250 A logger mapping named ``my_app.views`` will capture records from this logger:
251
252 .. code-block:: python
253 :emphasize-lines: 4
254
255 LOGGING = {
256 # ...
257 "loggers": {
258 "my_app.views": {...},
259 },
260 }
261
262 A logger mapping named ``my_app`` will be more permissive, capturing records
263 from loggers anywhere within the ``my_app`` namespace (including
264 ``my_app.views``, ``my_app.utils``, and so on):
265
266 .. code-block:: python
267 :emphasize-lines: 4
268
269 LOGGING = {
270 # ...
271 "loggers": {
272 "my_app": {...},
273 },
274 }
275
276 You can also define logger namespacing explicitly::
277
278 logger = logging.getLogger("project.payment")
279
280 and set up logger mappings accordingly.
281
282 .. _naming-loggers-hierarchy:
283
284 Using logger hierarchies and propagation
285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286
287 Logger naming is *hierarchical*. ``my_app`` is the parent of ``my_app.views``,
288 which is the parent of ``my_app.views.private``. Unless specified otherwise,
289 logger mappings will propagate the records they process to their parents - a
290 record from a logger in the ``my_app.views.private`` namespace will be handled
291 by a mapping for both ``my_app`` and ``my_app.views``.
292
293 To manage this behavior, set the propagation key on the mappings you define::
294
295 LOGGING = {
296 # ...
297 "loggers": {
298 "my_app": {
299 # ...
300 },
301 "my_app.views": {
302 # ...
303 },
304 "my_app.views.private": {
305 # ...
306 "propagate": False,
307 },
308 },
309 }
310
311 ``propagate`` defaults to ``True``. In this example, the logs from
312 ``my_app.views.private`` will not be handled by the parent, but logs from
313 ``my_app.views`` will.
314
315 Configure responsive logging
316 ----------------------------
317
318 Logging is most useful when it contains as much information as possible, but
319 not information that you don't need - and how much you need depends upon what
320 you're doing. When you're debugging, you need a level of information that would
321 be excessive and unhelpful if you had to deal with it in production.
322
323 You can configure logging to provide you with the level of detail you need,
324 when you need it. Rather than manually change configuration to achieve this, a
325 better way is to apply configuration automatically according to the
326 environment.
327
328 For example, you could set an environment variable ``DJANGO_LOG_LEVEL``
329 appropriately in your development and staging environments, and make use of it
330 in a logger mapping thus::
331
332 "level": os.getenv("DJANGO_LOG_LEVEL", "WARNING")
333
334 \- so that unless the environment specifies a lower log level, this
335 configuration will only forward records of severity ``WARNING`` and above to
336 its handler.
337
338 Other options in the configuration (such as the ``level`` or ``formatter``
339 option of handlers) can be similarly managed.