README

This is a trivial PHP client (one class with a fluent interface) that helps you to monitor success or failure of stuff.

One thing that is often overlooked when writing crons and other regular processes is health monitoring. This usually takes the form of "Oh my god, such-and-such a script has not run successfully for 2 weeks, help!".

Absence of Success

One key thing here is that this system looks for the absence of a success message. So, if your cron starts hitting a Fatal error, this will tell you. Regular "log/email" stuff in a script will not even get hit.

Getting Started

When you need to know if some regular process stops working, do something like this at the end of your script (when you know the job is done to satisfaction)

Docnet\MATT::expect('My cron finished OK')->every('15m')->sms('07777123456');

If something should never happen, do this (perhaps in the main 'catch' block)

Docnet\MATT::expect('Some horrible error')->never()->email('bill@microsoft.com');

Install with Composer

Here's the require line for Composer users...

"docnet/matt-client": "dev-master"

No set-up required

You don't need to go and set up monitors in a web interface or anything. The first time you make a call (as above) the server will start watching.

You'll get a single set up message too, on first call for a unique event reference.

Named recipients

You can used named targets and groups that have been set up too, so in this example 'support' means several people

Docnet\MATT::expect('Some other horrible error')->never()->email('support');

At the time of writing, named recipients must be set up by the author.

Event Names

The expect() singleton factory method takes an event name/identifier as a parameter. These are limited to 32 characters and will be truncated.

We trigger a E_USER_WARNING when we do this.

Intervals

The every() method take a string parameter to represent intervals. Supported interval strings are one of

• minute
• hour
• day
• week
• month

OR, one of the following time representations, where N is a number

• Nm
• Nh
• Nd

Changing Intervals

If you start off with

Docnet\MATT::expect('My cron finished OK')->every('5m')->sms('07777123456');

And then decide you want to change the interval, just change the value you are passing to every(), like this:

Docnet\MATT::expect('My cron finished OK')->every('15m')->sms('07777123456');

The system will update it's watch interval automatically for you, and send you another confirmation message.

Alert Frequency

MATT will send you alerts once every skipped interval.

So, a failed cron due to run once per hour will send you alerts once per hour until it runs successfully again.

Watch out - If you ask for an SMS every minute - you'll get one!

Monitors are HOST and DOCNET_APP_ID unique

By default, the MATT client will include your hostname as part of the request and, if defined, the DOCNET_APP_ID.

Monitors are unique to host+app_id pairs.

This means a monitor for "Google feed uploaded OK" can run and each client check will be independent of each other.

If you need to override the hostname, you can use the from() method as follows (but watch overlap with development).

Docnet\MATT::expect('Clustered cron')->from('cluster')->every('hour')->email('support');

Cancellation (stop monitoring)

If you need to stop the server monitoring a particular event, use cancel() like this

MATT::expect('Some other horrible error')->cancel();

The system will notify current SMS and EMAIL recipients of the cancellation.

Silent watching/cancelling

If you need to suppress the "Now watching..." and "Stopped watching..." messages, use suppress_watch_message() like this

Docnet\MATT::expect('Clustered cron')->from('cluster')->every('hour')->email('support')->suppress_watch_message();

Docnet\MATT::expect('Clustered cron')->cancel()->suppress_watch_message();

API calls over HTTPS with PHP Streams

As we don't know what sort of platforms we are going to be deployed on to, we don't use Curl in case it's not installed.

So, API calls are made over HTTPS using PHP native Streams and associated context options. If HTTPS using PHP native Streams fails and Curl is available, the API call will be attempted via Curl

API calls are made on __destruct() of each MATT instance. If the call fails, an E_USER_WARNING triggered.

If the response from the server includes a textual message, this is pushed out with an E_USER_NOTICE.

PHP Version Support

Desired compatibility with PHP 5.3.0 and above.

Coding Standards

Desired adherence to PSR-2.