1. Steve Losh
  2. django-hoptoad


django-hoptoad / docs / wiki / config / index.mdown


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:


Specify a Default Timeout

By default, the amount of time the notifier will wait before giving up on contacting Hoptoad is Python's "global default timeout setting". I have no idea what that is because the documentation 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.


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.

Track 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:


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:

    # ... other middleware classes ...

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.

Track 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:



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

Ignore Specific User Agents

If you'd like to ignore all errors from certain User Agents you can use the following setting:


If any of the strings in the list appear anywhere in the User Agent string, Hoptoad will not be notified of the error.

The strings are actually regular expressions, so you can be more specific if you like:

HOPTOAD_IGNORE_AGENTS = [r'^Mozilla.*compatible; MSIE \d+\.\d+.*$']

One thing this is useful for (aside from hating on IE) is ignoring errors from web crawlers. Often bots will mangle URLs and if you're tracking 404 errors you'll see a lot of errors that you probably don't care about.

This would probably be a good starting point for ignoring crawlers:

HOPTOAD_IGNORE_AGENTS = ['Googlebot', 'Yahoo! Slurp', 'YahooSeeker']

Using SSL to POST to Hoptoad

If you desire to use SSL and your account plan supports it, then you can use the following setting to enable SSL POSTs:


This will force all HTTP requests to use SSL. There's always a possibility, due to either an account downgrade, or, an expiration of a SSL certificate that Hoptoad might return an error code of 402 on a POST. There is built-in support automatically to try to re-POST the same error message without using SSL. To enable this feature, just add this option as well:


This will force a fallback to a non-SSL HTTP post to Hoptoad.

Asynchronous POSTs and Request Handlers

On a highly trafficked website, there is a noticeable degree of a delay when POST'ing to hoptoad -- either due to error limitations, network instability, or other acts of God that can cause an HTTP request to slow down or fail. To fix this, django-hoptoad will spawn a daemon thread, by default, that will spawn a thread pool, with 4 threads, to queue up all errors for maximum throughput. However, this can be configured to your heart's content, including changing the notification handler completely.

To control the number of threads spawned per threadpool, you can set the following variable to your desired thread count per threadpool:


In django-hoptoad, this variable defaults to 4.

There is also built-in support for various other methods of communicating synchronously with Hoptoad, and that requires just one more setting:

HOPTOAD_HANDLER = "blocking"

This variable is set to "threadpool" by default.

There are a few handlers to choose from, (i.e. possible HOPTOAD_HANDLER settings):


This is the default setting. Will return a daemonized thread with a 4 worker-thread thread pool to handle all enqueued errors.


This will switch from the thread pool approach to a blocking HTTP POST where the entire Django process is halted until this blocking call returns.

Over time, there will be more custom handlers with various options to control them.

What if you do not want to use any of the default handlers, but instead, use your own proprietary system?

There is support for drop-in replacements of handlers so that you might write your own custom handler. It's actually quite simple. All that's needed is that you implement a class, that implements an enqueue method which takes two parameters, payload, and timeout. You also have to import the api that's needed to report.

For example, consider the following class below:

from hoptoad.api import htv2

class SomeAwesomeReporting(object):
    def enqueue(self, payload, timeout):
        """This enqueue method is your own implementation"""
        htv2.report(payload, timeout)

You would need to also to set two variables in settings.py:

HOPTOAD_HANDLER = "/path/to/the/custom/implementation.py"

As you can see, HOPTOAD_HANDLER is the file location to the implementation of the custom handler and HOPTOAD_HANDLER_CLASS is the name of the actual class that implements the enqueue method.

Hoptoad Notification URL

Currently, Hoptoad has their notification URLs pointed to http://hoptoadapp.com/notifier_api/v2/notices, but this has been the second time that this was changed. It, therefore, can be expected that this will change again, so it is configurable like so:

HOPTOAD_NOTIFICATION_URL = "Hoptoad Notification URL here."

This defaults to http://hoptoadapp.com/notifier_api/v2/notices.

Hoptoad Setting Groupings

As you've probably noticed, these hoptoad settings are getting to be extremely abundant, so in order to give you some organization support for your settings.py, we've included support for grouping them in a dictionary. You can group them using HOPTOAD_SETTINGS as a dictionary and django-hoptoad will have support for this:

        'HOPTOAD_API_KEY' : 'a3eer..'
        'HOPTOAD_HANDLER' : 'threadpool',
        'HOPTOAD_USE_SSL' : True,
        # etc, you get the point


If you're having trouble you might want to take a look at the Troubleshooting Guide.