Browse Source

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

pull/395/head
Pēteris Caune 4 years ago
parent
commit
27a91bfe22
No known key found for this signature in database GPG Key ID: E28D7679E9A9EDE2
  1. 1
      CHANGELOG.md
  2. 6
      templates/docs/api.html
  3. 6
      templates/docs/api.md
  4. 3
      templates/docs/configuring_notifications.html
  5. 3
      templates/docs/configuring_notifications.md
  6. 12
      templates/docs/http_api.html
  7. 12
      templates/docs/http_api.md
  8. 32
      templates/docs/reliability_tips.html
  9. 41
      templates/docs/reliability_tips.md
  10. 19
      templates/front/base_docs.html

1
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

6
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

6
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

3
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

3
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)

12
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>

12
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

32
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>

41
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.

19
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>

Loading…
Cancel
Save