Ruby On Rails

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@latest

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

Installation

Add both gems to your Gemfile:

Gemfile

PostHog AI

Then run:

Terminal

PostHog AI

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

PostHog AI

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

PostHog AI

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

PostHog AI

bashCopy

rails credentials:edit

config/credentials.yml.enc

PostHog AI

yamlCopy

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

config/initializers/posthog.rb

PostHog AI

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

PostHog AI

Identify a user and set their person properties:

Ruby

PostHog AI

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:

Ruby

PostHog AI

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

PostHog AI

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

PostHog AI

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

Ruby

PostHog AI

Background job exceptions

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

Ruby

PostHog AI

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

PostHog AI

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

Ruby

PostHog AI

You can also use a block:

Ruby

PostHog AI

Rails 7.0+ error reporter

PostHog integrates with Rails’ built-in error reporting:

Ruby

PostHog AI

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

PostHog AI

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

PostHog AI

Or define a method on your User model:

Ruby

PostHog AI

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

PostHog AI

Feature flags

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

Ruby

PostHog AI

For multivariate flags and experiments, use get_flag:

Ruby

PostHog AI

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

PostHog AI

For local evaluation, ensure you’ve set personal_api_key:

Ruby

PostHog AI

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

PostHog AI

Or in your specs:

spec/rails_helper.rb

PostHog AI

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

   PostHog AI

   rubyCopy

   Rails.console
   > PostHog.initialized?
   => true

2. Check your excluded exceptions list.

3. Verify middleware is installed:

   Ruby

   PostHog AI

   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).

Community questions

Ask a question

Was this page useful?

HelpfulCould be better