Skip to main content

​
Breadcrumbs

Breadcrumbs are a trail of events that happened before an error occurred. They help you understand the sequence of actions that led to the error.

​
Automatic Breadcrumbs

Reflex automatically captures:
  • HTTP requests - Outgoing API calls
  • SQL queries - Database operations
  • Console logs - Rails.logger output
  • Navigation - Controller actions

​
Manual Breadcrumbs

Add custom breadcrumbs: 
BrainzLab::Reflex.add_breadcrumb(
  message: "User clicked checkout",
  category: "ui",
  data: { cart_items: 3 }
)

​
Categories

Use categories to organize breadcrumbs:
CategoryUse Case
httpHTTP requests
queryDatabase queries
uiUser interactions
navigationPage/route changes
userUser actions
consoleLog messages

​
Info (default)

General information: 
BrainzLab::Reflex.add_breadcrumb(
  message: "Cache miss",
  category: "cache",
  level: :info
)

​
Warning

Something unexpected: 
BrainzLab::Reflex.add_breadcrumb(
  message: "Retry attempt 2 of 3",
  category: "http",
  level: :warning
)

​
Error

An error occurred: 
BrainzLab::Reflex.add_breadcrumb(
  message: "Payment declined",
  category: "payment",
  level: :error,
  data: { reason: "insufficient_funds" }
)

​
Example Timeline

When an error is captured, you’ll see breadcrumbs like: 
10:00:00.000  [navigation]  GET /checkout
10:00:00.050  [query]       SELECT * FROM carts WHERE id = 123
10:00:00.100  [ui]          User clicked "Place Order"
10:00:00.150  [http]        POST https://api.stripe.com/v1/charges
10:00:00.500  [error]       StripeError: Card declined
By default, Reflex keeps the last 100 breadcrumbs. Configure this: 
BrainzLab.configure do |config|
  config.reflex_max_breadcrumbs = 50
end

​
Filtering Breadcrumbs

Exclude certain breadcrumbs: 
BrainzLab.configure do |config|
  config.reflex_breadcrumb_filter = ->(crumb) {
    # Return false to exclude
    return false if crumb[:category] == "query" &&
                    crumb[:message].include?("sessions")
    true
  }
end
Breadcrumbs are cleared between jobs. Set job context: 
class PaymentJob < ApplicationJob
  def perform(order_id)
    BrainzLab::Reflex.add_breadcrumb(
      message: "Job started",
      category: "job",
      data: { order_id: order_id }
    )

    order = Order.find(order_id)

    BrainzLab::Reflex.add_breadcrumb(
      message: "Processing payment",
      category: "payment",
      data: { amount: order.total }
    )

    process_payment(order)
  end
end

​
HTTP Request Breadcrumbs

Automatically captured for Faraday, HTTParty, Net::HTTP: 
# This HTTP call is automatically recorded
response = Faraday.get("https://api.example.com/data")

# Breadcrumb created:
# [http] GET https://api.example.com/data -> 200 (150ms)

​
SQL Query Breadcrumbs

Automatically captured: 
User.find(123)
# Breadcrumb: [query] SELECT * FROM users WHERE id = 123 (2ms)

​
Truncating Long Queries

BrainzLab.configure do |config|
  config.reflex_breadcrumb_sql_limit = 500  # characters
end