summary A very brief overview of django-logging.

labels Featured

Important announcement

This project is no longer being maintained.

Unfortunately, I cannot commit the time needed to properly maintain django-logging, so have taken the decision to officially announce that it is no longer being supported. Should anyone wish to volunteer to adopt the project, please get in touch.

You can of course still checkout and use the latest version, but you may wish to look instead at the excellent Django Debug Toolbar.

Thanks to everyone who has given feedback, logged tickets and provided patches over the past few years!

Fraser

Introduction

It is really useful to know what your Django project is doing, especially when debugging.

If you're running Django via runserver, then you can simply use print statements and they will appear in the console. If you're running via mod_python, then you can output the print statements to the web server's error log by redirecting to stdout (print >>sys.stdout).

While useful, these both have their limitations. Python had a built-in logging system, so django-logging was created to allow it to be easily used within Django projects.

What's new

• 1 Jan 2009 - Added support for rewriting XHTML (and other) HTML-like pages
• 10 Sep 2008 - Made the new Profiling branch available
• 8 Sep 2008 - Added Pygments syntax highlighting and source code frame inspection
• 30 Aug 2008 - Eric Holscher has recently made a nice screencast which includes a brief demonstration of django-logging in action.

Installation

It's assumed that you have at least a basic knowledge of Django, Python and Subversion.

The source code for django-logging is stored in a Subversion repository, so to start with, you'll need to check out a copy, making sure that you put it somewhere on your PYTHONPATH:

svn co http://django-logging.googlecode.com/svn/trunk/djangologging/ djangologging

Step 1. Add the django-logging middleware to your Django project's settings file:

MIDDLEWARE_CLASSES = ( ... 'djangologging.middleware.LoggingMiddleware', ... )

The order of MIDDLEWARE_CLASSES is important: the django-logging middleware must come after any other middleware that encodes the response's content (such as GZipMiddleware).

Step 2. The django-logging middleware will only operate if your IP address is in the INTERNAL_IPS setting, so you will have to set this appropriately. If you're working locally, you may need to set this to something like:

INTERNAL_IPS = ('127.0.0.1',)

Step 3. As an additional security measure, the django-logging middleware will only add its output to HTML pages when: * LOGGING_OUTPUT_ENABLED is set to True; or * LOGGING_OUTPUT_ENABLED is undefined and DEBUG is set to True.

That's it! (See the Configuration section below for information on the various configurable options.)

Usage

django-logging uses the standard Python logging module, so simply import it and log whatever messages you like. For example:

``` import logging

logging.debug('This is a sample debug message') logging.info('This is a sample informational message') logging.warn('This is a sample warning message') logging.error('This is a sample error message') logging.critical('This is a sample critical message') ```

When you view a page in your browser, any log messages that were created during the processing of your request will appear at the bottom of the page.

One key feature of all this is that because this is using the standard logging framework, you can add other handlers to do other things, such as logging ERROR and CRITICAL level messages to a file. This could be expecially useful on a production server.

There are a number of sites which provide some useful information on using the logging module, including:

• A real Python logging example
• Simple usage of Python's logging module

How it works

A custom log handler is created that buffers all messages logged on a per-thread basis. This equates to a per-request basis within Django.

After the request has been processed and response generated, the middleware checks if the response is a HTML page (i.e. has a Content-Type header of text/html). If so, it writes the request's log messages into the HTML document. Extra HTTP headers are also added to indicate that the rewritten page should not be cached.

Note that unlike the built-in Django debug pages, django-logging does not sanitise any of the content; that is if you log any sensitve information (such as passwords), this will be displayed verbatim in clear text.

Configuration

django-logging should just work "out of the box", but you can configure the following options in your Django settings file:

| Variable | Default | Description | |:----------------------------------|:--------------------|:----------------| | LOGGING_INTERCEPT_REDIRECTS | False | Setting this to True will cause django-logging to intercept any HTTP redirects and output an interim page to allow you to see any messages that would have otherwise been lost. | | LOGGING_LOG_SQL | False | Setting this to True and having settings.DEBUG set to True will cause django-logging to log all SQL queries made through django.db.connection to be logged at a custom level, SQL. If installed, the Pygments syntax highlighter will be used to pretty print the SQL. | | LOGGING_OUTPUT_ENABLED | settings.DEBUG | Setting this to True will cause django-logging to be active and write the log data into outputted HTML pages. Setting this to False will prevent django-logging from outputting the log data. | | LOGGING_SHOW_METRICS | True | Setting this to True will cause django-logging calculate and display basic metric information, such as request duration and number of database queries. | | LOGGING_TEMPLATE_DIR | Auto determined | If you wish to use your own templates, set this to the full path to the directory containing your templates. This directory should contain your own versions of all the standard template files: logging.html, logging.css and redirect.html. | | LOGGING_REWRITE_CONTENT_TYPES | ('text/html',) | If you wish django-logging to add its output to responses with a Content-Type other than text/html, set this to a sequence of content type strings. For example, to enable rewriting of both HTML (Content-Type: text/html) and XHTML (Content-Type: application/xhtml+xml) pages, set this to ('text/html', 'application/xhtml+xml'). |

Output suppression

If there is a particular view that generates log messages that should not be appended to the page, you can use the suppress_logging_output decorator. For example:

``` from djangologging.decorators import suppress_logging_output

@suppress_logging_output def some_view(request): ... ```

If you're using AJAX to request a page, you may not wish django-logging to append its output to the response. Most Javascript libraries will add the X-Requested-With: XMLHttpRequest to AJAX requests, so you can use the SuppressLoggingOnAjaxRequestsMiddleware to stop log messages from being outputted. This middleware should be installed after the main logging middleware:

MIDDLEWARE_CLASSES = ( ... 'djangologging.middleware.LoggingMiddleware', 'djangologging.middleware.SuppressLoggingOnAjaxRequestsMiddleware', ... )

Future Features

Some things I'd like to add when I get the time:

• Ability to view the stack/frame information of each message in a similar way to the Django debug error page.
• Ability to view the messages from other loggers, not just the root logger.

Feedback

If you spot any bugs, have suggestions for improvement or ideas for future features, please use the issue tracker.

If you wish to email, my details are on my own site's contact page.