Sending telemetry events is the core integration mechanism for Cronitor's Job and Heartbeat monitors.
Jobs use telemetry events to implement a state machine that tracks the start time, end time and exit state of a cron job/scheduled task or other long running background process.
Heartbeats use telemetry events to record periodic system health, output or metrics.
In this guide:
The Telemetry Events resource is hosted on a separate domain from the rest of the Cronitor API. Events are recorded by sending requests to the following URL:
Base URL
https://cronitor.link/p/:apiKey/:monitorKey
| Param | Description |
:apiKey |
Authentication is handled by including an API key in the URL. Obtain one from your account settings page. |
:monitorKey |
A unique identifier for your monitor. If no monitor matches the provided key, a new monitor will be created automatically. |
Basic Usage - Jobs
# send a run event to indicate a job has started
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run
# send a complete event to indicate a job has completed successfully
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete
# send a failure event to trigger an immediate alert
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=fail
Basic Usage - Heartbeats
# send a heartbeat event
curl https://cronitor.link/p/<API-KEY>/airflow-heartbeat
# send a heartbeat event with count and error count
curl https://cronitor.link/p/<API-KEY>/address-verification-counts?metric=count:100&metric=error_count:5
Telemetry events can be enriched by sending optional query parameters along with each request. In the Basic Usage examples above, the state, count and error_count params were all used.
| Parameter | Description |
env |
The environment the telemetry event is being sent from. Use this for monitors that are running in multiple environments (e.g. staging and production). Alerting can be configured per environment. |
host |
The hostname of the server sending the telemetry event. |
message |
A url-encoded message of up to 2000 characters. |
metric |
Performance related metrics. Must be one of:
count:* - record counts of important events.
duration:* - the duration of the job/task being monitored.
error_count:* - the number of errors that occurred
curl https://cronitor.link/p/.../nightly-job?metric=count:100&metric=error_count:2
|
series |
A unique user-supplied ID to collate related pings, i.e. matching state=run and state=complete|fail to one another. If a job is pinging very frequently (every 2-3s or faster), it will greatly improve matching accurracy. |
state |
Indicate a state change for a monitor. Must be one of: run - a background job has started running.
complete - a background job completed successfully.
fail - a background job failed/an error occurred.
ok - manually reset the monitor to a passing state.
|
status_code |
Exit code returned from a background job. |
Parameters Usage Examples
# send an event to indicate that a job has been started on a specific host, by a specific user
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run&host=10.0.01&message='Job started by August'
# send a pair of run and complete events with the same series
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run&series=abcd
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete&series=abcd
# send a failure event with an error message
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=fail&message=$ERROR_MESSAGE
# send a complete event with count and error count
curl https://cronitor.link/p/<API-KEY>/address-verification-counts?state=complete&metric=count:100&metric=error_count:5
Cronitor auto-assigns a short, unique ID for every monitor that is created (called "key" on the dashboard and API). This allows anonymous telemetry events — events that don't use an API Key for authentication.
Anonymous telemetry events were the original integration mechanism for Cronitor, and will always be supported.
Accounts created after January 11th, 2021 require anonymous events to be enabled from the API settings page.
# Send a heartbeat event
curl https://cronitor.link/d3x0c1
# send a run event to indicate a job has started
curl https://cronitor.link/d3x0c1/run
# send a complete event to indicate a job has completed successfully
curl https://cronitor.link/d3x0c1/complete
# send a failure event to trigger an immediate alert
curl https://cronitor.link/d3x0c1/fail
Tip:While Cronitor's globally assigned ID's may look like a plain hash, each contains an embedded checksum, which gives us the ability to filter/block malicious traffic.
The Telemetry Events API supports sending events via email (SMTP) in addition HTTP. To send telemetry events via email you must first enable anonymous events.
Events are sent by sending email to {your-monitor-key}@cronitor.link
To report lifecycle events append the state with a + as shown below.
# send a run event to indicate a job has started
d3x0c1+run@cronitor.link
# send a complete event to indicate a job has completed successfully
d3x0c1+complete@cronitor.link
# send a failure event to trigger an immediate alert
d3x0c1+fail@cronitor.linkIn order to prevent users from accidentally flooding the Telemetry Events API (and potentially disrupting service for other users), Cronitor imposes rate limits on the number of requests that can be made to the Telemetry Events API. Requests over the limit will receive an HTTP 429 status code.
GET, POST and HEAD
requests. At this time, all POST bodies are discarded.
cronitor.io domain. To segregate ping traffic, we launched
the cronitor.link domain in February, 2015. This is a specially tuned cluster of ping collectors optimized for huge bursts of traffic (think midnight UTC).