AIVory Monitor - Ruby Agent

Real-time exception monitoring with AI-powered analysis for Ruby applications. Captures exceptions, stack traces, and local variables with zero performance impact.

• Ruby 2.7 or higher
• Network access to AIVory backend (wss://api.aivory.net)

gem install aivory_monitor

Add to your Gemfile:

gem 'aivory_monitor'

Then run:

bundle install

Initialize the agent at the start of your application:

require 'aivory_monitor'

AIVoryMonitor.init(
  api_key: 'your-api-key',
  environment: 'production'
)

Set environment variables and initialize without arguments:

export AIVORY_API_KEY=your-api-key
export AIVORY_ENVIRONMENT=production

require 'aivory_monitor'

AIVoryMonitor.init

Capture exceptions manually with additional context:

begin
  risky_operation
rescue => e
  AIVoryMonitor.capture_exception(e, {
    user_id: current_user.id,
    request_id: request.uuid,
    custom_data: { foo: 'bar' }
  })
  raise
end

Associate exceptions with specific users:

AIVoryMonitor.set_user({
  id: user.id,
  email: user.email,
  username: user.username
})

Add persistent context sent with all captures:

AIVoryMonitor.set_context({
  version: '1.2.3',
  region: 'us-west-2',
  tenant: 'acme-corp'
})

The agent automatically integrates with Rails. Add to your Gemfile:

gem 'aivory_monitor'

Create config/initializers/aivory_monitor.rb:

AIVoryMonitor.init(
  api_key: ENV['AIVORY_API_KEY'],
  environment: Rails.env,
  application_name: 'my-rails-app'
)

The agent will automatically capture:

• Controller exceptions with request parameters
• Background job failures (Sidekiq)
• Uncaught exceptions throughout the application

require 'sinatra'
require 'aivory_monitor'

AIVoryMonitor.init(
  api_key: ENV['AIVORY_API_KEY'],
  environment: ENV['RACK_ENV'] || 'development',
  application_name: 'my-sinatra-app'
)

error do
  exception = env['sinatra.error']
  AIVoryMonitor.capture_exception(exception, {
    path: request.path,
    method: request.request_method,
    params: params
  })
  'Internal Server Error'
end

get '/' do
  'Hello World'
end

For other Rack-based frameworks:

require 'aivory_monitor'

AIVoryMonitor.init

use Rack::Builder do
  use Rack::CommonLogger

  run lambda { |env|
    begin
      # Your application code
      [200, {'Content-Type' => 'text/plain'}, ['OK']]
    rescue => e
      AIVoryMonitor.capture_exception(e, {
        path: env['PATH_INFO'],
        method: env['REQUEST_METHOD']
      })
      raise
    end
  }
end

The agent can be configured using environment variables or initialization parameters.

AIVoryMonitor.init(
  api_key: 'your-api-key',
  backend_url: 'wss://api.aivory.net/ws/monitor/agent',
  environment: 'production',
  application_name: 'my-app',
  sampling_rate: 1.0,
  max_variable_depth: 3,
  debug: false,
  enable_breakpoints: true
)

Clone the repository and build the gem:

git clone https://github.com/aivory/aivory-monitor.git
cd aivory-monitor/monitor-agents/agent-ruby
bundle install
gem build aivory_monitor.gemspec
gem install aivory_monitor-1.0.0.gem

bundle exec rspec

bundle exec rubocop

The AIVory Monitor Ruby agent uses standard Ruby exception handling mechanisms to capture runtime errors:

1. At-Exit Hooks: Registers an at_exit handler to capture unhandled exceptions before the process terminates.

2. Thread Exception Reporting: Hooks into Thread.report_on_exception to capture exceptions in background threads.

3. Exception Capture: When an exception occurs:

   • Captures the full stack trace with file names and line numbers
   • Extracts local variables at each stack frame (up to configured depth)
   • Collects thread information and system context
   • Serializes the data and sends it to the AIVory backend via WebSocket

4. Non-Breaking Operation: All capture operations are non-blocking and designed to have minimal performance impact. Failures in the agent never affect your application.

5. WebSocket Connection: Maintains a persistent connection to the AIVory backend for real-time exception streaming and bidirectional communication (breakpoint commands, configuration updates).

• Automatic initialization via Railtie
• Controller exception capture with request context
• ActionMailer exception capture
• Works with Rails 5.0+

• Automatic middleware injection
• Captures job failures with worker context
• Includes job ID, queue name, and arguments

The agent works with any Ruby application or framework. For frameworks without automatic integration, use manual initialization and exception capture as shown in the usage examples.

Check that the agent is initialized:

puts AIVoryMonitor.initialized?  # Should return true
puts AIVoryMonitor.connected?    # Should return true

Enable debug logging:

AIVoryMonitor.init(
  api_key: 'your-api-key',
  debug: true
)

Verify your API key is correct and the backend URL is reachable:

export AIVORY_DEBUG=true
ruby your_app.rb

Check for firewall rules blocking WebSocket connections to wss://api.aivory.net.

If capturing large objects causes memory issues, reduce the variable capture depth:

AIVoryMonitor.init(
  api_key: 'your-api-key',
  max_variable_depth: 1  # Reduce from default of 3
)

Or enable sampling to capture only a percentage of exceptions:

AIVoryMonitor.init(
  api_key: 'your-api-key',
  sampling_rate: 0.1  # Capture 10% of exceptions
)

Ensure the gem is in your Gemfile and you've run bundle install. Create an initializer at config/initializers/aivory_monitor.rb to explicitly initialize if needed.

The Sidekiq middleware is automatically loaded if Sidekiq is detected. Ensure you're loading the agent before Sidekiq workers start:

# config/initializers/aivory_monitor.rb
AIVoryMonitor.init

• Documentation: https://aivory.net/monitor/docs
• GitHub Issues: https://github.com/aivory/aivory-monitor/issues
• Email: support@aivory.net

MIT License. See LICENSE file for details.