The cast of players¶

A Python logging configuration consists of four parts:

• Loggers
• Handlers
• Filters
• Formatters

Naming loggers¶

The call tologging.getLogger() obtains (creating, ifnecessary) an instance of a logger. The logger instance is identifiedby a name. This name is used to identify the logger for configurationpurposes.

By convention, the logger name is usually__name__, the name ofthe python module that contains the logger. This allows you to filterand handle logging calls on a per-module basis. However, if you havesome other way of organizing your logging messages, you can provideany dot-separated name to identify your logger:

# Get an instance of a specific named loggerlogger=logging.getLogger('project.interesting.stuff')

The dotted paths of logger names define a hierarchy. Theproject.interesting logger is considered to be a parent of theproject.interesting.stuff logger; theproject loggeris a parent of theproject.interesting logger.

Why is the hierarchy important? Well, because loggers can be set topropagate their logging calls to their parents. In this way, you candefine a single set of handlers at the root of a logger tree, andcapture all logging calls in the subtree of loggers. A logging handlerdefined in theproject namespace will catch all logging messagesissued on theproject.interesting andproject.interesting.stuff loggers.

This propagation can be controlled on a per-logger basis. Ifyou don’t want a particular logger to propagate to its parents, youcan turn off this behavior.

Making logging calls¶

The logger instance contains an entry method for each of the defaultlog levels:

• logger.debug()
• logger.info()
• logger.warning()
• logger.error()
• logger.critical()

There are two other logging calls available:

• logger.log(): Manually emits a logging message with aspecific log level.
• logger.exception(): Creates anERROR level loggingmessage wrapping the current exception stack frame.

Examples¶

The full documentation fordictConfig formatis the best source of information about logging configuration dictionaries.However, to give you a taste of what is possible, here are several examples.

First, here’s a simple configuration which writes all logging from thedjango logger to a local file:

LOGGING={'version':1,'disable_existing_loggers':False,'handlers':{'file':{'level':'DEBUG','class':'logging.FileHandler','filename':'/path/to/django/debug.log',},},'loggers':{'django':{'handlers':['file'],'level':'DEBUG','propagate':True,},},}

If you use this example, be sure to change the'filename' path to alocation that’s writable by the user that’s running the Django application.

Second, here’s an example of how to make the logging system print Django’slogging to the console. It may be useful during local development.

By default, this config only sends messages of levelINFO or higher to theconsole (same as Django’s default logging config, except that the default onlydisplays log records whenDEBUG=True). Django does not log many suchmessages. With this config, however, you can also set the environment variableDJANGO_LOG_LEVEL=DEBUG to see all of Django’s debug logging which is veryverbose as it includes all database queries:

importosLOGGING={'version':1,'disable_existing_loggers':False,'handlers':{'console':{'class':'logging.StreamHandler',},},'loggers':{'django':{'handlers':['console'],'level':os.getenv('DJANGO_LOG_LEVEL','INFO'),},},}

Finally, here’s an example of a fairly complex logging setup:

LOGGING={'version':1,'disable_existing_loggers':False,'formatters':{'verbose':{'format':'%(levelname)s%(asctime)s%(module)s%(process)d%(thread)d%(message)s'},'simple':{'format':'%(levelname)s%(message)s'},},'filters':{'special':{'()':'project.logging.SpecialFilter','foo':'bar',},'require_debug_true':{'()':'django.utils.log.RequireDebugTrue',},},'handlers':{'console':{'level':'INFO','filters':['require_debug_true'],'class':'logging.StreamHandler','formatter':'simple'},'mail_admins':{'level':'ERROR','class':'django.utils.log.AdminEmailHandler','filters':['special']}},'loggers':{'django':{'handlers':['console'],'propagate':True,},'django.request':{'handlers':['mail_admins'],'level':'ERROR','propagate':False,},'myproject.custom':{'handlers':['console','mail_admins'],'level':'INFO','filters':['special']}}}

This logging configuration does the following things:

• Identifies the configuration as being in ‘dictConfig version 1’format. At present, this is the only dictConfig format version.

• Defines two formatters:

  • simple, that just outputs the log level name (e.g.,DEBUG) and the log message.

    Theformat string is a normal Python formatting stringdescribing the details that are to be output on each loggingline. The full list of detail that can be output can befound inFormatter Objects.

  • verbose, that outputs the log level name, the logmessage, plus the time, process, thread and module thatgenerate the log message.

• Defines two filters:

  • project.logging.SpecialFilter, using the aliasspecial. If thisfilter required additional arguments, they can be provided as additionalkeys in the filter configuration dictionary. In this case, the argumentfoo will be given a value ofbar when instantiatingSpecialFilter.
  • django.utils.log.RequireDebugTrue, which passes on records whenDEBUG isTrue.

• Defines two handlers:

  • console, aStreamHandler, which prints anyINFO(or higher) message tosys.stderr. This handler uses thesimpleoutput format.
  • mail_admins, anAdminEmailHandler, which emails anyERROR(or higher) message to the siteADMINS. This handler uses thespecial filter.

