# Ruby SDK

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

## Install

```bash
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:

```ruby
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](https://github.com/cronitorio/sidekiq-cronitor).

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

```ruby
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:

```ruby
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`:

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

If you only want to record custom metrics, use a heartbeat monitor. See [Custom Metrics](https://cronitor.io/docs/custom-metrics.md).

## 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](https://cronitor.io/docs/mcp-server.md):

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

With [CronitorCLI](https://cronitor.io/docs/using-cronitor-cli.md):

```bash
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](https://github.com/cronitorio/cronitor-ruby): the full README, including YAML configuration.
- [Telemetry API](https://cronitor.io/docs/telemetry-api.md): the events and parameters that the SDK sends.