From d34854f8383f80d84065819491053a1b1784056d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Wed, 8 Jul 2020 17:19:13 +0300 Subject: [PATCH] Update bash examples with the "-m" parameter. --- static/css/docs.css | 6 +- templates/docs/bash.html | 41 +++++++++----- templates/docs/bash.md | 45 +++++++++++---- templates/docs/monitoring_cron_jobs.html | 66 ++++++++-------------- templates/docs/monitoring_cron_jobs.md | 70 +++++++++--------------- templates/docs/php.html | 2 +- templates/docs/php.md | 2 +- 7 files changed, 116 insertions(+), 116 deletions(-) diff --git a/static/css/docs.css b/static/css/docs.css index 9871f15f..fa9446f8 100644 --- a/static/css/docs.css +++ b/static/css/docs.css @@ -104,17 +104,17 @@ h2.rule { } -.docs-api dl { +.page-docs dl { display: grid; grid-template-columns: 150px auto; } -.docs-api dt { +.page-docs dt { font-weight: normal; font-family: "Lucida Console", Monaco, monospace; } -.docs-api dt, .docs-api dd { +.page-docs dt, .page-docs dd { border-top: 1px solid #DDD; padding: 8px 0; } diff --git a/templates/docs/bash.html b/templates/docs/bash.html index 6d31cd7b..aceecc5d 100644 --- a/templates/docs/bash.html +++ b/templates/docs/bash.html @@ -1,34 +1,49 @@

Shell Scripts

You can easily add SITE_NAME monitoring to a shell script. All you -have to do is make a HTTP request at the end of the script. +have to do is make a HTTP request at an appropriate place in the script. curl and wget are two common command line HTTP clients you can use.

-
# Sending a HTTP GET request with curl:
-curl --retry 3 PING_URL
+
# Sends a HTTP GET request with curl:
+curl -m 10 --retry 5 PING_URL
 
 # Silent version (no stdout/stderr output unless curl hits an error):
-curl -fsS --retry 3 PING_URL
-
-# Sending a HTTP GET request with wget:
-wget PING_URL -O /dev/null
+curl -fsS -m 10 --retry 5 -o /dev/null PING_URL
 

 
 
+
Here's what each curl parameter does:

+

+
-m <seconds>

+
Maximum time in seconds that you allow the whole operation to take.

+
--retry <num>

+
If a HTTP request fails, retry up to this many times. By default, curl
+uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...).
+See also --retry-delay.

+
-f, --fail

+
Makes curl treat non-200 responses as errors.

+
-s, --silent

+
Silent or quiet mode. Hides the progress meter, but also
+hides error messages.

+
-S, --show-error

+
Re-enables error messages when -s is used.

+
-o /dev/null

+
Redirect curl's stdout to /dev/null (error messages still go to stderr).

+

 
Signalling Failure from Shell Scripts

 
You can append /fail to any ping URL and  use the resulting URL to actively
-signal a failure. The below example:

+signal a failure. The following example:

 
    
 
  • runs /usr/bin/certbot renew
    • 
-
  • if the certbot command is successful (exit code 0), send HTTP GET to PING_URL
    • 
-
  • otherwise, send HTTP GET to PING_URL/fail
    • 
+
  • if the certbot command is successful (exit code 0), sends HTTP GET to PING_URL
    • 
+
  • otherwise, sends HTTP GET to PING_URL/fail
    • 
 

 
#!/bin/sh
 
 # Payload here:
 /usr/bin/certbot renew
 # Ping SITE_NAME
-curl --retry 3 "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
+curl -m 10 --retry 5 "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
 

 
 
@@ -40,7 +55,7 @@ will accept and store first 10KB of the request body.

 
#!/bin/sh
 
 m=$(/usr/bin/certbot renew 2>&1)
-curl -fsS --retry 3 --data-raw "$m" PING_URL
+curl -fsS -m 10 --retry 5 --data-raw "$m" PING_URL
 

 
 
@@ -61,5 +76,5 @@ register with SITE_NAME the first time they run.

 URL=`curl -s SITE_ROOT/api/v1/checks/  -H "X-Api-Key: $API_KEY" -d "$PAYLOAD"  | jq -r .ping_url`
 
 # Finally, send a ping:
-curl --retry 3 $URL
+curl -m 10 --retry 5 $URL
\ No newline at end of file diff --git a/templates/docs/bash.md b/templates/docs/bash.md index 40455960..37d35ea2 100644 --- a/templates/docs/bash.md +++ b/templates/docs/bash.md @@ -1,30 +1,51 @@ # Shell Scripts You can easily add SITE_NAME monitoring to a shell script. All you -have to do is make a HTTP request at the end of the script. +have to do is make a HTTP request at an appropriate place in the script. [curl](https://curl.haxx.se/docs/manpage.html) and [wget](https://www.gnu.org/software/wget/manual/wget.html) are two common command line HTTP clients you can use. ```bash -# Sending a HTTP GET request with curl: -curl --retry 3 PING_URL +# Sends a HTTP GET request with curl: +curl -m 10 --retry 5 PING_URL # Silent version (no stdout/stderr output unless curl hits an error): -curl -fsS --retry 3 PING_URL +curl -fsS -m 10 --retry 5 -o /dev/null PING_URL -# Sending a HTTP GET request with wget: -wget PING_URL -O /dev/null ``` +Here's what each curl parameter does: + +**-m <seconds>** +: Maximum time in seconds that you allow the whole operation to take. + +**--retry <num>** +: If a HTTP request fails, retry up to this many times. By default, curl + uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...). + See also [--retry-delay](https://curl.haxx.se/docs/manpage.html#--retry-delay). + +**-f, --fail** +: Makes curl treat non-200 responses as errors. + +**-s, --silent** +: Silent or quiet mode. Hides the progress meter, but also + hides error messages. + +**-S, --show-error** +: Re-enables error messages when -s is used. + +**-o /dev/null** +: Redirect curl's stdout to /dev/null (error messages still go to stderr). + ## Signalling Failure from Shell Scripts You can append `/fail` to any ping URL and use the resulting URL to actively -signal a failure. The below example: +signal a failure. The following example: * runs `/usr/bin/certbot renew` -* if the certbot command is successful (exit code 0), send HTTP GET to `PING_URL` -* otherwise, send HTTP GET to `PING_URL/fail` +* if the certbot command is successful (exit code 0), sends HTTP GET to `PING_URL` +* otherwise, sends HTTP GET to `PING_URL/fail` ```bash #!/bin/sh @@ -32,7 +53,7 @@ signal a failure. The below example: # Payload here: /usr/bin/certbot renew # Ping SITE_NAME -curl --retry 3 "PING_URL$([ $? -ne 0 ] && echo -n /fail)" +curl -m 10 --retry 5 "PING_URL$([ $? -ne 0 ] && echo -n /fail)" ``` ## Logging Command Output @@ -47,7 +68,7 @@ In the below example, certbot's output is captured and submitted via HTTP POST: #!/bin/sh m=$(/usr/bin/certbot renew 2>&1) -curl -fsS --retry 3 --data-raw "$m" PING_URL +curl -fsS -m 10 --retry 5 --data-raw "$m" PING_URL ``` ## Auto-provisioning New Checks @@ -71,5 +92,5 @@ PAYLOAD='{"name": "'`hostname`'", "timeout": 60, "grace": 60, "unique": ["name"] URL=`curl -s SITE_ROOT/api/v1/checks/ -H "X-Api-Key: $API_KEY" -d "$PAYLOAD" | jq -r .ping_url` # Finally, send a ping: -curl --retry 3 $URL +curl -m 10 --retry 5 $URL ``` diff --git a/templates/docs/monitoring_cron_jobs.html b/templates/docs/monitoring_cron_jobs.html index c2051859..59418976 100644 --- a/templates/docs/monitoring_cron_jobs.html +++ b/templates/docs/monitoring_cron_jobs.html @@ -30,19 +30,19 @@ increasingly important as you add more checks to your account.

Edit the check's schedule:

  • -

    Take note of your check's unique ping URL

    +

    Take note of your check's unique ping URL.

    • Finally, edit your cron job definition and append a curl or wget call after the command:

    $ crontab -e
 # m h dom mon dow command
-  8 6 * * * /home/user/backup.sh && curl -fsS --retry 3 -o /dev/null PING_URL
+  8 6 * * * /home/user/backup.sh && curl -fsS --retry 5 -o /dev/null PING_URL
    @@ -58,46 +58,26 @@ potentially go unnoticed otherwise:

  • cron does start your task, but the task exits with non-zero exit code

    • Curl Options

    -

    The extra options tells curl to not print anything to standard output unless -there is an error. Feel free to adjust the curl options to suit your needs.

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    &&Run curl only if /home/user/backup.sh exits with an exit code 0
    - -f, --fail - Makes curl treat non-200 responses as errors
    -s, --silentSilent or quiet mode. Use it to hide progress meter, - but it also hides error messages.
    -S, --show-errorRe-enables error messages when -s is used.
    --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 is a timeout or an HTTP 5xx - response code. -
    -o /dev/null - Redirect curl's stdout to /dev/null (error messages still go to stderr) -
    - +

    The extra options in the above example tells curl to retry failed HTTP requests, and +to silence output unless there is an error. Feel free to adjust the curl options to +suit your needs.

    +
    +
    &&
    +
    Run curl only if /home/user/backup.sh exits with an exit code 0.
    +
    -f, --fail
    +
    Makes curl treat non-200 responses as errors.
    +
    -s, --silent
    +
    Silent or quiet mode. Hides the progress meter, but also hides error messages.
    +
    -S, --show-error
    +
    Re-enables error messages when -s is used.
    +
    --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 is a timeout or an HTTP 5xx response code.
    +
    -o /dev/null
    +
    Redirect curl's stdout to /dev/null (error messages still go to stderr).
    +

    Looking up Your Machine's Time Zone

    On modern GNU/Linux systems, you can look up the time zone using the timedatectl status command and looking for "Time zone" in its output:

    diff --git a/templates/docs/monitoring_cron_jobs.md b/templates/docs/monitoring_cron_jobs.md index 7cf3ae18..cf8d017a 100644 --- a/templates/docs/monitoring_cron_jobs.md +++ b/templates/docs/monitoring_cron_jobs.md @@ -30,10 +30,10 @@ increasingly important as you add more checks to your account. 1. Edit the check's **schedule**: * change its type from "Simple" to "Cron" - * enter `8 6 * * *` in the cron epression field + * enter `8 6 * * *` in the cron expression field * set the timezone to match your machine's timezone -1. Take note of your check's unique **ping URL** +1. Take note of your check's unique **ping URL**. Finally, edit your cron job definition and append a curl or wget call after the command: @@ -41,7 +41,7 @@ after the command: ```bash $ crontab -e # m h dom mon dow command - 8 6 * * * /home/user/backup.sh && curl -fsS --retry 3 -o /dev/null PING_URL + 8 6 * * * /home/user/backup.sh && curl -fsS --retry 5 -o /dev/null PING_URL ``` Now, each time your cron job runs, it will send a HTTP request to the ping URL. @@ -58,46 +58,30 @@ potentially go unnoticed otherwise: ## Curl Options -The extra options tells curl to not print anything to standard output unless -there is an error. Feel free to adjust the curl options to suit your needs. - - - - - - - - - - - - - - - - - - - - - - - - - - -
    &&Run curl only if /home/user/backup.sh exits with an exit code 0
    - -f, --fail - Makes curl treat non-200 responses as errors
    -s, --silentSilent or quiet mode. Use it to hide progress meter, - but it also hides error messages.
    -S, --show-errorRe-enables error messages when -s is used.
    --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 is a timeout or an HTTP 5xx - response code. -
    -o /dev/null - Redirect curl's stdout to /dev/null (error messages still go to stderr) -
    +The extra options in the above example tells curl to retry failed HTTP requests, and +to silence output unless there is an error. Feel free to adjust the curl options to +suit your needs. + +**&&** +: Run curl only if `/home/user/backup.sh` exits with an exit code 0. + +**-f, --fail** +: Makes curl treat non-200 responses as errors. + +**-s, --silent** +: Silent or quiet mode. Hides the progress meter, but also hides error messages. + +**-S, --show-error** +: Re-enables error messages when -s is used. + +**--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 is a timeout or an HTTP 5xx response code. + +**-o /dev/null** +: Redirect curl's stdout to /dev/null (error messages still go to stderr). ## Looking up Your Machine's Time Zone diff --git a/templates/docs/php.html b/templates/docs/php.html index 3cc64e1a..e24112da 100644 --- a/templates/docs/php.html +++ b/templates/docs/php.html @@ -16,4 +16,4 @@ -

    Note: this code never throws any exception.

    \ No newline at end of file +

    Note: this code does not throw any exceptions.

    \ No newline at end of file diff --git a/templates/docs/php.md b/templates/docs/php.md index b84da268..ed9f50b8 100644 --- a/templates/docs/php.md +++ b/templates/docs/php.md @@ -19,4 +19,4 @@ $curl->setTimeout(5); $curl->get('PING_URL'); ``` -Note: this code never throws any exception. +Note: this code does not throw any exceptions.