• Configures three loggers:

  • django, which passes all messages to theconsole handler.
  • django.request, which passes allERROR messages tothemail_admins handler. In addition, this logger ismarked tonot propagate messages. This means that logmessages written todjango.request will not be handledby thedjango logger.
  • myproject.custom, which passes all messages atINFOor higher that also pass thespecial filter to twohandlers – theconsole, andmail_admins. Thismeans that allINFO level messages (or higher) will beprinted to the console;ERROR andCRITICALmessages will also be output via email.

Custom logging configuration¶

If you don’t want to use Python’s dictConfig format to configure yourlogger, you can specify your own configuration scheme.

TheLOGGING_CONFIG setting defines the callable that willbe used to configure Django’s loggers. By default, it points atPython’slogging.config.dictConfig() function. However, if you want touse a different configuration process, you can use any other callablethat takes a single argument. The contents ofLOGGING willbe provided as the value of that argument when logging is configured.

Disabling logging configuration¶

If you don’t want to configure logging at all (or you want to manuallyconfigure logging using your own approach), you can setLOGGING_CONFIG toNone. This will disable theconfiguration process forDjango’s default logging. Here’s an example that disables Django’slogging configuration and then manually configures logging:

LOGGING_CONFIG=Noneimportlogging.configlogging.config.dictConfig(...)

SettingLOGGING_CONFIG toNone only means that the automaticconfiguration process is disabled, not logging itself. If you disable theconfiguration process, Django will still make logging calls, falling back towhatever default logging behavior is defined.

Loggers¶

Django provides several built-in loggers.

'handlers':{'null':{'class':'logging.NullHandler',},},'loggers':{'django.security.DisallowedHost':{'handlers':['null'],'propagate':False,},},

Handlers¶

Django provides one log handler in addition to those provided by thePython logging module.

classAdminEmailHandler(include_html=False,email_backend=None)[source]¶

This handler sends an email to the siteADMINS for each logmessage it receives.

If the log record contains arequest attribute, the full detailsof the request will be included in the email. The email subject willinclude the phrase “internal IP” if the client’s IP address is in theINTERNAL_IPS setting; if not, it will include “EXTERNAL IP”.

If the log record contains stack trace information, that stacktrace will be included in the email.

Theinclude_html argument ofAdminEmailHandler is used tocontrol whether the traceback email includes an HTML attachmentcontaining the full content of the debug Web page that would have beenproduced ifDEBUG wereTrue. To set this value in yourconfiguration, include it in the handler definition fordjango.utils.log.AdminEmailHandler, like this:

'handlers':{'mail_admins':{'level':'ERROR','class':'django.utils.log.AdminEmailHandler','include_html':True,}},

Note that this HTML version of the email contains a full traceback,with names and values of local variables at each level of the stack, plusthe values of your Django settings. This information is potentially verysensitive, and you may not want to send it over email. Consider usingsomething such asSentry to get the best of both worlds – therich information of full tracebacks plus the security ofnot sending theinformation over email. You may also explicitly designate certainsensitive information to be filtered out of error reports – learn more onFiltering error reports.

By setting theemail_backend argument ofAdminEmailHandler, theemail backend that is being used by thehandler can be overridden, like this:

'handlers':{'mail_admins':{'level':'ERROR','class':'django.utils.log.AdminEmailHandler','email_backend':'django.core.mail.backends.filebased.EmailBackend',}},

By default, an instance of the email backend specified inEMAIL_BACKEND will be used.

send_mail(subject,message,*args,**kwargs)[source]¶

Sends emails to admin users. To customize this behavior, you cansubclass theAdminEmailHandler class andoverride this method.

Filters¶

Django provides some log filters in addition to those provided by the Pythonlogging module.

classCallbackFilter(callback)[source]¶

This filter accepts a callback function (which should accept a singleargument, the record to be logged), and calls it for each record thatpasses through the filter. Handling of that record will not proceed if thecallback returns False.

For instance, to filter outUnreadablePostError(raised when a user cancels an upload) from the admin emails, you wouldcreate a filter function:

fromdjango.httpimportUnreadablePostErrordefskip_unreadable_post(record):ifrecord.exc_info:exc_type,exc_value=record.exc_info[:2]ifisinstance(exc_value,UnreadablePostError):returnFalsereturnTrue

and then add it to your logging config:

'filters':{'skip_unreadable_posts':{'()':'django.utils.log.CallbackFilter','callback':skip_unreadable_post,}},'handlers':{'mail_admins':{'level':'ERROR','filters':['skip_unreadable_posts'],'class':'django.utils.log.AdminEmailHandler'}},

classRequireDebugFalse[source]¶

This filter will only pass on records when settings.DEBUG is False.

This filter is used as follows in the defaultLOGGINGconfiguration to ensure that theAdminEmailHandler only sendserror emails to admins whenDEBUG isFalse:

'filters':{'require_debug_false':{'()':'django.utils.log.RequireDebugFalse',}},'handlers':{'mail_admins':{'level':'ERROR','filters':['require_debug_false'],'class':'django.utils.log.AdminEmailHandler'}},

classRequireDebugTrue[source]¶

This filter is similar toRequireDebugFalse, except that records arepassed only whenDEBUG isTrue.