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 (opens in a new tab).

Beta: integration via LLM

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

npx @posthog/wizard

Learn more (opens in a new tab)

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
• Log forwarding – Optionally forwards Rails.logger output to PostHog Logs (opens in a new tab) over OpenTelemetry, automatically correlated with request context (Ruby 3.3+)

Installation

Add both gems to your Gemfile:

Gemfile

Then run:

Terminal

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 (opens in a new tab), LLM traces (opens in a new tab), or error tracking (opens in a new tab).

See our guide on identifying users (opens in a new tab) for how to set this up.

Generate the initializer

Run the install generator to create the PostHog initializer:

Terminal

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:

config/initializers/posthog.rb

You can find your project token and instance address in your project settings (opens in a new tab).

Tip: Use Rails.application.credentials (opens in a new tab) to avoid hardcoding API keys. First, add your keys and then reference them in your initializer:

Terminal

bashCopy

rails credentials:edit

config/credentials.yml.enc

yamlCopy

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

config/initializers/posthog.rb

rubyCopy

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:

Ruby

Identify a user and set their person properties:

Ruby

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.

If you’re using PostHog JS (opens in a new tab) on the frontend, configure tracing_headers (opens in a new tab) for your Rails backend hostname so browser requests include the session and distinct ID headers.

Tracing headers are client-controlled analytics context, not authentication or authorization. Pass an authenticated distinct_id explicitly for security-sensitive server-side decisions.

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:

Ruby

Logs

To set up PostHog Logs (opens in a new tab) in your Rails app, follow the Ruby on Rails logs installation guide (opens in a new tab). The integration forwards Rails.logger output to PostHog Logs over OpenTelemetry, automatically correlated with each request’s distinct ID and session ID. Requires Ruby 3.3+.

Error tracking

For full details on setting up error tracking with Rails, see our Rails error tracking installation guide (opens in a new tab).

Automatic exception tracking

When auto_capture_exceptions is enabled, exceptions are automatically captured:

Ruby

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:

Ruby

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

Ruby

Background job exceptions

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

Ruby

Associating jobs with users

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

Ruby

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

Ruby

You can also use a block:

Ruby

Rails 7.0+ error reporter

PostHog integrates with Rails’ built-in error reporting:

Ruby

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:

Ruby

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:

Ruby

Or define a method on your User model:

Ruby

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:

Ruby

Feature flags

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

Ruby

For multivariate flags and experiments, use get_flag:

Ruby

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:

Ruby

For local evaluation, ensure you’ve set personal_api_key:

Ruby

See our Ruby SDK docs (opens in a new tab) 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:

config/environments/test.rb

Or in your specs:

spec/rails_helper.rb

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 flag_definition_cache_provider can be passed as an options hash to PostHog.init(...); see the Ruby SDK docs (opens in a new tab) 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

   rubyCopy

   Rails.console
   > PostHog.initialized?
   => true

2. Check your excluded exceptions list.

3. Verify middleware is installed:

   Ruby

   rubyCopy

   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 (opens in a new tab).

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better