Configuration

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 an Environment Name

If your application is deployed in multiple places, an environment name distinguishes production servers from QA or staging servers, so you know which server the error was produced on. Hoptoad's API seems to accept any environment name, but typical examples would be 'Production', 'QA', 'Test', 'Development'. If you have one settings.py per environment, you can set this quite simply:

HOPTOAD_ENV_NAME = 'Production'

If you have a single settings.py shared between environments, you may want to set this in a more dynamic fashion. There's no limit (other than Python itself) on how to do this. For example:

HOPTOAD_ENV_NAME = 'Test' if DEBUG else 'Production'

Or:

import platform
HOPTOAD_ENV_NAME = platform.node()

If HOPTOAD_ENV_NAME is not set, the Middleware by default will send the environment name as 'Unknown'.

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.

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.

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:

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:

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:

HOPTOAD_NOTIFY_403 = True

Note:

Ignore Specific User Agents

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

HOPTOAD_IGNORE_AGENTS = ['MSIE 6.0', 'Trident']

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']

Use SSL to POST to Hoptoad

If you want to use SSL (and your account plan supports it) you can use the following setting to enable SSL POSTs:

HOPTOAD_USE_SSL = True

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:

HOPTOAD_NO_SSL_FALLBACK = True

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

Hide Sensitive Request Parameters

If a user submits important data (credit card numbers, for example) with a GET or POST request and an error occurs, that data will be passed along to Hoptoad. If you want to blank out the contents of certain parameters you can use this option:

HOPTOAD_PROTECTED_PARAMS = ['credit_card_number', 'ssn']

Any parameter in this list will have its contents replaced with ******************** before it is sent 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. It 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 change the number of threads spawned per threadpool from the default of 4, you can set the following variable to your desired thread count per threadpool:

HOPTOAD_THREAD_COUNT = 2

There is also built-in support for various other methods of communicating synchronously with Hoptoad:

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

"threadpool"

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

"blocking"

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.

Writing and Using Custom Handlers

There is support for drop-in replacements of handlers so that you can write your own. All you need to do is implement a class which implements an enqueue method, which takes two parameters: payload and timeout. You'll also need to import the API that's needed to report.

For example:

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'll need set two variables in settings.py to use your custom handler:

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

HOPTOAD_HANDLER is the file location to the module that contains your implementation of the custom handler and HOPTOAD_HANDLER_CLASS is the name of the actual handler class.

Change the Hoptoad Notification URL

Currently Hoptoad has their notification API at http://hoptoadapp.com/notifier_api/v2/notices, but this has been the second time that this was changed. It may change again, so it's configurable (in case you want to fix the problem before we have a chance to update django-hoptoad with the new URL):

HOPTOAD_NOTIFICATION_URL = "Hoptoad Notification URL here."

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

Group django-hoptoad Settings

As you've probably noticed, these django-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:

HOPTOAD_SETTINGS = { 
        'HOPTOAD_API_KEY' : 'abc12345...'
        'HOPTOAD_HANDLER' : 'threadpool',
        'HOPTOAD_THREAD_COUNT' : 2,
        'HOPTOAD_USE_SSL' : True,
        # ...
 }

Problems?

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