API Docs

Telemetry API


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.

Sending Events

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

Client Libraries

This doc uses curl to interact with the Telemetry API over HTTP.

Select one of our client libraries to see usage examples in code.

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

# send an event
curl https://cronitor.link/p/<API-KEY>/airflow-heartbeat
# 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
# send an event with count and error count
curl https://cronitor.link/p/<API-KEY>/address-verification-counts?metric=count:100&metric=error_count:5

Event Parameters

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
beta 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
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

Anonymous Events

Cronitor auto-assigns a UUID for every monitor that is created. 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 account settings page.

# Send an anonymous telemetry 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.

Email Integration

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 {monitorUUID}@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.link

Rate Limiting

In 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.

  • Each event endpoint (run, complete, fail, etc) allows 5 requests/sec with bursts up to 10 pings beyond the limit.
  • Each IP address is allowed 50 requests/sec, with bursts of 250 pings beyond the limit.

FAQs & Tips

  • Telemetry URLs will accept GET, POST and HEAD requests. At this time, all POST bodies are discarded.
  • Telemetry URLs were originally hosted on the 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 burts of ping traffic (think midnight UTC).
  • Unencrypted (e.g. http://) pings are only accepted on cronitor.link. Unencrypted pings sent to cronitor.io will receive a 301 redirect response pointing to https://cronitor.io.