nielsperetzke
/
healthchecks


								{% extends "front/base_docs.html" %}

								{% load staticfiles %}


								{% block title %}Documentation - healthchecks.io{% endblock %}


								{% block docs_content %}


								<h2>Summary</h2>

								<p>

								Each check in <a href="{% url 'hc-index' %}">My Checks</a>

								page has an unique "ping" URL. Whenever you access this URL,

								the "Last Ping" value of corresponding check is updated.

								</p>

								<p>When a certain amount of time passes since last received ping, the

								check is considered "late", and healthchecks.io sends an email alert.

								It is a simple idea.</p>


								<h2>Executing a Ping</h2>

								<p>

								    At the end of your batch job, add a bit of code to request

								    your ping URL.

								</p>

								<ul>

								    <li>HTTP and HTTPS protocols both are fine</li>

								    <li>Request method can be GET, POST or HEAD</li>

								    <li>Both IPv4 and IPv6 work</li>

								    <li>It does not matter what request headers you send, or what you put in request body.</li>

								</ul>


								<p>The response will have status code "200 OK" and response body will be a

								short and simple string "OK".</p>


								<p>

								    Here are examples of executing pings from different environments.

								</p>


								<a name="crontab"></a>

								<h3>Crontab</h3>


								<p>

								When using cron, probably the easiest is to append a curl

								or wget call after your command. The scheduled time comes,

								and your command runs. If it completes successfully (exit code 0),

								curl or wget runs a HTTP GET call to the ping URL.

								</p>


								{% include "front/snippets/crontab.html" %}


								<p>With this simple modification, you monitor several failure

								scenarios:</p>


								<ul>

								    <li>The whole machine has stopped working (power outage, janitor stumbles on wires, VPS provider problems, etc.) </li>

								    <li>cron daemon is not running, or has invalid configuration</li>

								    <li>cron does start your task, but the task exits with non-zero exit code</li>

								</ul>


								<p>Either way, when your task doesn't finish successfully, you will soon

								know about it.</p>


								<p>The extra options to curl are meant to suppress any output, unless it hits

								an error. This is to prevent cron from sending an email every time the

								task runs. Feel free to adjust the curl options to your liking.

								</p>

								<table class="table curl-opts">

								    <tr>

								        <th>&amp;&amp;</th>

								        <td>Run curl only if <code>/home/user/backup.sh</code> succeeds</td>

								    </tr>

								    <tr>

								        <th>

								            -f,  --fail

								        </th>

								        <td>Makes curl treat non-200 responses as errors</td>

								    </tr>

								    <tr>

								        <th>-s, --silent</th>

								        <td>Silent or quiet mode. Don't show progress meter or error messages.</td>

								    </tr>

								    <tr>

								        <th>-S, --show-error</th>

								        <td>When used with -s it makes curl show error message if it fails.</td>

								    </tr>

								    <tr>

								        <th>--retry &lt;num&gt;</th>

								        <td>

								            If a transient error is returned when curl tries to perform a

								            transfer, it will retry this number of times before  giving  up.

								            Setting  the number  to  0  makes curl do no retries

								            (which is the default). Transient error means either: a timeout,

								            an FTP 4xx response code or an HTTP 5xx response code.

								        </td>

								    </tr>

								    <tr>

								        <th>&gt; /dev/null</th>

								        <td>

								            Redirect curl's stdout to /dev/null (error messages go to stderr,)

								        </td>

								    </tr>

								</table>


								<a name="bash"></a>

								<h3>Bash or a shell script</h3>


								<p>Both <code>curl</code> and <code>wget</code> examples accomplish the same

								thing: they fire off a HTTP GET method.</p>


								<p>

								    If using <code>curl</code>, make sure it is installed on your target system.

								    Ubuntu, for example, does not have curl installed out of the box.

								</p>


								{% include "front/snippets/bash.html" %}


								<a name="python"></a>

								<h3>Python</h3>

								{% include "front/snippets/python.html" %}


								<a name="node"></a>

								<h3>Node</h3>

								{% include "front/snippets/node.html" %}


								<a name="php"></a>

								<h3>PHP</h3>

								{% include "front/snippets/php.html" %}


								<a name="browser"></a>

								<h3>Browser</h3>

								<p>

								    healthchecks.io includes <code>Access-Control-Allow-Origin:*</code>

								    CORS header in its ping responses, so cross-domain AJAX requests

								    should work.

								</p>

								{% include "front/snippets/browser.html" %}


								<a name="email"></a>

								<h3>Email</h3>

								<p>

								    As an alternative to HTTP/HTTPS requests,

								    you can "ping" this check by sending an

								    email message to <a href="mailto:{{ check.email }}">{{ check.email }}</a>

								</p>

								<p>

								    This is useful for end-to-end testing weekly email delivery.

								</p>

								<p>

								    An example scenario: you have a cron job which runs weekly and

								    sends weekly email reports to a list of e-mail addresses. You have already

								    set up a check to get alerted when your cron job fails to run.

								    But what you ultimately want to check is your emails <em>get sent and

								    get delivered</em>.

								</p>

								<p>

								    The solution: set up another check, and add its

								    @hchk.io address to your list of recipient email addresses. Set its

								    Period to 1 week. As long as your weekly email script runs correctly,

								    the check will be regularly pinged and will stay up.

								</p>


								<h2>When Alerts Are Sent</h2>

								<p>

								    Each check has a configurable <strong>Period</strong> parameter, with the default value of one day.

								    For periodic tasks, this is the expected time gap between two runs.

								</p>

								<p>

								    Additionally, each check has a <strong>Grace</strong> parameter, with default value of one hour.

								    You can use this parameter to account for run time variance of tasks.

								    For example, if a backup task completes in 50 seconds one day, and

								    completes in 60 seconds the following day, you might not want to get

								    alerted because the backups are 10 seconds late.

								</p>

								<p>Each check can be in one of the following states:</p>


								<table class="table">

								    <tr>

								        <td>

								            <span class="glyphicon glyphicon-question-sign new"></span>

								        </td>

								        <td>

								            <strong>New.</strong>

								            A check that has been created, but has not received any pings yet.

								        </td>

								    </tr>

								    <tr>

								        <td>

								            <span class="glyphicon glyphicon-ok-sign up"></span>

								        </td>

								        <td>

								            <strong>Up.</strong>

								            Time since last ping has not exceeded <strong>Period</strong>.

								        </td>

								    </tr>

								    <tr>

								        <td>

								            <span class="glyphicon glyphicon-exclamation-sign grace"></span>

								        </td>

								        <td>

								            <strong>Late.</strong>

								            Time since last ping has exceeded <strong>Period</strong>,

								            but has not yet exceeded <strong>Period</strong> + <strong>Grace</strong>.

								        </td>

								    </tr>

								    <tr>

								        <td>

								            <span class="glyphicon glyphicon-exclamation-sign down"></span>

								        </td>

								        <td>

								            <strong>Down.</strong>

								            Time since last ping has exceeded <strong>Period</strong> + <strong>Grace</strong>.

								            When check goes from "Late" to "Down", healthchecks.io

								            sends you an alert.

								        </td>

								    </tr>

								</table>


								{% endblock %}