#summary A very brief overview of django-logging.
#labels Featured

= 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 
[http://docs.python.org/lib/module-logging.html built-in logging system],
so _django-logging_ was created to allow it to be easily used within Django
projects.

= 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
}}}

All you should then need to do is add the _django-logging_ middleware to your
Django project's settings file:

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

The order of 
[http://www.djangoproject.com/documentation/settings/#middleware-classes MIDDLEWARE_CLASSES]
is important: the _django-logging_ middleware *must* come before any other
middleware that encodes the response's content (such as GZipMiddleware).

As a security measure, the _django-logging_ middleware will only operate when
your IP address is in
[http://www.djangoproject.com/documentation/settings/#internal-ips INTERNAL_IPS]
*and* either:
  * `LOGGING_OUTPUT_ENABLED` is set to `True`; or
  * `LOGGING_OUTPUT_ENABLED` is undefined and [http://www.djangoproject.com/documentation/settings/#debug DEBUG] is set to `True`.
You'll therefore need to set these values within your [http://www.djangoproject.com/documentation/settings/ settings file] appropriately.

That's it!

= Usage =

_django-logging_ uses the standard Python
[http://docs.python.org/lib/module-logging.html 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:

  * [http://antonym.org/node/76 A real Python logging example]
  * [http://www.mechanicalcat.net/richard/log/Python/Simple_usage_of_Python_s_logging_module 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_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. ||

= 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.
  * Logging of all the SQL statements that get executed.
  * 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
[http://code.google.com/p/django-logging/issues/list issue tracker].

If you wish to email, my details are on my own site's
[http://www.nevett.org/contact contact page].