Ruby on Rails

PostHog makes it easy to get data about traffic and usage of your Ruby on Rails app. Integrating PostHog enables analytics, custom event capture, feature flags, and automatic exception tracking.

This guide walks you through integrating PostHog into your Rails app using the posthog-rails gem.

Beta: integration via LLM

Install PostHog for Rails in seconds with our wizard by running this prompt with LLM coding agents like Cursor and Bolt, or by running it in your terminal.

Or, to integrate manually, continue with the rest of this guide.

Features

• Automatic exception tracking – Captures unhandled and rescued exceptions
• ActiveJob instrumentation – Tracks background job exceptions
• User context – Automatically associates exceptions with the current user
• Smart filtering – Excludes common Rails exceptions (404s, etc.) by default
• Request context – Adds request metadata and optional PostHog tracing header identity/session context to captured events
• Rails 7.0+ error reporter – Integrates with Rails' built-in error reporting

Installation

Add both gems to your Gemfile:

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

Then run:

bundle install

Identifying users

Identifying users is required. Backend events need a distinct_id that matches the ID your frontend uses when calling posthog.identify(). Without this, backend events are orphaned — they can't be linked to frontend event captures, session replays, LLM traces, or error tracking.

See our guide on identifying users for how to set this up.

Generate the initializer

Run the install generator to create the PostHog initializer:

rails generate posthog:install

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

Configuration

PostHog.init creates a single client instance used across your app. Avoid creating multiple PostHog::Client instances with the same API key, as this can cause dropped events and inconsistent behavior.

The generated initializer includes the most common options:

# Rails-specific configuration
PostHog::Rails.configure do |config|
  config.auto_capture_exceptions = true           # Enable automatic exception capture (default: false)
  config.report_rescued_exceptions = true         # Report exceptions Rails rescues (default: false)
  config.auto_instrument_active_job = true        # Instrument background jobs (default: false)
  config.use_tracing_headers = true               # Use PostHog tracing headers for identity/session context (default: true)
  config.capture_user_context = true              # Include authenticated user info in exceptions (default: true)
  config.current_user_method = :current_user      # Method to get current user (default: :current_user)
  config.user_id_method = nil                     # Method to get ID from user object (default: auto-detect)

  # Add additional exceptions to ignore
  config.excluded_exceptions = ['MyCustomError']
end

# Core PostHog client initialization
PostHog.init do |config|
  # Required: Your PostHog project API key
  config.api_key = '<ph_project_token>'

  # Optional: Your PostHog instance URL
  config.host = 'https://us.i.posthog.com'

  # Optional: Personal API key for feature flags
  config.personal_api_key = 'phx_xxxxxxxxx'

  # Maximum number of events to queue before dropping (default: 10000)
  config.max_queue_size = 10_000

  # Send events synchronously on the calling thread (default: false)
  config.sync_mode = false

  # Feature flags polling interval in seconds (default: 30)
  config.feature_flags_polling_interval = 30

  # Feature flag request timeout in seconds (default: 3)
  config.feature_flag_request_timeout_seconds = 3

  # Error callback to detect misconfiguration
  config.on_error = proc { |status, msg|
    Rails.logger.error("PostHog error: #{msg}")
  }

  # Before-send callback to modify or drop events
  config.before_send = proc { |event|
    event[:properties] ||= {}
    event[:properties]['environment'] = Rails.env
    event
  }

  # Disable network calls in test mode
  config.test_mode = true if Rails.env.test?
end

You can find your project token and instance address in your project settings.

Tip: Use Rails.application.credentials to avoid hardcoding API keys. First, add your keys and then reference them in your initializer:

Terminal

PostHog AI

rails credentials:edit

config/credentials.yml.enc

PostHog AI

posthog:
  api_key: <ph_project_token>
  host: https://us.i.posthog.com
  personal_api_key: phx_xxxxxxxxx

config/initializers/posthog.rb

PostHog AI

config.api_key = Rails.application.credentials.posthog[:api_key]
config.host = Rails.application.credentials.posthog[:host]
config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]

Capturing events

Track custom events anywhere in your Rails app:

PostHog.capture({
  distinct_id: current_user.id,
  event: 'post_created',
  properties: { title: @post.title }
})

Identify a user and set their person properties:

PostHog.identify({
  distinct_id: current_user.id,
  properties: {
    email: current_user.email,
    plan: current_user.plan
  }
})

The Rails integration delegates methods like capture, identify, alias, group_identify, evaluate_flags, capture_exception, flush, and shutdown to the initialized PostHog::Client.

Request context

PostHog Rails automatically applies request-scoped context to events captured during web requests. Request metadata such as $current_url, $request_method, $request_path, $user_agent, and $ip is added to event properties.

When use_tracing_headers is enabled, PostHog tracing headers (X-PostHog-Distinct-Id and X-PostHog-Session-Id) are also used as default distinct_id and $session_id values. Explicit distinct_id and properties passed to PostHog.capture always take precedence.

Disable tracing header identity/session capture if you do not want client-supplied tracing headers used for server-side events. Request metadata is still captured:

PostHog::Rails.config.use_tracing_headers = false

Error tracking

For full details on setting up error tracking with Rails, see our Rails error tracking installation guide.

Automatic exception tracking

