healthchecks_healthchecks/templates/docs/attaching_logs.html-fragment

<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 an arbitrary payload in the request body</strong>.
SITE_NAME will log the first PING_BODY_LIMIT_FORMATTED (PING_BODY_LIMIT bytes) of the
request body, so that you can inspect it later.</p>
<h2>Logging Command Output</h2>
<p>In this example, we run <code>certbot renew</code>, capture its output (both the stdout
and stderr streams), and submit the captured output to SITE_NAME:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot<span class="w"> </span>renew<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>--data-raw<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span><span class="w"> </span>PING_URL
</code></pre></div>

<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><code><span class="ch">#!/bin/sh</span>

<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot<span class="w"> </span>renew<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>--data-raw<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span><span class="w"> </span>PING_URL/<span class="nv">$?</span>
</code></pre></div>

<p>If the command produces a lot of output, you may run into the following error:</p>
<div class="highlight"><pre><span></span><code>/usr/bin/curl: Argument list too long
</code></pre></div>

<p>In that case, one workaround is to save the output to a temporary file,
then tell curl to send the file as the request body:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

/usr/bin/certbot<span class="w"> </span>renew<span class="w"> </span>&gt;<span class="w"> </span>/tmp/certbot-renew.log<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>--data-binary<span class="w"> </span>@/tmp/certbot-renew.log<span class="w"> </span>PING_URL/<span class="nv">$?</span>
</code></pre></div>

<h2>Using Runitor</h2>
<p><a href="https://github.com/bdd/runitor">Runitor</a> is a third-party utility that runs the
supplied command, captures its output and reports to SITE_NAME.
It also measures the execution time and retries HTTP requests on transient errors.
Best of all, the syntax is simple and clean:</p>
<div class="highlight"><pre><span></span><code>runitor<span class="w"> </span>-uuid<span class="w"> </span>your-uuid-here<span class="w"> </span>--<span class="w"> </span>/usr/bin/certbot<span class="w"> </span>renew
</code></pre></div>

<h2>Sending Logs Without Signalling Success or Failure</h2>
<p>You may sometimes want to log diagnostic information without altering the check's
current state. SITE_NAME provides the <a href="../http_api#log-uuid">/log endpoint</a> just for
that. When you send an HTTP POST request to this endpoint, SITE_NAME will log the event
and display it in check's "Events" section but will keep the check's state unchanged.</p>
<h2>Handling More Than PING_BODY_LIMIT_FORMATTED of Logs</h2>
<p>While SITE_NAME can store a small amount of logs in a pinch, it is not specifically
designed for that. If you run into the issue of logs getting cut off, consider
the following options:</p>
<ul>
<li>See if the logs can be made less verbose. For example, if you have a batch job
that outputs a line of text per item processed, perhaps it can output a summary with
the totals instead.</li>
<li>If the important content is usually at the end, submit the
<strong>last PING_BODY_LIMIT_FORMATTED</strong> instead of the first. Here is an example that
submits the last PING_BODY_LIMIT_FORMATTED of <code>dmesg</code> output:</li>
</ul>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>dmesg<span class="w"> </span><span class="p">|</span><span class="w"> </span>tail<span class="w"> </span>--bytes<span class="o">=</span>PING_BODY_LIMIT<span class="k">)</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>--data-raw<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span><span class="w"> </span>PING_URL
</code></pre></div>

<ul>
<li>Finally, if it is critical to capture the entire log output,
consider using a dedicated log aggregation service for capturing the logs.</li>
</ul>
<h2>Where to See Captured Logs</h2>
<p>In the check's details page, Events section, click on individual events to see
full event details, including the captured log information.</p>
<p><img alt="The Events section" src="IMG_URL/events.png" /></p>
<p>In the dialog that opens, use the "Download Original" link to download the request
body data, exactly as it was submitted to SITE_NAME:</p>
<p><img alt="The Ping Details dialog" src="IMG_URL/ping_details.png" /></p>