Tweak navigation in docs, added "Docs > Reliability Tips" page (cc: #384)

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
 - Added /api/v1/checks/uuid/flips/ endpoint (#349)
 - In the cron expression dialog, show a human-friendly version of the expression
 - Indicate a started check with a progress spinner under status icon (#338)
+- Added "Docs > Reliability Tips" page
 
 ### Bug Fixes
 - Removing Pager Team integration, project appears to be discontinued

templates/docs/api.html

@@ -1,5 +1,5 @@
-<h1>API Reference</h1>
-<p>SITE_NAME REST API supports listing, creating, updating, pausing and deleting
+<h1>Management API</h1>
+<p>SITE_NAME Management API supports listing, creating, updating, pausing and deleting
 checks in user's account.</p>
 <h2>API Endpoints</h2>
 <table>
@@ -53,7 +53,7 @@ checks in user's account.</p>
 </tbody>
 </table>
 <h2>Authentication</h2>
-<p>Your requests to SITE_NAME REST API must authenticate using an
+<p>Your requests to SITE_NAME Management API must authenticate using an
 API key. Each project in your SITE_NAME account has separate API keys.
 There are no account-wide API keys. By default, a project on SITE_NAME doesn't have
 an API key. You can create read-write and read-only API keys in the

templates/docs/api.md

@@ -1,6 +1,6 @@
-# API Reference
+# Management API
 
-SITE_NAME REST API supports listing, creating, updating, pausing and deleting
+SITE_NAME Management API supports listing, creating, updating, pausing and deleting
 checks in user's account.
 
 ## API Endpoints
@@ -20,7 +20,7 @@ Endpoint Name                                         | Endpoint Address
 
 ## Authentication
 
-Your requests to SITE_NAME REST API must authenticate using an
+Your requests to SITE_NAME Management API must authenticate using an
 API key. Each project in your SITE_NAME account has separate API keys.
 There are no account-wide API keys. By default, a project on SITE_NAME doesn't have
 an API key. You can create read-write and read-only API keys in the

templates/docs/configuring_notifications.html

@@ -16,7 +16,8 @@ set up in each project separately.</p>
 <p>In the web interface, the list of checks shows a visual overview of which alerting
 methods are enabled for each check. You can click the icons to toggle them on and off:</p>
 <p><img alt="Integration icons in the checks list" src="IMG_URL/checks_integrations.png" /></p>
-<p>You can also toggle the integrations on and off when viewing an individual check:</p>
+<p>You can also toggle the integrations on and off when viewing an individual check by
+clicking on the "ON" / "OFF" labels:</p>
 <p><img alt="Integration on/off toggles in the check details page" src="IMG_URL/details_integrations.png" /></p>
 <h2>SMS and WhatsApp Monthly Quotas</h2>
 <p>SITE_NAME limits the maximum number of SMS and WhatsApp notifications an account

templates/docs/configuring_notifications.md

@@ -20,7 +20,8 @@ methods are enabled for each check. You can click the icons to toggle them on an
 
 ![Integration icons in the checks list](IMG_URL/checks_integrations.png)
 
-You can also toggle the integrations on and off when viewing an individual check:
+You can also toggle the integrations on and off when viewing an individual check by
+clicking on the "ON" / "OFF" labels:
 
 ![Integration on/off toggles in the check details page](IMG_URL/details_integrations.png)
 

templates/docs/http_api.html

@@ -1,6 +1,6 @@
-<h1>HTTP API</h1>
-<p>The SITE_NAME pinging API is used for submitting success, failure and job start
-signals from the monitored systems.</p>
+<h1>Pinging API</h1>
+<p>The SITE_NAME pinging API is used for submitting "start", "success" and "fail"
+signals ("pings") from the monitored systems.</p>
 <h2>General Notes</h2>
 <p>All ping endpoints support:</p>
 <ul>
@@ -14,7 +14,7 @@ If the request body looks like a UTF-8 string, SITE_NAME stores the request body
 </ul>
 <p>Successful responses will have the "200 OK" HTTP response status code and a short
 and simple string "OK" in the response body.</p>
-<h2>Signal Success ("ping")</h2>
+<h2>Send a "success" Signal</h2>
 <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}
 </code></pre></div>
 
@@ -40,7 +40,7 @@ OK
 </code></pre></div>
 
 
-<h2>Signal Failure</h2>
+<h2>Send a "fail" Signal</h2>
 <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}/fail
 </code></pre></div>
 
@@ -65,7 +65,7 @@ OK
 </code></pre></div>
 
 
-<h2>Signal a Start</h2>
+<h2>Send a "start" Signal</h2>
 <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}/start
 </code></pre></div>
 

