Skip to main content

​
Reflex - Ruby SDK

Complete guide to using Reflex for error tracking in Ruby.

​
Automatic Capture

Errors are automatically captured in Rails:
  • Controller exceptions
  • Background job failures
  • Rake task errors

​
Manual Capture

​
Capture Exceptions

begin
  risky_operation
rescue => e
  BrainzLab::Reflex.capture(e)
end

​
Capture and Re-raise

begin
  risky_operation
rescue => e
  BrainzLab::Reflex.capture(e)
  raise
end

​
Capture Messages

BrainzLab::Reflex.capture_message("Something unexpected",
  level: :warning,
  extra: { details: "..." }
)

​
Adding Context

​
User Context

BrainzLab::Reflex.capture(exception,
  user: {
    id: user.id,
    email: user.email,
    plan: user.plan
  }
)

​
Tags

BrainzLab::Reflex.capture(exception,
  tags: {
    feature: "checkout",
    provider: "stripe"
  }
)

​
Extra Data

BrainzLab::Reflex.capture(exception,
  extra: {
    order_id: order.id,
    amount: order.total,
    items: order.items.map(&:id)
  }
)

​
Full Example

begin
  charge = Stripe::Charge.create(amount: order.total_cents)
rescue Stripe::CardError => e
  BrainzLab::Reflex.capture(e,
    user: { id: current_user.id },
    tags: { feature: "checkout", provider: "stripe" },
    extra: { order_id: order.id, amount: order.total }
  )
  handle_payment_failure
end
Track events leading to errors. Breadcrumbs are automatically captured for:
  • HTTP requests and responses
  • Controller actions
  • Background job executions

​
Manual Breadcrumbs

BrainzLab.add_breadcrumb("User clicked checkout",
  category: "ui",
  level: :info,
  data: { cart_items: 3 }
)

BrainzLab.add_breadcrumb("Debug info", level: :debug)
BrainzLab.add_breadcrumb("User action", level: :info)
BrainzLab.add_breadcrumb("Rate limit warning", level: :warning)
BrainzLab.add_breadcrumb("API error", level: :error)

​
Clear Breadcrumbs

BrainzLab.clear_breadcrumbs!

​
Filtering Errors

​
Exclude Exceptions

BrainzLab.configure do |config|
  config.reflex_excluded_exceptions = [
    'ActionController::RoutingError',
    'ActiveRecord::RecordNotFound'
  ]
end

​
Before Send Hook

Modify or drop error events before sending: 
BrainzLab.configure do |config|
  config.reflex_before_send = ->(payload, exception) {
    # Drop specific errors
    return nil if exception&.message&.include?("expected")

    # Add custom data
    payload[:custom_field] = "added"

    # Return modified payload (or nil to drop)
    payload
  }
end

​
Sampling

Sample high-volume errors: 
BrainzLab.configure do |config|
  config.reflex_sample_rate = 0.5  # 50% of errors
end

​
Disable Capture

Temporarily disable: 
BrainzLab::Reflex.without_capture do
  # Errors here are not reported
  risky_operation
end

​
Testing

RSpec.describe PaymentService do
  it "captures payment errors" do
    expect(BrainzLab::Reflex).to receive(:capture)
      .with(kind_of(Stripe::CardError))

    PaymentService.charge(invalid_card)
  end
end

​
Disable in Tests

# config/environments/test.rb
BrainzLab.configure do |config|
  config.reflex_enabled = false
end