Ruby SDK

Installation

Install via gem:

gem install cronbeats-ruby

Requirements: Ruby 2.7 or higher

Quick Start

Send a simple ping to mark your cron job as successful:

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.ping

# Done! CronBeats knows your job ran successfully.

Sending Pings

Simple Ping

Send a single heartbeat when your job completes:

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.ping

Start & End Signals

Track execution time by signaling when your job starts and ends:

client = CronBeatsRuby::PingClient.new("YCrXzYbV")

client.start
# ... do your work ...
client.success  # or client.fail on error

Real-World Cron Job Example

Complete example with error handling:

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.start

begin
  # Your actual cron job work
  process_emails
  generate_reports
  cleanup_temp_files
  
  client.success
rescue StandardError => e
  client.fail
  puts "Error: #{e.message}"
  exit 1
end

Progress Tracking

Send real-time progress updates from long-running jobs. CronBeats displays a live progress bar and status message on your dashboard.

📊 Two Progress Modes

Mode 1: With Percentage — client.progress(50, "message")

Dashboard shows progress bar (0-100%) + your message. Use when you can calculate meaningful progress.

Mode 2: Message Only — client.progress(message: "...")

Dashboard shows only your status message (no percentage bar). Use for status updates without measurable progress.

Basic Progress Update

# Send progress percentage (0-100) with status message
client.progress(50, "Processing batch 50/100")

# Using hash syntax
client.progress({
  seq: 75,
  message: "Almost done"
})

Processing Records Example

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.start

total = 10_000
(1..total).each do |i|
  process_record(i)
  
  # Update progress every 500 records
  if (i % 500).zero?
    percent = (i * 100 / total).to_i
    client.progress(percent, "Processed #{i.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse} / #{total.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse} records")
  end
end

client.progress(100, "All records processed")
client.success

Rails Rake Task

# lib/tasks/backup.rake

require "cronbeats_ruby"

namespace :backup do
  desc "Backup database with CronBeats monitoring"
  task database: :environment do
    client = CronBeatsRuby::PingClient.new(ENV["CRONBEATS_JOB_KEY"])
    client.start
    
    begin
      puts "Starting backup..."
      # Your backup logic
      system("pg_dump mydb > backup.sql")
      client.progress(50, "Database dumped")
      
      system("gzip backup.sql")
      client.progress(100, "Backup complete")
      
      client.success
      puts "Backup completed successfully"
    rescue StandardError => e
      client.fail
      puts "Backup failed: #{e.message}"
      raise
    end
  end
end

Error Handling

The SDK raises typed exceptions for validation and API errors:

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")

begin
  client.ping
  
rescue CronBeatsRuby::ValidationError => e
  # Invalid job key format or parameters (client-side)
  puts "Validation error: #{e.message}"
  
rescue CronBeatsRuby::ApiError => e
  # API/network issue with normalized metadata
  puts "API error: #{e.code}"        # e.g. 'RATE_LIMITED'
  puts "HTTP status: #{e.http_status}" # e.g. 429
  puts "Retryable: #{e.retryable}"     # boolean
end

API Reference

Method	Description
`ping`	Send a simple heartbeat ping
`start`	Signal job start and begin execution timer
`end(status)`	Signal job end with status ("success" or "fail")
`success`	Alias for end("success")
`fail`	Alias for end("fail")
`progress(seq, msg = nil)`	Send progress update (0-100) with optional status message

For complete API documentation, see the GitHub repository.

Configuration Options

Customize the client behavior:

client = CronBeatsRuby::PingClient.new("YCrXzYbV", {
  base_url: "https://cronbeats.io",  # Default
  timeout_ms: 5000,                   # Default: 5 seconds
  max_retries: 2                      # Default: 2 retries
})

Note: The default 5-second timeout ensures the SDK never blocks your cron job if CronBeats is unreachable. Adjust only if you need longer waits.

Complete Examples

Processing Records with Progress

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.start

total = 10_000
(1..total).each do |i|
  process_record(i)
  
  # Update progress every 500 records
  if (i % 500).zero?
    percent = (i * 100 / total).to_i
    client.progress(percent, "Processed #{i} / #{total} records")
  end
end

client.progress(100, "All records processed")
client.success

Rails Background Job

# app/jobs/backup_job.rb

class BackupJob < ApplicationJob
  queue_as :default
  
  def perform
    client = CronBeatsRuby::PingClient.new(ENV["CRONBEATS_JOB_KEY"])
    client.start
    
    begin
      Rails.logger.info "Starting backup..."
      # Your backup logic
      BackupService.perform
      
      client.success
      Rails.logger.info "Backup completed"
    rescue StandardError => e
      client.fail
      Rails.logger.error "Backup failed: #{e.message}"
      raise
    end
  end
end

Standalone Script

#!/usr/bin/env ruby

require "cronbeats_ruby"

client = CronBeatsRuby::PingClient.new("YCrXzYbV")
client.start

stages = [
  { pct: 0, msg: "Connecting to database", fn: :connect_db },
  { pct: 25, msg: "Fetching records", fn: :fetch_records },
  { pct: 50, msg: "Processing data", fn: :process_data },
  { pct: 75, msg: "Writing results", fn: :write_results }
]

stages.each do |stage|
  client.progress(stage[:pct], stage[:msg])
  send(stage[:fn])
end

client.progress(100, "Job complete")
client.success