A simple library for reliably monitoring cron jobs, control-loops, or other important system events with Cronitor.
npm install cronitorCronitor provides end-to-end monitoring for background jobs, websites, APIs, and anything else that can send or receive an HTTP request. This library provides convenient access to the Cronitor API from applications written in Javascript. See our API docs for detailed references on configuring monitors and sending telemetry pings.
In this guide:
- Installation
- Monitoring Background Jobs
- Sending Telemetry Events
- Configuring Monitors
- Package Configuration & Env Vars
npm install cronitor --save
or
yarn add cronitor
Monitoring Background Jobs
$3
If you are using a library like node-cron or cron, this package provides a lightweight wrapper to enable easy monitoring integration.javascript
const cron = require('cronitor')('cronitor_api_key');
const nodeCron = require('node-cron');cron.wraps(nodeCron);
// the first parameter is now the key that Cronitor will use
// to send telemetry events when the jobs runs, completes or fails
cron.schedule('SendWelcomeEmail', '/5 *', () => {
console.log('Sending welcome email to new sign ups every five minutes.');
});
`$3
Cronitor can wrap any function with telemetry pings.
javascript
const cronitor = require('cronitor')('cronitor_api_key');let asyncWorker = cronitor.wrap('background-worker', async () => {
// do some async work
});
// cronitor will track the start and end time and state (promise resolved or rejected).
await asyncWorker();
`$3
If you have a long running process (Control-Loop, Daemon, Worker, etc) you might not care about the lifecycle (start/end),
and instead wish to record counts/error counts of these events instead. Use the
object to synchronously record loop ticks and asynchronously batch report these events to Cronitor.
The following example uses sqs-consumer.javascript
const cronitor = require('cronitor')('cronitor_api_key');
const { Consumer } = require('sqs-consumer');event = new cronitor.Event('monitor-key');
const app = Consumer.create({
queueUrl: 'https://sqs.eu-west-1.amazonaws.com/account-id/queue-name',
pollingWaitTimeMs: 100, // duration to wait before repolling the queue (defaults to 0).
handleMessage: async (message) => {
// do some work with
message
}
});// Consumer is an event emitter and will emit one of the below events each time it is called.
// a message was processed
app.on('processed_message', () => {
// increment the tick counter, no other side effects.
event.tick();
});
// the queue is empty
app.on('empty', () => {
// record a tick and also record that no message was processed
event.tick(0);
});
// an error occurred connectiong to SQS
app.on('error', (err) => {
// .error is a special "tick" method for reporting error counts.
// Use it to tell Cronitor your program is still running, but encountering errors.
// Error rate alert thresholds are configurable.
event.error();
});
oncon
app.start();
Sending Telemetry Events
If you want to send a heartbeat events, or want finer control over when/how telemetry events are sent for your jobs, you can create a monitor instance and call the
method.`javascript
const monitor = new cronitor.Monitor('heartbeat-monitor');// send a heartbeat event
monitor.ping();
// optional params can be passed as an object.
// for a complete list see https://cronitor.io/docs/ping-api
monitor.ping({
state: 'run|complete|fail|ok', // run/complete|fail used to measure lifecycle of a job.
env: '', // the environment this is running in (development, staging, production)
message: '', // optional message that will be displayed in alerts as well as monitor activity panel on your dashboard.
metrics: {
duration: 100,
count: 4500,
error_count: 10
}
});
`Configuring Monitors
$3
You can configure all of your monitors using a single YAML file. This can be version controlled and synced to Cronitor as part of
a deployment or build process. For details on all of the attributes that can be set, see the Monitor API documentation.javascript
const cronitor = require('cronitor')('apiKey123');cronitor.readConfig({path: './cronitor.yaml'}); // parse the yaml file of monitors
cronitor.validateConfig({path: './cronitor.yaml'}); // send monitors to Cronitor for configuration validation
cronitor.applyConfig({path: './cronitor.yaml'}); // sync the monitors from the config file to Cronitor
cronitor.generateConfig({path: './cronitor.yaml'}); // generate a new config file from the Cronitor API
`The
file includes three top level keys jobs, checks, heartbeats. You can configure monitors under each key by defining monitors.`yaml
jobs:
nightly-database-backup:
schedule: 0 0 *
notify:
- devops-alert-pagerduty
assertions:
- metric.duration < 5 minutes send-welcome-email:
schedule: every 10 minutes
assertions:
- metric.count > 0
- metric.duration < 30 seconds
checks:
cronitor-homepage:
request:
url: https://cronitor.io
regions:
- us-east-1
- eu-central-1
- ap-northeast-1
assertions:
- response.code = 200
- response.time < 2s
cronitor-ping-api:
request:
url: https://cronitor.link/ping
assertions:
- response.body contains ok
- response.time < .25s
heartbeats:
production-deploy:
notify:
alerts: ['deploys-slack']
events: true # send alert when the event occurs
`#### Async Uploads
If you are working with large YAML files (300+ monitors), you may hit timeouts when trying to sync monitors in a single http request. This workload to be processed asynchronously by adding the key
to the config file. The request will immediately return a batch_key. If a webhook_url parameter is included, Cronitor will POST to that URL with the results of the background processing and will include the batch_key matching the one returned in the initial response.
$3
You can also create and update monitors by calling
Monitor.put. For details on all of the attributes that can be set see the Monitor API [documentation)(https://cronitor.io/docs/monitor-api#attributes).`javascript
const cronitor = require('cronitor')('apiKey123');const jobMonitor = await cronitor.Monitor.put({
type: 'job',
key: 'send-customer-invoices',
schedule: '0 0 *',
assertions: [
'metric.duration < 5 min'
],
notify: ['devops-alerts-slack']
});
const uptimeMonitor = await cronitor.Monitor.put({
type: 'check',
key: 'Cronitor Homepage',
schedule: 'every 45 seconds',
request: {
url: 'https://cronitor.io'
},
assertions: [
'response.code = 200',
'response.time < 600ms'
]
})
`$3
javascript
const monitor = new cronitor.Monitor('heartbeat-monitor');monitor.pause(24) // pause alerting for 24 hours
monitor.unpause() // alias for .pause(0)
monitor.ok() // reset to a passing state alias for monitor.ping({state: ok})
monitor.delete() // destroy the monitor
`Package Configuration
The package needs to be configured with your account's
, which is available on the account settings page. You can also optionally specify an api_version, an environment, a request timeout, and a cronitor region.These can also be supplied using the environment variables
CRONITOR_API_KEY, CRONITOR_API_VERSION, CRONITOR_ENVIRONMENT, CRONITOR_TIMEOUT, CRONITOR_REGION.`javascript
const cronitor = require('cronitor')(
'cronitor_api_key',
{
apiVersion: '2020-10-01',
environment: 'staging',
timeout: 5000,
region: 'eu'
});
``Pull requests and features are happily considered! By participating in this project you agree to abide by the Code of Conduct.
Fork, then clone the repo:
git clone git@github.com:your-username/cronitor-js.git
Set up your machine:
npm install
Make sure the tests pass:
npm test
Make your change. Add tests for your change. Make the tests pass:
npm test
Push to your fork and submit a pull request