Ruby SDK

The official Ruby SDK for Checkend error monitoring. Capture exceptions and send custom notifications from your Ruby applications.

Installation

Add the gem to your Gemfile:

Gemfile

gem 'checkend-ruby'

Then run:

Terminal

bundle install

Configuration

Configure the SDK with your API key and endpoint. In Rails, create an initializer:

config/initializers/checkend.rb

Checkend.configure do |config|
  config.api_key = ENV['CHECKEND_API_KEY']
  config.endpoint = ENV['CHECKEND_ENDPOINT']
  config.environment = Rails.env
end

Environment Variables

The SDK automatically reads CHECKEND_API_KEY and CHECKEND_ENDPOINT from your environment if not explicitly configured.

Reporting Exceptions

The most common way to report errors is by passing an exception object:

Ruby

begin
  # Your code that might raise an exception
  user.process_payment!
rescue => exception
  Checkend.notify(exception)
  raise # Re-raise if you want the error to propagate
end

You can add additional context, user information, and tags:

Ruby

Checkend.notify(exception,
  context: { order_id: order.id, amount: order.total },
  user: { id: current_user.id, email: current_user.email },
  tags: %w[payments critical],
  fingerprint: "payment-error-#{order.id}"
)

Custom Notifications

You can send notifications without an exception object. This is useful for tracking custom events, warnings, or business rule violations that don't raise exceptions.

String Messages

Pass a string message directly to notify:

Ruby

# Simple message (uses default error class 'Checkend::Notice')
Checkend.notify("User exceeded API rate limit")

# With custom error class
Checkend.notify("User exceeded API rate limit",
  error_class: "RateLimitExceeded"
)

# With full context
Checkend.notify("Suspicious login attempt detected",
  error_class: "SecurityAlert",
  context: { ip_address: request.ip, attempts: 5 },
  user: { id: user.id, email: user.email },
  tags: %w[security high-priority]
)

Hash Payloads

For full control over the notification, pass a hash with error details:

Ruby

Checkend.notify({
  error_class: "DataValidationError",
  message: "Invalid email format in bulk import",
  backtrace: caller  # Optional: include current stack trace
})

# Combine hash with additional options
Checkend.notify(
  { error_class: "BusinessRuleViolation", message: "Order total exceeds limit" },
  context: { order_id: 123, limit: 10_000, actual: 15_000 },
  tags: %w[orders validation]
)

Use Cases for Custom Notifications

Security events (failed logins, suspicious activity)
Business rule violations
Data validation warnings
Performance threshold alerts
Third-party API failures that don't raise exceptions

Synchronous Sending

By default, notifications are sent asynchronously in a background thread. Use notify_sync when you need to confirm delivery:

Ruby

# Useful for CLI tools, tests, or critical errors
result = Checkend.notify_sync(exception)

# Also works with string messages
result = Checkend.notify_sync("Critical system alert",
  error_class: "SystemAlert"
)

Thread-Local Context

Set context that automatically applies to all notifications in the current thread:

Ruby

# In a before_action or middleware
Checkend.set_context(
  tenant_id: current_tenant.id,
  request_id: request.request_id
)

Checkend.set_user(
  id: current_user.id,
  email: current_user.email,
  name: current_user.name
)

# All subsequent notify calls include this context automatically
Checkend.notify(exception)  # Includes tenant_id, request_id, and user

# Clear at the end of the request
Checkend.clear!

Before-Notify Callbacks

Ruby

Checkend.configure do |config|
  # Add extra context to all notifications
  config.before_notify << ->(notice) {
    notice.context[:app_version] = MyApp::VERSION
    notice.context[:server] = Socket.gethostname
    true  # Return true to send, false to skip
  }

  # Filter out specific errors
  config.before_notify << ->(notice) {
    # Don't report canceled requests
    return false if notice.error_class == "ActionController::RoutingError"
    true
  }
end

Rails Integration

The SDK automatically integrates with Rails when detected:

Catches unhandled exceptions via Rack middleware
Captures request information (URL, method, params, headers)
Respects Rails environment settings
Works with ActiveJob and Sidekiq out of the box

Automatic Error Capture

With Rails integration enabled, unhandled exceptions are automatically reported. You only need to call Checkend.notify for errors you rescue and handle yourself.

Configuration Options

Option	Default	Description
api_key	ENV['CHECKEND_API_KEY']	Your Checkend ingestion API key
endpoint	ENV['CHECKEND_ENDPOINT']	Your Checkend server URL
environment	Rails.env or 'development'	Environment name included in reports
enabled	true in production/staging	Enable/disable error reporting
async	true	Send notifications in background thread
ignored_exceptions	[]	Exception classes to ignore
filter_keys	[:password, :token, ...]	Keys to scrub from context/params

Next steps

Learn about error grouping Using tags for filtering API reference