NewsBlur-viq/utils/djangologging/docs/Overview.wiki

#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.

=== 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 [http://ericholscher.com/blog/2008/aug/29/screencast-2-logging-fun-and-profit/ nice screencast] which includes a brief demonstration of _django-logging_ in action.

[http://ericholscher.com/blog/2008/aug/29/screencast-2-logging-fun-and-profit/ http://images.vimeo.com/12/59/94/125994988/125994988_100x75.jpg]

= 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 
[http://docs.djangoproject.com/en/dev/ref/settings/#middleware-classes 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 [http://docs.djangoproject.com/en/dev/ref/settings/#internal-ips 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 [http://docs.djangoproject.com/en/dev/ref/settings/#debug 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
[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_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 [http://pygments.org/ 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
[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].