Added an example of capturing and submitting log output. Fixes #315

templates/docs/attaching_logs.html

@@ -0,0 +1,34 @@
+<h1>Attaching Logs</h1>
+<p>SITE_NAME ping endpoints accept HTTP HEAD, GET and POST request methods.</p>
+<p>When using HTTP POST, <strong>you can include arbitrary payload in the request body</strong>.
+If the request body looks like a UTF-8 string, SITE_NAME will log the first 10 kilobytes of
+the request body, so you can inspect it later.</p>
+<h2>Logging Command Output</h2>
+<p>In this example, we run <code>certbot renew</code>, capture its output, and submit
+the captured output to SITE_NAME:</p>
+<div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span>
+
+<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot renew <span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
+curl -fsS --retry <span class="m">3</span> -X POST --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span> PING_URL
+</pre></div>
+
+
+<h2>In Combination with the <code>/fail</code> Endpoint</h2>
+<p>We can extend the previous example and signal either success or failure
+depending on the exit code:</p>
+<div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span>
+
+<span class="nv">url</span><span class="o">=</span>PING_URL
+
+<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot renew <span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
+
+<span class="k">if</span> <span class="o">[</span> <span class="nv">$?</span> -ne <span class="m">0</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span> <span class="nv">url</span><span class="o">=</span><span class="nv">$url</span>/fail<span class="p">;</span> <span class="k">fi</span>
+curl -fsS --retry <span class="m">3</span> -X POST --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span> <span class="nv">$url</span>
+</pre></div>
+
+
+<h2>As One-Liner</h2>
+<p>Finally, all of the above can be packaged in a single line. The one-line
+version can be put directly in crontab, without using a wrapper script.</p>
+<div class="highlight"><pre><span></span><span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot renew <span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span><span class="p">;</span> curl -fsS -X POST --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span> <span class="s2">&quot;PING_URL</span><span class="k">$(</span><span class="o">[</span> <span class="nv">$?</span> -ne <span class="m">0</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nb">echo</span> -n /fail<span class="k">)</span><span class="s2">&quot;</span>
+</pre></div>

templates/docs/attaching_logs.md

@@ -0,0 +1,44 @@
+# Attaching Logs
+
+SITE_NAME ping endpoints accept HTTP HEAD, GET and POST request methods.
+
+When using HTTP POST, **you can include arbitrary payload in the request body**.
+If the request body looks like a UTF-8 string, SITE_NAME will log the first 10 kilobytes of
+the request body, so you can inspect it later.
+
+## Logging Command Output
+
+In this example, we run `certbot renew`, capture its output, and submit
+the captured output to SITE_NAME:
+
+```bash
+#!/bin/sh
+
+m=$(/usr/bin/certbot renew 2>&1)
+curl -fsS --retry 3 -X POST --data-raw "$m" PING_URL
+```
+
+## In Combination with the `/fail` Endpoint
+
+We can extend the previous example and signal either success or failure
+depending on the exit code:
+
+```bash
+#!/bin/sh
+
+url=PING_URL
+
+m=$(/usr/bin/certbot renew 2>&1)
+
+if [ $? -ne 0 ]; then url=$url/fail; fi
+curl -fsS --retry 3 -X POST --data-raw "$m" $url
+```
+
+## As One-Liner
+
+Finally, all of the above can be packaged in a single line. The one-line
+version can be put directly in crontab, without using a wrapper script.
+
+```bash
+m=$(/usr/bin/certbot renew 2>&1); curl -fsS -X POST --data-raw "$m" "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
+```

templates/docs/signalling_failures.html

@@ -3,6 +3,7 @@
 Requesting the <code>/fail</code> URL will immediately mark the check as "down".
 You can use this feature to minimize the delay from your monitored service failing
 to you getting a notification.</p>
+<h2>Python</h2>
 <p>Below is a skeleton code example in Python which signals a failure when the
 work function returns an unexpected value or throws an exception:</p>
 <div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>

templates/docs/signalling_failures.md

@@ -5,6 +5,8 @@ Requesting the `/fail` URL will immediately mark the check as "down".
 You can use this feature to minimize the delay from your monitored service failing
 to you getting a notification.
 
+## Python
+
 Below is a skeleton code example in Python which signals a failure when the
 work function returns an unexpected value or throws an exception:
 

templates/front/base_docs.html

@@ -14,6 +14,7 @@
         {% include "front/docs_nav_item.html" with slug="monitoring_cron_jobs" title="Monitoring cron jobs" %}
         {% include "front/docs_nav_item.html" with slug="signalling_failures" title="Signalling failures" %}
         {% include "front/docs_nav_item.html" with slug="measuring_script_run_time" title="Measuring script run time" %}
+        {% include "front/docs_nav_item.html" with slug="attaching_logs" title="Attaching logs" %}
 
         <li class="nav-header">Platforms</li>
         {% include "front/docs_nav_item.html" with slug="bash" title="Bash" %}