BrainzLab Ruby SDK

gem 'brainzlab'

source "https://rubygems.pkg.github.com/brainz-lab" do
  gem 'brainzlab'
end

# config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  # Authentication (required) - Your Platform API key
  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']

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

  # Enable/disable products
  config.recall_enabled = true   # Logging
  config.reflex_enabled = true   # Error tracking
  config.pulse_enabled = true    # APM

  # Auto-provisioning (creates projects automatically)
  config.recall_auto_provision = true
  config.reflex_auto_provision = true
  config.pulse_auto_provision = true
end

# Log levels
BrainzLab::Recall.debug("Debug message", details: "...")
BrainzLab::Recall.info("User signed up", user_id: user.id)
BrainzLab::Recall.warn("Rate limit approaching", current: 95, limit: 100)
BrainzLab::Recall.error("Payment failed", error: e.message, amount: 99.99)
BrainzLab::Recall.fatal("Database connection lost")

# With context
BrainzLab::Recall.info("Order created",
  order_id: order.id,
  user_id: user.id,
  total: order.total,
  items: order.items.count
)

config.recall_min_level = :info        # Minimum log level (:debug, :info, :warn, :error, :fatal)
config.recall_buffer_size = 50         # Batch size before flush
config.recall_flush_interval = 5       # Seconds between flushes

# Capture exceptions
begin
  risky_operation
rescue => e
  BrainzLab::Reflex.capture(e,
    user_id: current_user.id,
    order_id: order.id
  )
end

# Add breadcrumbs for context
BrainzLab::Reflex.add_breadcrumb("User clicked checkout",
  category: "ui.click",
  data: { button: "checkout" }
)

# Set user context
BrainzLab::Reflex.set_user(
  id: user.id,
  email: user.email,
  plan: user.plan
)

# Add tags
BrainzLab::Reflex.set_tags(
  environment: "production",
  region: "us-east-1"
)

config.reflex_excluded_exceptions = ['ActiveRecord::RecordNotFound']
config.reflex_sample_rate = 1.0        # 1.0 = 100%, 0.5 = 50%
config.reflex_before_send = ->(event) {
  # Modify or filter events
  event[:tags][:custom] = 'value'
  event  # Return nil to drop the event
}

# Enable/disable specific instrumentations
config.instrument_http = true           # Net::HTTP, Faraday, HTTParty
config.instrument_active_record = true  # SQL queries
config.instrument_redis = true          # Redis commands
config.instrument_sidekiq = true        # Sidekiq jobs
config.instrument_graphql = true        # GraphQL queries
config.instrument_mongodb = true        # MongoDB operations
config.instrument_elasticsearch = true  # Elasticsearch queries
config.instrument_action_mailer = true  # Email delivery
config.instrument_delayed_job = true    # Delayed::Job
config.instrument_grape = true          # Grape API

# Filtering
config.http_ignore_hosts = ['localhost', '127.0.0.1']
config.redis_ignore_commands = ['ping', 'info']
config.pulse_excluded_paths = ['/health', '/ping', '/up', '/assets']
config.pulse_sample_rate = 1.0          # 1.0 = 100%

# Extracting trace context from incoming requests (automatic in Rails)
context = BrainzLab::Pulse.extract!(request.headers)

# Injecting trace context into outgoing requests (automatic with instrumentation)
BrainzLab::Pulse.inject!(headers)

BrainzLab::Pulse.trace("process_payment", kind: "payment") do |span|
  span[:data] = { amount: 99.99, currency: "USD" }
  process_payment(order)
end

class ApplicationController < ActionController::Base
  before_action :set_brainzlab_context

  private

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

# config/initializers/sidekiq.rb
# Instrumentation is automatic, but you can configure:

BrainzLab.configure do |config|
  config.instrument_sidekiq = true
end

class API < Grape::API
  use BrainzLab::Instrumentation::GrapeInstrumentation::Middleware

  # Your API endpoints...
end

class MySchema < GraphQL::Schema
  trace_with BrainzLab::Instrumentation::GraphQLInstrumentation::Tracer

  # Your schema...
end

config.scrub_fields = [:password, :password_confirmation, :token, :api_key, :secret]

# In your initializer
BrainzLab.configure do |config|
  config.debug = true
end

# Or via environment variable
# BRAINZLAB_DEBUG=true

BrainzLab.configure do |config|
  config.debug = true
  config.logger = Rails.logger
  # Or any Logger-compatible object
  config.logger = Logger.new('log/brainzlab.log')
end

BrainzLab.configure do |config|
  # Called before each API request
  config.on_send = ->(service, method, path, payload) {
    Rails.logger.debug "[BrainzLab] Sending to #{service}: #{method} #{path}"

    # You can use this to:
    # - Log all outgoing requests
    # - Send metrics to your monitoring system
    # - Add custom tracing
  }

  # Called when an SDK error occurs
  config.on_error = ->(error, context) {
    Rails.logger.error "[BrainzLab] Error in #{context[:service]}: #{error.message}"

    # You can use this to:
    # - Alert on SDK failures
    # - Track error rates
    # - Fallback to alternative logging

    # Note: This is for SDK errors, not application errors
    # Application errors are sent to Reflex as normal
  }
end

# Log a debug message (only outputs when debug=true)
BrainzLab::Debug.log("Custom message", level: :info)
BrainzLab::Debug.log("Something went wrong", level: :error, error_code: 500)

# Measure operation timing
BrainzLab::Debug.measure(:custom, "expensive_operation") do
  # Your code here
end

# Check if debug mode is enabled
if BrainzLab::Debug.enabled?
  # Perform additional debug operations
end

# config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  # Enable development mode (works offline)
  config.mode = :development

  # Optional: customize the SQLite database path (default: tmp/brainzlab.sqlite3)
  config.development_db_path = 'tmp/brainzlab_dev.sqlite3'

  # Other settings still apply
  config.environment = Rails.env
  config.service = 'my-app'
end

# Get all events
events = BrainzLab.development_events

# Filter by service
logs = BrainzLab.development_events(service: :recall)
errors = BrainzLab.development_events(service: :reflex)
traces = BrainzLab.development_events(service: :pulse)

# Filter by event type
BrainzLab.development_events(event_type: 'log')
BrainzLab.development_events(event_type: 'error')
BrainzLab.development_events(event_type: 'trace')

# Filter by time
BrainzLab.development_events(since: 1.hour.ago)

# Limit results
BrainzLab.development_events(limit: 10)

# Combine filters
BrainzLab.development_events(
  service: :recall,
  since: 30.minutes.ago,
  limit: 50
)

# Get stats by service
BrainzLab.development_stats
# => { recall: 42, reflex: 3, pulse: 15 }

# Clear all stored events
BrainzLab.clear_development_events!

BrainzLab.configure do |config|
  config.recall_url = 'https://recall.your-domain.com'
  config.reflex_url = 'https://reflex.your-domain.com'
  config.pulse_url = 'https://pulse.your-domain.com'
end