| author |
Steve Losh <steve@stevelosh.com> |
| date |
Tue, 10 Apr 2012 10:16:30 -0400 |
| parents |
50444dfe7265 |
| children |
(none) |
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<title>
django-hoptoad »
Configuration
</title>
<link rel="stylesheet" type="text/css" href="../media/css/reset.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="../media/css/layout.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="../media/css/typography.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="../media/css/pygments.css" media="screen, projection" />
</head>
<body >
<div id="content">
<div id="breadcrumbs">
<p>
<a href="../">index</a> »
config
</p>
</div> <!-- div#breadcrumbs -->
<h1 id="configuration">Configuration</h1>
<p>There are a few extra things you can configure if you'd like to tweak the notification process a bit.</p>
<div class="toc">
<ul>
<li><a href="#configuration">Configuration</a><ul>
<li><a href="#notify-hoptoad-while-in-debug-mode">Notify Hoptoad While in DEBUG Mode</a></li>
<li><a href="#specify-an-environment-name">Specify an Environment Name</a></li>
<li><a href="#specify-a-default-timeout">Specify a Default Timeout</a></li>
<li><a href="#track-404-errors">Track 404 Errors</a></li>
<li><a href="#track-403-errors">Track 403 Errors</a></li>
<li><a href="#ignore-specific-user-agents">Ignore Specific User Agents</a></li>
<li><a href="#use-ssl-to-post-to-hoptoad">Use SSL to POST to Hoptoad</a></li>
<li><a href="#hide-sensitive-request-parameters">Hide Sensitive Request Parameters</a></li>
<li><a href="#asynchronous-posts-and-request-handlers">Asynchronous POSTs and Request Handlers</a><ul>
<li><a href="#threadpool">"threadpool"</a></li>
<li><a href="#blocking">"blocking"</a></li>
</ul>
</li>
<li><a href="#writing-and-using-custom-handlers">Writing and Using Custom Handlers</a></li>
<li><a href="#change-the-hoptoad-notification-url">Change the Hoptoad Notification URL</a></li>
<li><a href="#group-django-hoptoad-settings">Group django-hoptoad Settings</a></li>
<li><a href="#problems">Problems?</a></li>
</ul>
</li>
</ul>
</div>
<h2 id="notify-hoptoad-while-in-debug-mode">Notify Hoptoad While in DEBUG Mode</h2>
<p>By default the Middleware will <strong>not</strong> report errors to Hoptoad when your project is in <code>DEBUG</code> 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 <code>DEBUG</code> mode, add the following setting:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_NOTIFY_WHILE_DEBUG</span> <span class="o">=</span> <span class="n">True</span>
</pre></div>
<h2 id="specify-an-environment-name">Specify an Environment Name</h2>
<p>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 <code>settings.py</code> per environment, you can set this quite simply:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_ENV_NAME</span> <span class="o">=</span> <span class="s">'Production'</span>
</pre></div>
<p>If you have a single <code>settings.py</code> 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:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_ENV_NAME</span> <span class="o">=</span> <span class="s">'Test'</span> <span class="k">if</span> <span class="n">DEBUG</span> <span class="k">else</span> <span class="s">'Production'</span>
</pre></div>
<p>Or:</p>
<div class="codehilite"><pre><span class="nb">import</span> <span class="n">platform</span>
<span class="n">HOPTOAD_ENV_NAME</span> <span class="o">=</span> <span class="n">platform</span><span class="o">.</span><span class="n">node</span><span class="p">()</span>
</pre></div>
<p>If <code>HOPTOAD_ENV_NAME</code> is not set, the Middleware by default will send the environment name as 'Unknown'.</p>
<h2 id="specify-a-default-timeout">Specify a Default Timeout</h2>
<p>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 <a href="http://docs.python.org/library/urllib2.html">documentation</a> does not see fit to explain that to me.</p>
<p>If you'd like to change that amount you can use the <code>HOPTOAD_TIMEOUT</code> setting. You <strong>must</strong> be running Python 2.6+ to use this.</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_TIMEOUT</span> <span class="o">=</span> <span class="mi">5</span>
</pre></div>
<p>The number is the number of seconds the notifier will wait before timing out. Yes, you can use a float like <code>0.5</code> to specify fractions of a second.</p>
<h2 id="track-404-errors">Track 404 Errors</h2>
<p>By default Hoptoad will <strong>not</strong> be notified of 404 (page not found) errors. If you'd like to change this you'll need to add the following setting:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_NOTIFY_404</span> <span class="o">=</span> <span class="n">True</span>
</pre></div>
<p><strong>IMPORTANT</strong>: If you are using Django's <code>flatpages</code> app and want to track 404 errors, you need to make sure the <code>FlatpageFallbackMiddleware</code> comes <em>after</em> the <code>HoptoadNotifierMiddleware</code>. If you don't do this Hoptoad will be notified of 404 errors even if the user actually sees a Flatpage.</p>
<p>To track 404s while using the <code>flatpages</code> app your <code>MIDDLEWARE_CLASSES</code> setting should look like this:</p>
<div class="codehilite"><pre><span class="n">MIDDLEWARE_CLASSES</span> <span class="o">=</span> <span class="p">(</span>
<span class="c1"># ... other middleware classes ...</span>
<span class="s">'hoptoad.middleware.HoptoadNotifierMiddleware'</span><span class="p">,</span>
<span class="s">'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
<p>A couple of things to note:</p>
<ul>
<li>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.</li>
<li>At the moment all 404 errors are grouped together as "similar" errors in Hoptoad. I am trying to figure out what causes this.</li>
</ul>
<h2 id="track-403-errors">Track 403 Errors</h2>
<p>By default Hoptoad will <strong>not</strong> be notified of 403 (forbidden) errors. If you'd like to change this you'll need to add the following setting:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_NOTIFY_403</span> <span class="o">=</span> <span class="n">True</span>
</pre></div>
<p>Note:</p>
<ul>
<li>At the moment all 403 errors are grouped together as "similar" errors in Hoptoad. I am trying to figure out what causes this.</li>
</ul>
<h2 id="ignore-specific-user-agents">Ignore Specific User Agents</h2>
<p>If you'd like to ignore all errors from certain User Agents you can use the following setting:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_IGNORE_AGENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'MSIE 6.0'</span><span class="p">,</span> <span class="s">'Trident'</span><span class="p">]</span>
</pre></div>
<p>If any of the strings in the list appear <em>anywhere</em> in the User Agent string, Hoptoad will not be notified of the error.</p>
<p>The strings are actually regular expressions, so you can be more specific if you like:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_IGNORE_AGENTS</span> <span class="o">=</span> <span class="p">[</span><span class="n">r</span><span class="s">'^Mozilla.*compatible; MSIE \d+\.\d+.*$'</span><span class="p">]</span>
</pre></div>
<p>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 <em>lot</em> of errors that you probably don't care about.</p>
<p>This would probably be a good starting point for ignoring crawlers:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_IGNORE_AGENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'Googlebot'</span><span class="p">,</span> <span class="s">'Yahoo! Slurp'</span><span class="p">,</span> <span class="s">'YahooSeeker'</span><span class="p">]</span>
</pre></div>
<h2 id="use-ssl-to-post-to-hoptoad">Use SSL to POST to Hoptoad</h2>
<p>If you want to use SSL (and your account plan supports it) you can use the following setting to enable SSL POSTs:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_USE_SSL</span> <span class="o">=</span> <span class="n">True</span>
</pre></div>
<p>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 <code>402</code> 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:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_NO_SSL_FALLBACK</span> <span class="o">=</span> <span class="n">True</span>
</pre></div>
<p>This will force a fallback to a non-SSL HTTP post to Hoptoad if the SSL post fails.</p>
<h2 id="hide-sensitive-request-parameters">Hide Sensitive Request Parameters</h2>
<p>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:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_PROTECTED_PARAMS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'credit_card_number'</span><span class="p">,</span> <span class="s">'ssn'</span><span class="p">]</span>
</pre></div>
<p>Any parameter in this list will have its contents replaced with
<code>********************</code> before it is sent to Hoptoad.</p>
<h2 id="asynchronous-posts-and-request-handlers">Asynchronous POSTs and Request Handlers</h2>
<p>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. </p>
<p>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:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_THREAD_COUNT</span> <span class="o">=</span> <span class="mi">2</span>
</pre></div>
<p>There is also built-in support for various other methods of communicating <strong>synchronously</strong> with Hoptoad:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_HANDLER</span> <span class="o">=</span> <span class="s">"blocking"</span>
</pre></div>
<p>This variable is set to "threadpool" by default. </p>
<p>There are a few handlers to choose from, (i.e. possible <code>HOPTOAD_HANDLER</code> settings):</p>
<h3 id="threadpool">"threadpool"</h3>
<p>This is the default setting. Will return a daemonized thread with a 4 worker-thread thread pool to handle all enqueued errors.</p>
<h3 id="blocking">"blocking"</h3>
<p>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.</p>
<p>Over time there will be more custom handlers with various options to control them.</p>
<h2 id="writing-and-using-custom-handlers">Writing and Using Custom Handlers</h2>
<p>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 <code>enqueue</code> method, which takes two parameters: <code>payload</code> and <code>timeout</code>. You'll also need to import the API that's needed to report.</p>
<p>For example:</p>
<div class="codehilite"><pre><span class="n">from</span> <span class="n">hoptoad</span><span class="o">.</span><span class="n">api</span> <span class="nb">import</span> <span class="n">htv2</span>
<span class="n">class</span> <span class="n">SomeAwesomeReporting</span><span class="p">(</span><span class="n">object</span><span class="p">):</span>
<span class="n">def</span> <span class="n">enqueue</span><span class="p">(</span><span class="n">self</span><span class="p">,</span> <span class="n">payload</span><span class="p">,</span> <span class="n">timeout</span><span class="p">):</span>
<span class="s">"""This enqueue method is your own implementation"""</span>
<span class="n">htv2</span><span class="o">.</span><span class="n">report</span><span class="p">(</span><span class="n">payload</span><span class="p">,</span> <span class="n">timeout</span><span class="p">)</span>
</pre></div>
<p>You'll need set two variables in <code>settings.py</code> to use your custom handler:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_HANDLER</span> <span class="o">=</span> <span class="s">"/path/to/the/custom/implementation.py"</span>
<span class="n">HOPTOAD_HANDLER_CLASS</span> <span class="o">=</span> <span class="s">"SomeAwesomeReport"</span>
</pre></div>
<p><code>HOPTOAD_HANDLER</code> is the file location to the module that contains your implementation of the custom handler and <code>HOPTOAD_HANDLER_CLASS</code> is the name of the actual handler class.</p>
<h2 id="change-the-hoptoad-notification-url">Change the Hoptoad Notification URL</h2>
<p>Currently Hoptoad has their notification API at <code>http://hoptoadapp.com/notifier_api/v2/notices</code>, 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):</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_NOTIFICATION_URL</span> <span class="o">=</span> <span class="s">"Hoptoad Notification URL here."</span>
</pre></div>
<p>This defaults to <code>http://hoptoadapp.com/notifier_api/v2/notices</code>.</p>
<h2 id="group-django-hoptoad-settings">Group django-hoptoad Settings</h2>
<p>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 <code>settings.py</code>, we've included support for grouping them in a dictionary. You can group them using <code>HOPTOAD_SETTINGS</code> as a dictionary:</p>
<div class="codehilite"><pre><span class="n">HOPTOAD_SETTINGS</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'HOPTOAD_API_KEY'</span> <span class="p">:</span> <span class="s">'abc12345...'</span>
<span class="s">'HOPTOAD_HANDLER'</span> <span class="p">:</span> <span class="s">'threadpool'</span><span class="p">,</span>
<span class="s">'HOPTOAD_THREAD_COUNT'</span> <span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
<span class="s">'HOPTOAD_USE_SSL'</span> <span class="p">:</span> <span class="n">True</span><span class="p">,</span>
<span class="c1"># ...</span>
<span class="p">}</span>
</pre></div>
<h2 id="problems">Problems?</h2>
<p>If you're having trouble you might want to take a look at the <a href="../troubleshooting/">Troubleshooting Guide</a>.</p>
<p id="footer">
django-hoptoad —
Powered by <a href="http://bitbucket.org/zacharyvoase/markdoc">Markdoc</a>.
</p>
</div> <!-- div#content -->
</body>
</html>