Requirements

Rails Pulse requires:

• Ruby 3.1+
• Rails 7.2+
• Database: SQLite, PostgreSQL, or MySQL (MariaDB is not supported)

Already running Rails Pulse? See Upgrading. Moving from 0.3.x to 0.4.0 needs a one-time route migration.

Installation Steps

1. Add the Gem

Add Rails Pulse to your application’s Gemfile:

# Gemfile
gem 'rails_pulse'

2. Install the Gem

Run bundle install:

bundle install

3. Generate Installation Files

Generate the Rails Pulse configuration and database files:

# Install with single database setup (default - recommended)
rails generate rails_pulse:install

# Or install with separate database setup
rails generate rails_pulse:install --database=separate

4. Run Migrations

For single database setup (default):

rails db:migrate

For separate database setup:

1. Add a rails_pulse entry to config/database.yml with migrations_paths: db/rails_pulse_migrate and schema_dump: false
2. Uncomment config.connects_to in the initializer
3. Run: rails db:prepare to create the database and load the schema

See the Database Setup documentation for full configuration examples.

5. Mount the Engine

Add the Rails Pulse route to your application:

# config/routes.rb
Rails.application.routes.draw do
  mount RailsPulse::Engine => "/rails_pulse"
end

Quick Setup

Rails Pulse automatically starts collecting performance data once installed. Access your monitoring dashboard at:

http://localhost:3000/rails_pulse

Authentication is on by default outside development and test. Before deploying, set config.authorize in the initializer or you will be met with an HTTP Basic prompt that denies everyone until RAILS_PULSE_PASSWORD is set. See Authentication.

Database Setup Options

Single Database (default): Rails Pulse tables are created in your main database - no additional configuration needed.

Separate Database: See the Database Setup section for setup instructions.

Schedule Background Jobs

Rails Pulse uses two background jobs to maintain performance data. Schedule them using your preferred job scheduler (cron, whenever, solid_queue, etc.):

# Schedule to run 5 minutes past every hour
# cron: 5 * * * *
RailsPulse::SummaryJob.perform_later

# Schedule to run daily
# cron: 0 1 * * *
RailsPulse::CleanupJob.perform_later

Basic Configuration

The installation generator creates config/initializers/rails_pulse.rb with sensible defaults. Here are some common configuration options:

# config/initializers/rails_pulse.rb
RailsPulse.configure do |config|
  # Enable or disable Rails Pulse
  config.enabled = true

  # Write inline in tests, where threads share one database connection
  config.async = false if Rails.env.test?

  # Set performance thresholds (in milliseconds)
  config.request_thresholds = {
    slow: 700,
    very_slow: 2000,
    critical: 4000
  }

  # Track background jobs (opt-in)
  config.track_jobs = true

  # Track unhandled exceptions (new installs default to true)
  config.track_exceptions = true
  config.capture_exception_params = true  # filtered via Rails' filter_parameters

  # Protect the dashboard
  config.authorize = ->(controller) { controller.current_user&.admin? }

  # Enable automatic cleanup
  config.archiving_enabled = true
end

For complete configuration options, see the Advanced Configuration documentation.

Next Steps

Explore Features

Learn about the dashboard, SQL tracking, background job monitoring, exception tracking, and more.

View Features →

Secure Your Dashboard

Set up authentication to protect access to your monitoring dashboard.

Setup Authentication →