Monitor is a web service that your computers can use to look at the results of a Batch stored on our system. A web service is a software system designed to support interoperable machine-to-machine interaction over a network.
In lay terms, your computer asks Monitor "Did this Batch work?", and Monitor answers with a Yes or No that is easy for your computer to understand (parse).
Real World Use Case
We monitor our own CheckTLS email system. We setup a Batch Thru to compute a total score for how well we both send and receive email. We scheduled the Batch to run every six hours.
Our hosting company uses PRTG to monitor. It uses our Monitor web service to read the LastRun and LastTotal from the Batch, and it alerts us if the test didn't run or if our score falls below 100.
This is the Batch we use:
<BatchTest TestType="thru"> <Target>CheckTLS-Reply@CheckTLS.com</Target> <Delivery> <To>File</To> <Format>text</Format> </Delivery> <Total Function="average"></Total> </BatchTest>
This is the XML that Monitor outputs:
<CheckTLS test="thru"> <Description>Monitor CheckTLS</Description> <LastRun>2017-02-15T14:54:12-0500</LastRun> <LastTotal>100.000000</LastTotal> </CheckTLS>Click here to fiddle with this Monitor.
Simple and fail-safe email monitoring and verification for the price of a Corporate Subscription to CheckTLS!
What It Does
Using Monitor and Batch, your computers can:
- know for certain a Batch of addresses is OK
- know for certain your email is OK, both in and out
- know CheckTLS is OK
- access Batch results
Your computers use a specially formatted URL to talk directly with our computers to find out if a Batch worked. Monitor is an "active positive" test, which means everything has to work for it to report "success". If Monitor reports "success" it means three things:
- Your Batch
- Your Batch did all the testing you put into it and returned your definition of success
- Our Tests
- Our programming of all the tests and scripting you put into your Batch worked
- Our Hosting
- Our computers, internet, and data center are all working
If the targets in your Batch don't meet your spec, Monitor returns "unsuccessful". If CheckTLS has any internal errors or fails to run your Batch for any reasons, Monitor returns "unsuccessful". If CheckTLS is down, Monitor does not return anything, which is also "unsuccessful".
The URL your computer uses to talk to our computer includes your User Code, Password, and a BatchId. Monitor uses those to lookup the last time the Batch was run all the way thru and what the final total was. The URL also includes an AGE and a MINIMUM for success.
If the Batch last finished longer ago than the AGE that you specify, Monitor returns "unsuccessful". This prevents false positives. The Batch has to have run all the way to the end within the last AGE minutes to be successful.
If the Batch total was less than the MINIMUM, Monitor returns "unsuccessful". Monitor compares your definition of success (MINIMUM) to the total that you programmed into the Batch (see Batch documentation and edit for more information). You decide what "success" means.
Monitor has three modes: XML, CHECK, and RAW.
In XML mode, Monitor answers your computer with the raw AGE and TOTAL for the Batch. This lets you program your own rules for success and failure. You decide how bad a failure is and what you want to do about it. Monitor sends this XML document:
<CheckTLS test="receiver"> <Description>receiver test on firstname.lastname@example.org</Description> <LastRun>2017-02-04T07:36:03-0500</LastRun> <LastTotal>100.000000</LastTotal> </CheckTLS>
The XML elements are very simple:
- The XML root node. The test attribute says the Batch was a receiver test (as opposed to a thru test).
- The Description you gave to the Batch in BatchEdit.
- The date and time the Batch last ran through to the very end.
- The total you told the Batch to compute (total).
In CHECK mode, Monitor looks at the AGE and TOTAL of the Batch for you. It checks if the Batch finshed recently enough and if it had a high enough score. You tell Monitor how long ago and what score means "success". Monitor answers your computer with a yes or no.
Monitor has three ways to tell your computer if the Batch in question was "successful":
Monitor replies with a valid web page with a single line:
The web page is easily parsed by your computer. The complete output looks like:
Test OK Test NOT OK
HTTP/1.1 200 OKg Date: Fri, 24 Feb 2017 13:24:34 GMTg Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3g Age: 64846g Cache-Control: max-age=0g Expires: Fri, 24 Feb 2017 13:24:34 GMTg Transfer-Encoding: chunkedg Content-Type: text/html; charset=ISO-8859-1g g <html> <head> <title>OK</title> </head> <body> Test OK </body>
Monitor replies with just a 1 or a 0. It is an invalid HTML document that looks like:
HTTP/1.1 200 OK Date: Fri, 24 Feb 2017 13:34:17 GMT Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 65429 Cache-Control: max-age=0 Expires: Fri, 24 Feb 2017 13:34:17 GMT Transfer-Encoding: chunked Content-Type: text/html; charset=ISO-8859-1 1
Monitor fails at the web page level, returning an HTTP status 200 or 412 (see HTTP Response Headers)
HTTP/1.1 412 Criteria Failed Date: Fri, 24 Feb 2017 13:39:06 GMT Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 65718 Last-Modified: Fri, 24 Feb 2017 13:39:06 GMT Cache-Control: max-age=0 Expires: Fri, 24 Feb 2017 13:39:06 GMT Transfer-Encoding: chunked Content-Type: text/html; charset=ISO-8859-1 <html> <head> <title>FAIL</title> </head> <body> Batch failed monitor criteria </body>
By setting Show Results to "Y", you can tell Monitor to send you the output from the Batch as well. You get both the CHECK result and the Batch result. See RAW Mode below.
RAW Mode (Batch Results as a Web Service)
In RAW mode, Monitor just sends you the output from the Batch. Since this is the actual output from the Batch in the format specified in the Batch, you choose the format that your computer can parse and use. RAW mode gives you the LastRun date and time in the Age: header and looks like:
HTTP/1.1 412 Criteria Failed Date: Fri, 24 Feb 2017 13:42:51 GMT Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 65944 Last-Modified: Fri, 24 Feb 2017 13:42:52 GMT Cache-Control: max-age=0 Expires: Fri, 24 Feb 2017 13:42:51 GMT Transfer-Encoding: chunked Content-Type: text/html; charset=ISO-8859-1 <html> <head> <title>FAIL</title> </head> <body> Batch failed monitor criteria <p>Test score is too low</p> <pre><code>100 email@example.com 100 firstname.lastname@example.org 100 NoOne@NoWhere.com 100 SomeOne@SomeWhere.com 100.000 average </body>
RAW mode is web service access to the results of stored Batches. Since Batch unlocks options that are not available from the web site (Custom), RAW mode is web service access to all CheckTLS.
See Batch Upload for how to create and/or run Batches as a web service.