Installation

# Gemfile
gem "beacon-rails"

bundle install

Configuration

Create an initializer to configure the client.

# config/initializers/beacon.rb
Beacon.configure do |config|
  config.token     = ENV["BEACON_API_TOKEN"]
  config.base_url  = ENV.fetch("BEACON_BASE_URL", "https://app.beaconstatus.com")
  config.page_slug = ENV["BEACON_PAGE_SLUG"]
end

Create an incident

Beacon.create_incident(
  title: "Database connection errors",
  impact: "major",
  state: "investigating",
  message: "Elevated connection timeouts from primary DB."
)

Update component status

Beacon.update_component(component_id, status: "degraded")

Resolve an incident

Beacon.resolve_incident(incident_id,
  message: "Database connections restored after failover."
)

Heartbeat with Sidekiq

class InvoiceProcessingJob
  include Sidekiq::Job

  def perform
    process_invoices
    Beacon.heartbeat("invoice-processing-token")
  end
end

Exception handler

class ApplicationController < ActionController::Base
  rescue_from StandardError do |e|
    if e.is_a?(CriticalDatabaseError)
      Beacon.create_incident(
        title: "Critical database failure",
        impact: "critical"
      )
    end
    raise e
  end
end

Async mode

By default, API calls are dispatched in a background thread so they never block your request cycle. Set config.async = false for synchronous calls.

Features

• Zero dependencies (Net::HTTP from Ruby stdlib)
• Thread-safe async mode
• Auto-configures from environment variables
• Never raises exceptions — rescues and logs
• Works with Rails 7+, Ruby 3.1+
• Railtie for automatic initialization