← Back to branch summary

~ubuntu-branches/debian/sid/python-django/sid

« back to all changes in this revision

Viewing changes to docs/topics/logging.txt

  • Committer: Package Import Robot
  • Author(s): Luke Faraone
  • Date: 2013-11-07 15:33:49 UTC
  • mfrom: (1.3.12)
  • Revision ID: package-import@ubuntu.com-20131107153349-e31sc149l2szs3jb
Tags: 1.6-1
http://bugs.debian.org/557474
http://bugs.debian.org/724637
http://bugs.debian.org/636511
http://bugs.debian.org/686333
http://bugs.debian.org/704203
* New upstream version. Closes: #557474, #724637.
* python-django now also suggests the installation of ipython,
  bpython, python-django-doc, and libgdal1.
  Closes: #636511, #686333, #704203
* Set package maintainer to Debian Python Modules Team.
* Bump standards version to 3.9.5, no changes needed.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/logging.txt
169
169
``project.interesting.stuff`` loggers.
170
170
 
171
171
This propagation can be controlled on a per-logger basis. If
172
 
you don't want a particular logger to propagate to it's parents, you
 
172
you don't want a particular logger to propagate to its parents, you
173
173
can turn off this behavior.
174
174
 
175
175
Making logging calls
218
218
and the log levels and other properties that you want those components
219
219
to have.
220
220
 
221
 
Prior to Django 1.5, the :setting:`LOGGING` setting overwrote the :ref:`default
222
 
Django logging configuration <default-logging-configuration>`. From Django
223
 
1.5 forward, the project's logging configuration is merged with Django's
224
 
defaults, hence you can decide if you want to add to, or replace the existing
225
 
configuration. To completely override the default configuration, set the
226
 
``disable_existing_loggers`` key to ``True`` (which is the default) in the
227
 
:setting:`LOGGING` dictConfig. Alternatively you can redefine some or all of
228
 
the loggers by setting ``disable_existing_loggers`` to ``False``.
 
221
Prior to Django 1.5, the :setting:`LOGGING` setting always overwrote the
 
222
:ref:`default Django logging configuration <default-logging-configuration>`.
 
223
From Django 1.5 forward, it is possible to get the project's logging
 
224
configuration merged with Django's defaults, hence you can decide if you want to
 
225
add to, or replace the existing configuration.
 
226
 
 
227
If the ``disable_existing_loggers`` key in the :setting:`LOGGING` dictConfig is
 
228
set to ``True`` (which is the default) the default configuration is completely
 
229
overridden. Alternatively you can redefine some or all of the loggers by
 
230
setting ``disable_existing_loggers`` to ``False``.
229
231
 
230
232
Logging is configured as soon as settings have been loaded
231
233
(either manually using :func:`~django.conf.settings.configure` or when at least
395
397
Loggers
396
398
-------
397
399
 
398
 
Django provides three built-in loggers.
 
400
Django provides four built-in loggers.
399
401
 
400
402
``django``
401
403
~~~~~~~~~~
435
437
``settings.DEBUG`` is set to ``True``, regardless of the logging
436
438
level or handlers that are installed.
437
439
 
 
440
``django.security.*``
 
441
~~~~~~~~~~~~~~~~~~~~~~
 
442
 
 
443
The security loggers will receive messages on any occurrence of
 
444
:exc:`~django.core.exceptions.SuspiciousOperation`. There is a sub-logger for
 
445
each sub-type of SuspiciousOperation. The level of the log event depends on
 
446
where the exception is handled.  Most occurrences are logged as a warning, while
 
447
any ``SuspiciousOperation`` that reaches the WSGI handler will be logged as an
 
448
error. For example, when an HTTP ``Host`` header is included in a request from
 
449
a client that does not match :setting:`ALLOWED_HOSTS`, Django will return a 400
 
450
response, and an error message will be logged to the
 
451
``django.security.DisallowedHost`` logger.
 
452
 
 
453
Only the parent ``django.security`` logger is configured by default, and all
 
454
child loggers will propagate to the parent logger. The ``django.security``
 
455
logger is configured the same as the ``django.request`` logger, and any error
 
456
events will be mailed to admins. Requests resulting in a 400 response due to
 
457
a ``SuspiciousOperation`` will not be logged to the ``django.request`` logger,
 
458
but only to the ``django.security`` logger.
 
459
 
 
460
To silence a particular type of SuspiciousOperation, you can override that
 
461
specific logger following this example::
 
462
 
 
463
        'loggers': {
 
464
            'django.security.DisallowedHost': {
 
465
                'handlers': ['null'],
 
466
                'propagate': False,
 
467
            },
 
468
 
438
469
Handlers
439
470
--------
440
471
 
441
472
Django provides one log handler in addition to those provided by the
442
473
Python logging module.
443
474
 
444
 
.. class:: AdminEmailHandler([include_html=False])
 
475
.. class:: AdminEmailHandler(include_html=False, email_backend=None)
445
476
 
446
477
    This handler sends an email to the site admins for each log
447
478
    message it receives.
477
508
    sensitive information to be filtered out of error reports -- learn more on
478
509
    :ref:`Filtering error reports<filtering-error-reports>`.
479
510
 
 
511
    .. versionadded:: 1.6
 
512
 
 
513
    By setting the ``email_backend`` argument of ``AdminEmailHandler``, the
 
514
    :ref:`email backend <topic-email-backends>` that is being used by the
 
515
    handler can be overridden, like this::
 
516
 
 
517
        'handlers': {
 
518
            'mail_admins': {
 
519
                'level': 'ERROR',
 
520
                'class': 'django.utils.log.AdminEmailHandler',
 
521
                'email_backend': 'django.core.mail.backends.filebased.EmailBackend',
 
522
            }
 
523
        },
 
524
 
 
525
    By default, an instance of the email backend specified in
 
526
    :setting:`EMAIL_BACKEND` will be used.
 
527
 
480
528
.. _Sentry: http://pypi.python.org/pypi/sentry
481
529
 
482
530
 
488
536
 
489
537
.. class:: CallbackFilter(callback)
490
538
 
491
 
   .. versionadded:: 1.4
492
 
 
493
539
   This filter accepts a callback function (which should accept a single
494
540
   argument, the record to be logged), and calls it for each record that passes
495
541
   through the filter. Handling of that record will not proceed if the callback
526
572
 
527
573
.. class:: RequireDebugFalse()
528
574
 
529
 
   .. versionadded:: 1.4
530
 
 
531
575
   This filter will only pass on records when settings.DEBUG is False.
532
576
 
533
577
   This filter is used as follows in the default :setting:`LOGGING`