From 464d05c99fbe39ddf6df35fd9ae95c748f0c2606 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Thu, 31 May 2018 14:28:28 +0300 Subject: [PATCH] "Signalling a Failure" section in docs. (cc: #151) --- hc/front/management/commands/pygmentize.py | 1 + templates/front/docs.html | 35 +++++++++++++++---- .../front/snippets/python_requests_fail.html | 17 +++++++++ .../front/snippets/python_requests_fail.txt | 16 +++++++++ 4 files changed, 62 insertions(+), 7 deletions(-) create mode 100644 templates/front/snippets/python_requests_fail.html create mode 100644 templates/front/snippets/python_requests_fail.txt diff --git a/hc/front/management/commands/pygmentize.py b/hc/front/management/commands/pygmentize.py index 4de60672..44ce0356 100644 --- a/hc/front/management/commands/pygmentize.py +++ b/hc/front/management/commands/pygmentize.py @@ -34,6 +34,7 @@ class Command(BaseCommand): _process("node", lexers.JavascriptLexer()) _process("python_urllib2", lexers.PythonLexer()) _process("python_requests", lexers.PythonLexer()) + _process("python_requests_fail", lexers.PythonLexer()) _process("php", lexers.PhpLexer()) _process("powershell", lexers.shell.PowerShellLexer()) _process("powershell_inline", lexers.shell.BashLexer()) diff --git a/templates/front/docs.html b/templates/front/docs.html index be8add19..5cf6a4e6 100644 --- a/templates/front/docs.html +++ b/templates/front/docs.html @@ -15,11 +15,18 @@

Summary

Each check in My Checks -page has an unique "ping" URL. Whenever you access this URL, -the "Last Ping" value of corresponding check is updated. +page has a unique "ping" URL. Whenever you make a HTTP request to this URL, +{% site_name %} records the request and updates the "Last Ping" value of +the corresponding check.

-

When a certain amount of time passes since last received ping, the -check is considered "late", and {% site_name %} sends an email alert. + +

When a certain, configurable amount of time passes since last received ping, +the check is considered "late". {% site_name %} then +waits for additional time (configured with the "Grace Time" parameter) and, +if still no ping, sends you an alert.

+ +

As long as the monitored service sends pings on time, you receive no +alerts. As soon as it fails to check in on time, you get notified. It is a simple idea.

Executing a Ping

@@ -28,18 +35,32 @@ It is a simple idea.

your ping URL.

The response will have status code "200 OK" and response body will be a short and simple string "OK".

+

Signalling a Failure

- Here are examples of executing pings from different environments. + Append /fail to a ping URL and use it to actively signal a + failure. 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.

+

Below is a skeleton code example in Python which signals a failure when the +work function returns an unexpected value or throws an exception:

+ +{% include "front/snippets/python_requests_fail.html" %}

Crontab

diff --git a/templates/front/snippets/python_requests_fail.html b/templates/front/snippets/python_requests_fail.html new file mode 100644 index 00000000..748bcc00 --- /dev/null +++ b/templates/front/snippets/python_requests_fail.html @@ -0,0 +1,17 @@ +
import requests
+URL = "{{ ping_url }}"
+
+def do_work():
+    # Do actual work here.
+    # Return a truthy value on success.
+    # Return a falsy value or throw an exception on failure.
+    return True
+
+success = False
+try:
+    success = do_work()
+finally:
+    # On success, requests {{ ping_url }}
+    # On failure, requests {{ ping_url }}/fail
+    requests.get(URL if success else URL + "/fail")
+
diff --git a/templates/front/snippets/python_requests_fail.txt b/templates/front/snippets/python_requests_fail.txt new file mode 100644 index 00000000..e85d5e4f --- /dev/null +++ b/templates/front/snippets/python_requests_fail.txt @@ -0,0 +1,16 @@ +import requests +URL = "PING_URL" + +def do_work(): + # Do actual work here. + # Return a truthy value on success. + # Return a falsy value or throw an exception on failure. + return True + +success = False +try: + success = do_work() +finally: + # On success, requests PING_URL + # On failure, requests PING_URL/fail + requests.get(URL if success else URL + "/fail")