Skip to main content

​
Ruby SDK Installation

​
Requirements

  • Ruby 3.1+
  • Rails 7.0+ (for auto-integration)
  • Bundler 2.0+

​
Installation

Add to your Gemfile:
Gemfile
gem 'brainzlab'
Run: 
bundle install

​
Quick Setup

Run the install generator: 
rails generate brainzlab:install
Options:
  • --key=YOUR_KEY - Set your secret key directly
  • --replace-logger - Replace Rails.logger to send all logs to Recall
# With options
rails generate brainzlab:install --replace-logger

​
Manual Configuration

​
Basic Configuration

config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  # Required: Your secret key from the dashboard
  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']

  # Optional: Override environment detection
  config.environment = Rails.env

  # Optional: Service name (defaults to app name)
  config.service = 'my-app'
end

​
Full Configuration Options

config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  # Authentication
  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']

  # Environment
  config.environment = Rails.env
  config.service = 'my-app'
  config.host = Socket.gethostname

  # Git context (auto-detected if not set)
  config.commit = ENV['GIT_COMMIT']
  config.branch = ENV['GIT_BRANCH']

  # Product URLs (only for self-hosting)
  # Via Traefik subdomains (production)
  config.recall_url = 'https://recall.mycompany.com'
  config.reflex_url = 'https://reflex.mycompany.com'
  config.pulse_url  = 'https://pulse.mycompany.com'

  # Or via direct ports (local development)
  # config.recall_url = 'http://localhost:3001'
  # config.reflex_url = 'http://localhost:3002'
  # config.pulse_url  = 'http://localhost:3003'

  # Recall settings
  config.recall_enabled = true
  config.recall_min_level = :debug  # :debug, :info, :warn, :error, :fatal
  config.recall_buffer_size = 50
  config.recall_flush_interval = 5

  # Reflex settings
  config.reflex_enabled = true
  config.reflex_excluded_exceptions = ['ActionController::RoutingError']
end

​
Environment Variables

You can also configure via environment variables: 
BRAINZLAB_SECRET_KEY=sk_live_xxx
BRAINZLAB_ENVIRONMENT=production
BRAINZLAB_SERVICE=my-app

# Git context
GIT_COMMIT=abc123
GIT_BRANCH=main

# Self-hosting (Traefik subdomains)
RECALL_URL=https://recall.mycompany.com
REFLEX_URL=https://reflex.mycompany.com
PULSE_URL=https://pulse.mycompany.com

# Self-hosting (direct ports for local dev)
# RECALL_URL=http://localhost:3001
# REFLEX_URL=http://localhost:3002
# PULSE_URL=http://localhost:3003

​
Rails Auto-Integration

The SDK automatically:
  1. Captures request context - request ID, path, method added to all logs
  2. Captures errors - unhandled exceptions are reported to Reflex
  3. Identifies users - if you set current_user, it’s included in reports

​
Setting User Context

app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_brainzlab_user

  private

  def set_brainzlab_user
    if current_user
      BrainzLab.set_user(
        id: current_user.id,
        email: current_user.email,
        name: current_user.name
      )
    end
  end
end

​
Verify Installation

Check that everything is working: 
# In Rails console
BrainzLab::Recall.info("Test log from console")
BrainzLab::Reflex.capture_message("Test error message")
Then check your dashboard to see the events.

​
Troubleshooting

​
Logs Not Appearing

  1. Check your API key is correct
  2. Verify recall_enabled is true
  3. Check the minimum log level

​
Errors Not Captured

  1. Check your API key is correct
  2. Verify reflex_enabled is true
  3. Check reflex_excluded_exceptions

​
Need Help?

Support

Get help from the Brainz Lab team