When auto_capture_exceptions is enabled, exceptions are automatically captured:

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

report_rescued_exceptions controls whether exceptions Rails rescues (for example, exceptions rendered by Rails error pages) are captured. Enable it along with auto_capture_exceptions for complete error visibility, or leave it disabled to capture only unhandled exceptions.

Manual exception capture

You can also manually capture exceptions:

PostHog.capture_exception(
  exception,
  current_user.id,
  { custom_property: 'value' }
)

If you evaluated feature flags for the request, pass the same snapshot to include matching flag properties on the exception event:

flags = PostHog.evaluate_flags(current_user.id)

PostHog.capture_exception(
  exception,
  current_user.id,
  { custom_property: 'value' },
  flags: flags
)

Background job exceptions

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 in hash arguments:

# PostHog will automatically use options[:user_id] as the distinct_id
ProcessOrderJob.perform_later(order.id, user_id: current_user.id)

For more control, use the posthog_distinct_id class method. The proc or block receives the same arguments as perform:

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

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

You can also use a block:

class ProcessOrderJob < ApplicationJob
  posthog_distinct_id do |_order, notify_user_id|
    notify_user_id
  end

  def perform(order, notify_user_id)
    # Process the order...
  end
end

Rails 7.0+ error reporter

PostHog integrates with Rails' built-in error reporting:

# 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. Other context keys are included as properties on the exception event.

User context

PostHog Rails automatically captures authenticated user information from your controllers for exceptions. Authenticated Rails user context takes precedence over client-supplied tracing headers for exception identity.

If your user method has a different name, configure it:

PostHog::Rails.config.current_user_method = :logged_in_user

User ID extraction

By default, PostHog Rails auto-detects the user's distinct ID by trying these methods in order:

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
4. pk – Primary key alias
5. uuid – For UUID-based primary keys

It also checks hash-like users for id, pk, and uuid keys.

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}"  # or external_id, or any unique identifier
  end
end

Excluded exceptions

The following exceptions are not reported by default (common 4xx errors):

• AbstractController::ActionNotFound
• ActionController::BadRequest
• ActionController::InvalidAuthenticityToken
• ActionController::InvalidCrossOriginRequest
• ActionController::MethodNotAllowed
• ActionController::NotImplemented
• ActionController::ParameterMissing
• ActionController::RoutingError
• ActionController::UnknownFormat
• ActionController::UnknownHttpMethod
• ActionDispatch::Http::Parameters::ParseError
• ActiveRecord::RecordNotFound
• ActiveRecord::RecordNotUnique

Add more with:

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

Feature flags

Evaluate flags once for the current user, then read values from the returned snapshot:

class PostsController < ApplicationController
  def show
    flags = PostHog.evaluate_flags(current_user.id)

    if flags.enabled?('new-post-design')
      render 'posts/show_new'
    else
      render 'posts/show'
    end
  end
end

For multivariate flags and experiments, use get_flag:

flags = PostHog.evaluate_flags(current_user.id)
variant = flags.get_flag('checkout-experiment')

if variant == 'test'
  # Do something differently
end

When capturing an event after branching on a flag, pass the same flags snapshot so the event includes the exact flag values used by your code:

flags = PostHog.evaluate_flags(current_user.id)

PostHog.capture({
  distinct_id: current_user.id,
  event: 'checkout_started',
  flags: flags.only_accessed
})

For local evaluation, ensure you've set personal_api_key:

config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]

See our Ruby SDK docs for details on local evaluation with Puma and Unicorn servers.

Note: PostHog.is_feature_enabled, PostHog.get_feature_flag, PostHog.get_feature_flag_result, PostHog.get_feature_flag_payload, and PostHog.capture({ ..., send_feature_flags: true }) still work during the migration period, but they're deprecated. Prefer PostHog.evaluate_flags for new code.

Testing

In your test environment, disable network calls with test mode:

PostHog.init do |config|
  config.api_key = '<ph_project_token>'
  config.test_mode = true
end

Or in your specs:

RSpec.configure do |config|
  config.before(:each) do
    allow(PostHog).to receive(:capture)
  end
end

Configuration reference

Core PostHog options

The PostHog.init block supports the options above. Less common core options like batch_size, disable_singleton_warning, skip_ssl_verification, and the experimental flag_definition_cache_provider can be passed as an options hash to PostHog.init(...); see the Ruby SDK docs for details.

Rails-specific options

Configure these via PostHog::Rails.configure or PostHog::Rails.config:

Troubleshooting

Exceptions not being captured

1. Verify PostHog is initialized:

   Ruby

   PostHog AI

   Rails.console
   > PostHog.initialized?
   => true

2. Check your excluded exceptions list.

3. Verify middleware is installed:

   Ruby

   PostHog AI

   Rails.application.middleware

User context not working

1. Verify current_user_method matches your controller method.
2. Check that the user object responds to posthog_distinct_id, distinct_id, id, pk, or uuid.
3. If using a custom identifier, set PostHog::Rails.config.user_id_method = :your_method.

Feature flags not working

Ensure you've set personal_api_key in your configuration.

Next steps

For any technical questions for how to integrate specific PostHog features into Rails (such as analytics, feature flags, A/B testing, etc.), have a look at our Ruby SDK docs.