Ruby SDK

Use the cronitor gem to report job runs, heartbeats, and metrics to Cronitor.

Install

gem install cronitor

With Bundler, add gem 'cronitor' to your Gemfile.

Configure

Set the CRONITOR_API_KEY environment variable to your SDK Integration key. Copy the key from Settings → API Keys at https://cronitor.io/app/settings/api. Keep the key in the environment or a secret store of the runtime. Do not commit it.

The gem reads CRONITOR_API_KEY when you require 'cronitor', so you do not need configuration code.

Monitor a job

Put the work of the job in a Cronitor.job block:

require 'cronitor'

Cronitor.job 'send-invoices' do
  SendInvoices.new.run
end

• Before the block starts, the SDK sends a run event.
• When the block ends, the SDK sends a complete event.
• When the block raises a StandardError, the SDK sends a fail event with the error message. Then it raises the error again.
• Cronitor calculates the duration from the run event and the complete or fail event.
• The events go to the monitor with the key send-invoices. If no monitor has this key, Cronitor creates one on the first event.

For Sidekiq, use sidekiq-cronitor.

To send the events yourself, use a Cronitor::Monitor:

monitor = Cronitor::Monitor.new('send-invoices')
monitor.ping(state: 'run')
monitor.ping(state: 'complete') # or state: 'fail'

Send a heartbeat

Send a ping each time the process completes a unit of useful work:

require 'cronitor'

monitor = Cronitor::Monitor.new('queue-worker')
monitor.ping(message: 'Alive!')

To attach metrics, give a metrics hash. The SDK sends each item as metric=name:value:

monitor.ping(metrics: { count: 100, error_count: 3 })

If you only want to record custom metrics, use a heartbeat monitor. See Custom Metrics.

Verify

After one real run, check the state of the monitor. A successful telemetry response shows only that Cronitor received the request. It does not show that Cronitor stored the event or matched it to a monitor.

With the MCP server:

get_status({"key": "send-invoices"})

With CronitorCLI:

cronitor status send-invoices

If CRONITOR_API_KEY is not set, the SDK logs No API key detected and sends no events. The job still runs.

Reference

• cronitor-ruby on GitHub: the full README, including YAML configuration.
• Telemetry API: the events and parameters that the SDK sends.