--- a/django-hoptoad/config/index.html Sun Jan 10 18:18:04 2010 -0500
+++ b/django-hoptoad/config/index.html Wed Jan 20 20:38:19 2010 -0500
@@ -50,6 +50,15 @@
<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="#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>
@@ -118,6 +127,75 @@
</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="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>