Rails error tracking installation

Add both gems to your Gemfile:

gem 'posthog-ruby'
gem 'posthog-rails'

Then run:

bundle install

Run the install generator to create the PostHog initializer:

rails generate posthog:install

This creates config/initializers/posthog.rb with sensible defaults.

Edit the generated initializer at config/initializers/posthog.rb:

# Rails-specific configuration
PostHog::Rails.configure do |config|
  config.auto_capture_exceptions = true           # Enable automatic exception capture
  config.report_rescued_exceptions = true         # Report exceptions Rails rescues
  config.auto_instrument_active_job = true        # Instrument background jobs
  config.capture_user_context = true              # Include user info in exceptions
  config.current_user_method = :current_user      # Method to get current user
end

# Core PostHog client initialization
PostHog.init do |config|
  config.api_key = ENV['POSTHOG_API_KEY']
  config.host = 'https://us.i.posthog.com'

  config.on_error = proc { |status, msg|
    Rails.logger.error("PostHog error: #{msg}")
  }
end

You can find your project API key and instance address in your project settings.

Note: We recommend using environment variables for API keys rather than hardcoding them.

In a Rails console, verify that PostHog is initialized:

Rails.console
> PostHog.initialized?
=> true

Automatic exception capture is enabled by setting auto_capture_exceptions = true in your configuration. When enabled, exceptions are automatically captured:

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    # Any exception here is automatically captured
  end
end

Understanding exception tracking options

auto_capture_exceptions - Master switch for all automatic error tracking (default: false)

• When true: All exceptions are automatically captured and sent to PostHog
• When false (default): No automatic error tracking (you must manually call PostHog.capture_exception)

report_rescued_exceptions - Control exceptions that Rails handles gracefully (default: false)

• When true: Capture exceptions that Rails rescues and shows error pages for (404s, 500s, etc.)
• When false (default): Only capture truly unhandled exceptions that crash your app

Recommendation: Enable both options to get complete visibility into all errors.

When auto_instrument_active_job is enabled, ActiveJob exceptions are automatically captured with job context:

class EmailJob < ApplicationJob
  def perform(user_id)
    user = User.find(user_id)
    UserMailer.welcome(user).deliver_now
    # Exceptions are automatically captured
  end
end

Associating jobs with users

By default, PostHog extracts a distinct_id from job arguments by looking for a user_id key:

ProcessOrderJob.perform_later(order.id, user_id: current_user.id)

For more control, use the posthog_distinct_id class method:

class SendWelcomeEmailJob < ApplicationJob
  posthog_distinct_id ->(user, options) { user.id }

  def perform(user, options = {})
    UserMailer.welcome(user).deliver_now
  end
end

Note: Currently only ActiveJob is supported. Support for other job runners (Sidekiq, Resque, Good Job, etc.) is planned for future releases.

PostHog Rails automatically captures user information from your controllers. By default, it uses the current_user method.

If your user method has a different name:

PostHog::Rails.config.current_user_method = :logged_in_user

PostHog auto-detects the user's distinct ID by trying these methods on your user object:

1. posthog_distinct_id – Define this on your User model for full control
2. distinct_id – Common analytics convention
3. id – Standard ActiveRecord primary key

You can configure a specific method:

PostHog::Rails.config.user_id_method = :email

Or define a method on your User model:

class User < ApplicationRecord
  def posthog_distinct_id
    "user_#{id}"
  end
end

PostHog integrates with Rails' built-in error reporting (Rails 7.0+):

# These errors are automatically sent to PostHog
Rails.error.handle do
  # Code that might raise an error
end

Rails.error.record(exception, context: { user_id: current_user.id })

PostHog automatically extracts the user's distinct ID from user_id or distinct_id in the context hash.

For exceptions you handle but still want to track:

begin
  # risky code
rescue => e
  PostHog.capture_exception(
    e,
    current_user.id,
    { custom_property: 'value' }
  )
  # handle the error gracefully
end

Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

The following exceptions are not reported by default:

• AbstractController::ActionNotFound
• ActionController::BadRequest
• ActionController::InvalidAuthenticityToken
• ActionController::RoutingError
• ActionController::UnknownFormat
• ActiveRecord::RecordNotFound

Add more with:

PostHog::Rails.config.excluded_exceptions = ['MyException']