From f41c78e40f58212ca75c58b2d778940307dca4c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Thu, 23 Jan 2020 16:58:28 +0200 Subject: [PATCH] Serve the introduction page at /docs/ --- hc/front/urls.py | 2 +- hc/front/views.py | 15 +- templates/base.html | 2 +- templates/front/base_docs.html | 4 +- templates/front/docs.html | 368 --------------------------------- 5 files changed, 6 insertions(+), 385 deletions(-) delete mode 100644 templates/front/docs.html diff --git a/hc/front/urls.py b/hc/front/urls.py index 55142d5b..5cfee8aa 100644 --- a/hc/front/urls.py +++ b/hc/front/urls.py @@ -72,7 +72,7 @@ urlpatterns = [ path("projects//checks/status/", views.status, name="hc-status"), path("checks//", include(check_urls)), path("integrations/", include(channel_urls)), - path("docs/", views.docs, name="hc-docs"), + path("docs/", views.serve_doc, name="hc-docs"), path("docs/api/", views.docs_api, name="hc-docs-api"), path("docs/cron/", views.docs_cron, name="hc-docs-cron"), path("docs/resources/", views.docs_resources, name="hc-docs-resources"), diff --git a/hc/front/views.py b/hc/front/views.py index c34c53a8..2027daf5 100644 --- a/hc/front/views.py +++ b/hc/front/views.py @@ -264,20 +264,7 @@ def index(request): return render(request, "front/welcome.html", ctx) -def docs(request): - ctx = { - "page": "docs", - "section": "home", - "ping_endpoint": settings.PING_ENDPOINT, - "ping_email": "your-uuid-here@%s" % settings.PING_EMAIL_DOMAIN, - "ping_email_domain": settings.PING_EMAIL_DOMAIN, - "ping_url": settings.PING_ENDPOINT + "your-uuid-here", - } - - return render(request, "front/docs.html", ctx) - - -def serve_doc(request, doc): +def serve_doc(request, doc="introduction"): path = os.path.join(settings.BASE_DIR, "templates/docs", doc + ".html") if not os.path.exists(path): raise Http404("not found") diff --git a/templates/base.html b/templates/base.html index 9c460703..3cde5167 100644 --- a/templates/base.html +++ b/templates/base.html @@ -124,7 +124,7 @@ {% endif %}
  • - Docs + Docs
    • {% if request.user.is_authenticated %} diff --git a/templates/front/base_docs.html b/templates/front/base_docs.html index f923ab0c..2a727a2f 100644 --- a/templates/front/base_docs.html +++ b/templates/front/base_docs.html @@ -8,7 +8,9 @@
    • Monitoring
      • - {% include "front/docs_nav_item.html" with slug="introduction" title="Introduction" %} +
    • + Introduction +
      • {% 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" %} diff --git a/templates/front/docs.html b/templates/front/docs.html deleted file mode 100644 index 3f9903ab..00000000 --- a/templates/front/docs.html +++ /dev/null @@ -1,368 +0,0 @@ -{% extends "front/base_docs.html" %} -{% load compress static hc_extras %} - -{% block title %}Documentation - {% site_name %}{% endblock %} -{% block description %} - -{% endblock %} -{% block keywords %} - -{% endblock %} - - -{% block docs_content %} - -

      How {% site_name %} Works

      -

      -Each check in My Checks -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, 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.

      - -

      Signalling a Success

      - -

      - At the end of your batch job, add a bit of code to request - your ping URL. -

      -
        -
      • HTTP and HTTPS protocols both work. - Prefer HTTPS, but on old systems you may need to fall back to HTTP.
        • -
      • Request method can be GET, POST or HEAD
        • -
      • Both IPv4 and IPv6 work
        • -
      • - For HTTP POST requests, you can include additional diagnostic information - for your own reference in the request body. If the request body looks - like a UTF-8 string, {% site_name %} will log the first 10 kilobytes - of the request body, so you can inspect it later. -
        • -
      - -

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

      - - -

      Signalling a Failure

      -

      - 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" %} - - -

      Measuring Job Execution Time

      -

      - Append /start to a ping URL and use it to signal - when a job starts. After receiving a start signal, {% site_name %} - will show the check as "Started". It will store the "start" events and - display the job execution times. The job execution times are calculated as the time - gaps between adjacent "start" and "complete" events. -

      -

      - Signalling a start kicks off a separate timer: the job - now must signal a success within its configured - "Grace Time", or it will get marked as "down". -

      - -

      Below is a code example in Python:

      - -{% include "front/snippets/python_requests_start.html" %} - -

      Examples

      - -

      - Jump to example: - Crontab, - Bash, - Python, - Ruby, - Node, - PHP, - C#, - Browser, - PowerShell, - Email. -

      - - -

      Crontab

      - -

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

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

      With this simple modification, you monitor several failure -scenarios:

      - -
        -
      • The whole machine has stopped working (power outage, janitor stumbles on wires, VPS provider problems, etc.)
        • -
      • cron daemon is not running, or has invalid configuration
        • -
      • cron does start your task, but the task exits with non-zero exit code
        • -
      - -

      Either way, when your task doesn't finish successfully, you will soon -know about it.

      - -

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

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      &&Run curl only if /home/user/backup.sh succeeds
      - -f, --fail - Makes curl treat non-200 responses as errors
      -s, --silentSilent or quiet mode. Don't show progress meter or error messages.
      -S, --show-errorWhen used with -s it makes curl show error message if it fails.
      --retry <num> - 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. -
      > /dev/null - Redirect curl's stdout to /dev/null (error messages go to stderr,) -
      - - -

      Bash or a shell script

      - -

      Both curl and wget examples accomplish the same -thing: they fire off a HTTP GET method.

      - -

      - If using curl, make sure it is installed on your target system. - Ubuntu, for example, does not have curl installed out of the box. -

      - -{% include "front/snippets/bash_curl.html" %} -{% include "front/snippets/bash_wget.html" %} - - -

      Python

      - -

      - If you are already using the - requests library, - it's convenient to also use it here: -

      -{% include "front/snippets/python_requests.html" %} - -

      - Otherwise, you can use the urllib standard module. -

      - -{% include "front/snippets/python_urllib2.html" %} - -

      - You can include additional diagnostic information in the - in the request body (for POST requests), or in the "User-Agent" - request header: -

      - -{% include "front/snippets/python_requests_payload.html" %} - - -

      Ruby

      -{% include "front/snippets/ruby.html" %} - - -

      Node

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

      PHP

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

      C#

      -{% include "front/snippets/cs.html" %} - - -

      Browser

      -

      - {% site_name %} includes Access-Control-Allow-Origin:* - CORS header in its ping responses, so cross-domain AJAX requests - should work. -

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

      PowerShell

      -

      - You can use PowerShell - and Windows Task Scheduler to automate various tasks on a Windows system. - From within a PowerShell script it is also easy to ping {% site_name %}. -

      -

      Here is a simple PowerShell script that pings {% site_name %}. -When scheduled to run with Task Scheduler, it will essentially -just send regular "I'm alive" messages. You can of course extend it to -do more things.

      - -{% include "front/snippets/powershell.html" %} - -

      Save the above to e.g. C:\Scripts\healthchecks.ps1. Then use -the following command in a Scheduled Task to run the script: -

      - -
      - 
      powershell.exe -ExecutionPolicy bypass -File C:\Scripts\healthchecks.ps1
      -
      - -

      In simple cases, you can also pass the script to PowerShell directly, -using the "-command" argument:

      - -{% include "front/snippets/powershell_inline.html" %} - - -

      Email

      -

      - As an alternative to HTTP/HTTPS requests, - you can "ping" this check by sending an - email message to {{ ping_email }} -

      -

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

      -

      - 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 get sent and - get delivered. -

      -

      - The solution: set up another check, and add its - @{{ ping_email_domain }} 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. -

      - - -

      When Alerts Are Sent

      -

      - Each check has a configurable Period parameter, with the default value of one day. - For periodic tasks, this is the expected time gap between two runs. -

      -

      - Additionally, each check has a Grace 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. -

      -

      Each check can be in one of the following states:

      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - New. - A check that has been created, but has not received any pings yet. -
      - - - Monitoring Paused. - You can resume monitoring of a paused check by pinging it. -
      - - - Started. - The check has received a "start" signal, and is currently running. -
      - - - Up. - Time since last ping has not exceeded Period. -
      - - - Late. - Time since last ping has exceeded Period, - but has not yet exceeded Period + Grace. -
      - - -

      Down. The check has not received a "success" - ping in time, or it has received an explicit "fail" signal. -

      -

      - When a check goes into the "Down" state, {% site_name %} - sends you an alert. -

      -
      - -{% endblock %} - -{% block scripts %} -{% compress js %} - - - - -{% endcompress %} -{% endblock %}