Source

django-hoptoad /

Filename Size Date modified Message
hoptoad
30 B
1.0 KB
5.2 KB
-*- markdown -*-

django-hoptoad
==============

django-hoptoad is some simple Middleware for letting [Django][]-driven websites report their errors to [Hoptoad][].  Now [ponies][] can ride the toad too.

[Django]: http://djangoproject.com/
[Hoptoad]: http://hoptoadapp.com/
[ponies]: http://djangopony.com/

Requirements
------------

django-hoptoad requires:

* [Python][] 2.5+ (preferably 2.6+ as that's what I've tested it with)
* [PyYAML][] (`pip install pyyaml` or `easy_install pyyaml`)
* [Django][] 1.0+
* A [Hoptoad][] account

[Python]: http://python.org/
[PyYAML]: http://pyyaml.org/

Installation
------------

Grab the the django-hoptoad code by cloning the [Mercurial][] repository (or just [download the latest version][tip-dl] and unzip it somewhere):

    hg clone http://bitbucket.org/sjl/django-hoptoad/

Once you download it, symlink the module into your `site-packages` directory:

    ln -s /full/path/to/django-hoptoad/hoptoad /full/path/to/site-packages/

To make sure it works you can run:

    python -c 'import hoptoad'

[Mercurial]: http://mercurial.selenic.com/
[tip-dl]: http://bitbucket.org/sjl/django-hoptoad/get/tip.zip

Usage
-----

To set up a Django project to notify Hoptoad of its errors, you need to do two things in the `settings.py` file.

First, add the `HoptoadNotifierMiddleware` as the last item in your `MIDDLEWARE_CLASSES` setting:

    MIDDLEWARE_CLASSES = (
        # ... other middleware classes ...
        'hoptoad.middleware.HoptoadNotifierMiddleware',
    )

Next, you'll need to add a `HOPTOAD_API_KEY` setting.  You can get the key from the Hoptoad project page.

    HOPTOAD_API_KEY = 'Your Hoptoad API key.'

Optional Settings
-----------------

There are a few extra things you can configure if you'd like to tweak the notification process a bit.

### Notify Hoptoad While in DEBUG Mode

By default the Middleware will **not** report errors to Hoptoad when your project is in `DEBUG` mode.  The idea behind this is that if you can already see the error information right in the browser you probably don't need to see it in Hoptoad too.  If you want to always notify Hoptoad of errors, even while in `DEBUG` mode, add the following setting:

    HOPTOAD_NOTIFY_WHILE_DEBUG = True

### Specify a Default Timeout

The notification middleware will make sure the error notification gets to Hoptoad before the response gets sent back to the user.  If it takes a while to contact Hoptoad the user will notice a delay.

By default, the amount of time the notifier will wait before giving up is Python's "global default timeout setting".  I have no idea what that is because the [documentation][urllib2docs] does not see fit to explain that to me.

If you'd like to change that amount you can use the `HOPTOAD_TIMEOUT` setting.  You **must** be running Python 2.6+ to use this.

    HOPTOAD_TIMEOUT = 5

The number is the number of seconds the notifier will wait before timing out.  Yes, you can use a float like `0.5` to specify fractions of a second.

[urllib2docs]: http://docs.python.org/library/urllib2.html

### Tracking 404 Errors

By default Hoptoad will **not** be notified of 404 (page not found) errors.  If you'd like to change this you'll need to add the following setting:

    HOPTOAD_NOTIFY_404 = True

**IMPORTANT**: If you are using Django's `flatpages` app and want to track 404 errors, you need to make sure the `FlatpageFallbackMiddleware` comes *after* the `HoptoadNotifierMiddleware`.  If you don't do this Hoptoad will be notified of 404 errors even if the user actually sees a Flatpage.

To track 404s while using the `flatpages` app your `MIDDLEWARE_CLASSES` setting should look like this:

    MIDDLEWARE_CLASSES = (
        # ... other middleware classes ...
        'hoptoad.middleware.HoptoadNotifierMiddleware',
        'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware',
    )

A couple of things to note:

* If your website doesn't have a favicon specified most browsers will request it each time.  This will result in one (or possibly two, if it tries to append a slash) 404 errors for every page view.
* At the moment all 404 errors are grouped together as "similar" errors in Hoptoad.  I am trying to figure out what causes this.

### Tracking 403 Errors

By default Hoptoad will **not** be notified of 403 (forbidden) errors.  If you'd like to change this you'll need to add the following setting:

    HOPTOAD_NOTIFY_403 = True

Note:

* At the moment all 403 errors are grouped together as "similar" errors in Hoptoad.  I am trying to figure out what causes this.

Troubleshooting
---------------

If things don't go smoothly, the first thing to do is run the tests to see if they can determine what's wrong.  To enable the tests you'll need to add django-hoptoad to your `INSTALLED_APPS` setting:

    INSTALLED_APPS = (
        # ... other apps ...
        'hoptoad',
        # ... other apps ...
    )

Once you've done that you can run the unit tests:

    python manage.py test hoptoad

**NOTE**: The unit tests are very simple at the moment.  I'm working on more, but please feel free to submit ideas (or better yet: patches).

Suggestions
-----------

This Middleware is a work in progress.  If you have a suggestion or find a bug please [add an issue][issues] and let me know.

[issues]: http://bitbucket.org/sjl/django-hoptoad/issues/?status=new&status=open