templates/docs/http_api.md

@@ -1,7 +1,7 @@
-# HTTP API
+# Pinging API
 
-The SITE_NAME pinging API is used for submitting success, failure and job start
-signals from the monitored systems.
+The SITE_NAME pinging API is used for submitting "start", "success" and "fail"
+signals ("pings") from the monitored systems.
 
 ## General Notes
 
@@ -18,7 +18,7 @@ If the request body looks like a UTF-8 string, SITE_NAME stores the request body
 Successful responses will have the "200 OK" HTTP response status code and a short
 and simple string "OK" in the response body.
 
-## Signal Success ("ping")
+## Send a "success" Signal
 
 ```text
 HEAD|GET|POST PING_ENDPOINT{uuid}
@@ -47,7 +47,7 @@ Access-Control-Allow-Origin: *
 OK
 ```
 
-## Signal Failure
+## Send a "fail" Signal
 
 ```text
 HEAD|GET|POST PING_ENDPOINT{uuid}/fail
@@ -75,7 +75,7 @@ Access-Control-Allow-Origin: *
 OK
 ```
 
-## Signal a Start
+## Send a "start" Signal
 
 ```text
 HEAD|GET|POST PING_ENDPOINT{uuid}/start

templates/docs/reliability_tips.html

@@ -0,0 +1,32 @@
+<h1>Pinging Reliability Tips</h1>
+<p>Sending monitoring signals over public internet is inherently unreliable.
+HTTP requests can sometimes take excessively long or fail completely
+for a variety of reasons. Here are some general tips to make your monitoring
+code more robust.</p>
+<h2>Specify HTTP Request Timeout</h2>
+<p>Put a time limit on how long each ping is allowed to take. This is especially
+important when sending a "start" signal at the start of a job: you don't want
+a stuck ping prevent the actual job from running. Another case is a continuously
+running worker process which pings SITE_NAME after each completed item. A stuck
+request would block the whole process, so it is important to guard against.</p>
+<p>Specifying the timeout depends on the tool you use. curl, for example, has the
+<code>--max-time</code> (shorthand: <code>-m</code>) parameter:</p>
+<div class="highlight"><pre><span></span><code><span class="c1"># Send a HTTP, 10 second timeout:</span>
+curl -m <span class="m">10</span> PING_URL
+</code></pre></div>
+
+
+<h2>Use Retries</h2>
+<p>To minimize the amount of false alerts you get from SITE_NAME, instruct your HTTP
+client to retry failed requests several times.</p>
+<p>Specifying the retry policy depends on the tool you use. curl, for example, has the
+<code>--retry</code> parameter:</p>
+<div class="highlight"><pre><span></span><code><span class="c1"># Retry up to 5 times, uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...)</span>
+curl --retry <span class="m">5</span> PING_URL
+</code></pre></div>
+
+
+<h2>Handle Exceptions</h2>
+<p>Make sure you know how your HTTP client handles failed requests. For example,
+if you use a HTTP library which raises exceptions, decide if you want to
+catch the exceptions, or let them bubble up.</p>

templates/docs/reliability_tips.md

@@ -0,0 +1,41 @@
+# Pinging Reliability Tips
+
+Sending monitoring signals over public internet is inherently unreliable.
+HTTP requests can sometimes take excessively long or fail completely
+for a variety of reasons. Here are some general tips to make your monitoring
+code more robust.
+
+## Specify HTTP Request Timeout
+
+Put a time limit on how long each ping is allowed to take. This is especially
+important when sending a "start" signal at the start of a job: you don't want
+a stuck ping prevent the actual job from running. Another case is a continuously
+running worker process which pings SITE_NAME after each completed item. A stuck
+request would block the whole process, so it is important to guard against.
+
+Specifying the timeout depends on the tool you use. curl, for example, has the
+`--max-time` (shorthand: `-m`) parameter:
+
+```bash
+# Send a HTTP, 10 second timeout:
+curl -m 10 PING_URL
+```
+
+## Use Retries
+
+To minimize the amount of false alerts you get from SITE_NAME, instruct your HTTP
+client to retry failed requests several times.
+
+Specifying the retry policy depends on the tool you use. curl, for example, has the
+`--retry` parameter:
+
+```bash
+# Retry up to 5 times, uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...)
+curl --retry 5 PING_URL
+```
+
+## Handle Exceptions
+
+Make sure you know how your HTTP client handles failed requests. For example,
+if you use a HTTP library which raises exceptions, decide if you want to
+catch the exceptions, or let them bubble up.

templates/front/base_docs.html

@@ -7,18 +7,21 @@
     <div class="col-sm-3">
 
     <ul class="docs-nav">
-        <li class="nav-header">Monitoring</li>
+        <li class="nav-header">{% site_name %}</li>
         <li {% if section == "introduction" %} class="active"{% endif %}>
             <a href="{% url 'hc-docs' %}">Introduction</a>
         </li>
-        {% include "front/docs_nav_item.html" with slug="monitoring_cron_jobs" title="Monitoring cron jobs" %}
         {% include "front/docs_nav_item.html" with slug="configuring_checks" title="Configuring checks" %}
         {% include "front/docs_nav_item.html" with slug="configuring_notifications" title="Configuring notifications" %}
         {% include "front/docs_nav_item.html" with slug="projects_teams" title="Projects and teams" %}
 
+        <li class="nav-header">API</li>
+        {% include "front/docs_nav_item.html" with slug="http_api" title="Pinging API" %}
+        {% include "front/docs_nav_item.html" with slug="api" title="Management API" %}
+
         <li class="nav-header">Pinging Examples</li>
-        {% include "front/docs_nav_item.html" with slug="http_api" title="HTTP API" %}
-        {% include "front/docs_nav_item.html" with slug="bash" title="Shell Scripts" %}
+        {% include "front/docs_nav_item.html" with slug="reliability_tips" title="Reliability Tips" %}
+        {% include "front/docs_nav_item.html" with slug="bash" title="Shell scripts" %}
         {% include "front/docs_nav_item.html" with slug="python" title="Python" %}
         {% include "front/docs_nav_item.html" with slug="ruby" title="Ruby" %}
         {% include "front/docs_nav_item.html" with slug="php" title="PHP" %}
@@ -28,18 +31,18 @@
         {% include "front/docs_nav_item.html" with slug="email" title="Email" %}
 
         <li class="nav-header">Guides</li>
+        {% 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" %}
-        {% include "front/docs_nav_item.html" with slug="cloning_checks" title="Cloning Checks" %}
+        {% include "front/docs_nav_item.html" with slug="cloning_checks" title="Cloning checks" %}
         {% include "front/docs_nav_item.html" with slug="configuring_prometheus" title="Configuring Prometheus" %}
 
         <li class="nav-header">Developer Tools</li>
-        {% include "front/docs_nav_item.html" with slug="api" title="Management API" %}
         {% include "front/docs_nav_item.html" with slug="resources" title="Third-party resources" %}
 
-        <li class="nav-header">Cron</li>
-        <li><a href="{% url 'hc-docs-cron' %}">Cron Syntax Cheatsheet</a></li>
+        <li class="nav-header">Reference</li>
+        <li><a href="{% url 'hc-docs-cron' %}">Cron syntax cheatsheet</a></li>
     </ul>
 
     </div>