Cronitor Node Library

Cronitor 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
npm install cronitor --save
# or
yarn add cronitor
Monitoring Background Jobs
Integrate with Cron Libraries
If you are using a library like node-cron or cron, this package provides a lightweight wrapper to enable easy monitoring integration.
const cron = require('cronitor')('cronitor_api_key');
const nodeCron = require('node-cron');
cron.wraps(nodeCron);
cron.schedule('SendWelcomeEmail', '*/5 * * * *', () => {
console.log('Sending welcome email to new sign ups every five minutes.');
});
Monitor Any Function
Cronitor can wrap any function with telemetry pings.
const cronitor = require('cronitor')('cronitor_api_key');
let asyncWorker = cronitor.wrap('background-worker', async () => {
});
await asyncWorker();
Monitor long running processes
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 Event
object to synchronously record loop ticks and asynchronously batch report these events to Cronitor.
The following example uses sqs-consumer.
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,
handleMessage: async (message) => {
}
});
app.on('processed_message', () => {
event.tick();
});
app.on('empty', () => {
event.tick(0);
});
app.on('error', (err) => {
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 .ping
method.
const monitor = new cronitor.Monitor('heartbeat-monitor');
monitor.ping();
monitor.ping({
state: 'run|complete|fail|ok',
env: '',
message: '',
metrics: {
duration: 100,
count: 4500,
error_count: 10
}
});
Configuring Monitors
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.
const cronitor = require('cronitor')('apiKey123');
cronitor.readConfig({path: './cronitor.yaml'});
cronitor.validateConfig({path: './cronitor.yaml'});
cronitor.applyConfig({path: './cronitor.yaml'});
cronitor.generateConfig({path: './cronitor.yaml'});
The cronitor.yaml
file includes three top level keys jobs
, checks
, heartbeats
. You can configure monitors under each key by defining monitors.
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
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).
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'
]
})
Pause, Reset, Delete
const monitor = new cronitor.Monitor('heartbeat-monitor');
monitor.pause(24)
monitor.unpause()
monitor.ok()
monitor.delete()
Package Configuration
The package needs to be configured with your account's API key
, 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
.
const cronitor = require('cronitor')(
'cronitor_api_key',
{
apiVersion: '2020-10-01',
environment: 'staging',
timeout: 5000,
region: 'eu'
});
Contributing
Pull requests and features are happily considered! By participating in this project you agree to abide by the Code of Conduct.
To contribute
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