deceptively simple web service with super powers
TimerCheck.io is a fully functional, fully scalable microservice built on the just-released Amazon API Gateway and increasingly popular AWS Lambda platforms.
TimerCheck.io is a public web service that maintains a practically unlimited number of countdown timers with one second resolution and no practical limit to the number of seconds each timer can run.
New timers can be created on a whim and each timer can be reset at any time to any number of seconds desired, whether it is still running or has already expired.
Synopsis
Let’s begin with an example to demonstrate the elegant simplicity of the TimerCheck.io interface.
1. Set timer - Any request of the following URL sets a timer named “YOURTIMERNAME” to start counting down immediately from 60 seconds:
You may click on that link now, or hit a URL of the same format with
your own timer name and your chosen number of seconds. You may use a
browser, a command like curl, or your favorite programming language.
2. Poll timer - The following URL requests the status of the above timer. Note that the only difference in the URL is that we have dropped the seconds count.
If the named timer is still running, TimerCheck.io will return HTTP
Status code 200 OK, along with a JSON structure containing
information like how many seconds are left.
If the timer has expired, TimerCheck.io will return an HTTP status
code 504 Timeout.
That’s it!
No, really. That’s the entire API.
And the whole service is implemented in about 100 lines of code, on top of a handful of powerful infrastructure services managed, protected, maintained, and scaled by Amazon.
Not Included
The TimerCheck.io service does not perform any action when a timer expires. The timer should be polled to find out if it has expired.
On first thought, this may cause you to wonder if this service might, in fact, be completely useless. Instead of polling TimerCheck.io, why not just have your code keep its own timer records or look at a clock and see if it’s time yet?
The answer is that TimerCheck.io is not created for situations where you can depend on your own code to be running and keeping track of things.
TimerCheck.io is designed for integration with existing third party software packages and services that already support a polling mechanism, but do not implement timers.
For example…
Event Monitoring
There are many types of monitoring software packages and free/commercial services that poll resources to see if they are healthy and alert you if there is a problem, but they have no way to alert you if an expected event does not occur. For example, you may want to ensure that a batch job runs every hour, or a message is posted to an SNS topic at least every 15 minutes.
The TimerCheck.io service can be the glue between the existing events you wish to monitor and your existing monitoring system. Here’s how it works:
1. Set timer - When your event runs, trigger a ping of TimerCheck.io to reset the timer. In the URL, specify the name of the timer and the number of seconds when your monitoring system should consider it a problem if no further event has run.
2. Poll timer - Add the TimerCheck.io polling URL for the same timer to your monitoring software, configuring it to alert you if the web request returns anything but success.
If your events keep resetting the timer before the timer expires, your monitoring system will stay happy and quiet, as the polling URL will always return success.
If the monitoring system polls the timer when no event has run in the specified number of seconds, then alarms sound, you will be woken up, and you can investigate why your batch job did not run on its expected schedule.
This is all possible using your existing monitoring system’s standard web check service, without any additional plugins or feature development.
Naming
TimerCheck.io has no registration, no authentication, and no authorization. If you don’t want somebody else resetting your timer accidentally or on purpose, you should pick a timer name that is unguessable even with brute force.
For example:
# A sensible timer name with some unguessable random bits
timer=https://timercheck.io/sample-timer-$(pwgen -s 22 1)
echo $timer
# (OR)
timer=https://timercheck.io/sample-timer-$(uuid -v4 -FSIV)
echo $timer
# Set the timer to 1 hour
seconds=3600
curl -s $timer/$seconds | jq .
# Check the timer
curl -s $timer | jq .
Cron Jobs
Say I have a cron job that runs once an hour. I don’t mind if it fails to compelete successfully once, but if it fails to check in twice in a row, I want to be alerted.
This example will use a random number for the timer name. You should generate your own unique timer names (see previous section).
Here’s a sample crontab entry that runs my job, then resets the countdown timer using TimerCheck.io:
0 * * * * $HOME/bin/create-snapshots && curl -s https://timercheck.io/sample-cron-4/8100 >/dev/null
The timer is being reset at the end of each job to 8100 seconds which is two hours plus 15 minutes. The extra minutes gives the hourly cron job some extra time to complete before we start sounding alarms.
All that’s left is to add the monitor poll URL to my monitoring service:
Responses
Though you can ignore the response content from the TimerCheck.io web service, here are samples of what it returns.
If the timer has not yet expired because your events are running on schedule and resetting the countdown, then the monitoring URL returns a 200 success code along with the current state of the timer. This includes things like when the timer set URL was last requested, and how many seconds remain before the timer goes into an error state.
{
"timer": "YOURTIMERNAME",
"request_id": "501abe10-2dad-11e5-80c1-35cdcb449e41",
"status": "ok",
"now": 1437265810,
"start_time": 1437265767,
"start_seconds": 60,
"seconds_elapsed": 43,
"seconds_remaining": 17,
"message": "Timer still running"
}
If the timer has expired and no event has been run to reset it, then the monitor URL returns a 504 timeout error code and an error message. Once I figure out how to get the API Manager to return both an error code and some JSON content, I will expand this to include more details about when the timer expired.
{
"errorMessage": "504: timer timed out"
}
When you call the event URL, passing in the number of seconds for resetting the timer, the API returns the previous state of the timer (as in the first example above) along with a note that it has set the new values.
{
"timer": "YOURTIMERNAME",
"request_id": "36a764b6-2dad-11e5-9318-f3b076dd2a3a",
"status": "ok",
"now": 1437265767,
"start_time": 1437263674,
"start_seconds": 60,
"seconds_elapsed": 2093,
"seconds_remaining": -2033,
"message": "Timer countdown updated",
"new_start_time": 1437265767,
"new_start_seconds": 60
}
If this is the first time you have set the particular timer, the previous state keys will be missing.
Guarantees
There are none.
TimerCheck.io a free public service intended, but not guaranteed, to be useful. It may return unexpected results. At any time and with no warning, it may become unavailable for short periods or forever.
Terms of Use
Don’t use TimerCheck.io in an abusive manner. If you are unsure if your use case might be considered abusive, ask.
Alternatives
I am not aware of any services that operate the same way as TimerCheck.io, with the ability to add dead man switch features to existing polling-based monitoring services, but here are a few services that are targeted specifically at event monitoring.
What do you use for monitoring and alerting? Are you using monitoring to make sure scheduled events are not missed?
[Update 2018-01-18: The Python version is a little longer than the original NodeJS version.]