Instrument Integration

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

Ruby on Rails

Canonical URL: https://posthog.com/docs/libraries/ruby-on-rails

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://us.posthog.com (app host for links).

On this page

• Install with the wizard

• Features

• Installation

• Identifying users

• Configuration

• Capturing events

• Request context

• Trace context

• Logs

• Error tracking

• Feature flags

• Testing

• Configuration reference

• Troubleshooting

• Next steps

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.

Install with the wizard

Run this command in your project directory to add PostHog to your Rails project. The wizard detects your framework, installs the SDK, and sets up your first events.

npx @posthog/wizard

Or set it up manually by following 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 over OpenTelemetry, automatically correlated with request context (Ruby 3.3+)

Installation

Add both gems to your Gemfile:

Gemfile

gem 'posthog-ruby', require: 'posthog'
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:

config/initializers/posthog.rb

# 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:

Copy

rails credentials:edit

config/credentials.yml.enc

Copy

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

config/initializers/posthog.rb

Copy

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.

If you're using PostHog JS on the frontend, configure tracing_headers 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:

PostHog::Rails.config.use_tracing_headers = false

Trace context

PostHog Rails adds missing sessionId and posthogDistinctId attributes to an active OpenTelemetry SDK request span after it reads the request context. To also add these attributes to child spans, register the optional processor on your existing OpenTelemetry provider before requests start:

require 'posthog/otel/context_span_processor'

OpenTelemetry.tracer_provider.add_span_processor(
  PostHog::ContextSpanProcessor.new
)

This integration supports OpenTelemetry SDK 1.0.0 or later. Keep your existing provider, exporter, sampler, and processors. Put the OpenTelemetry request middleware outside the PostHog request middleware so the request span is active when PostHog reads the context. To send spans to PostHog, configure your existing OTLP exporter with the PostHog trace endpoint.

Existing sessionId and posthogDistinctId span attributes take precedence. Set authenticated application identity with posthogDistinctId. Missing IDs stay absent. Spans that already started keep their attributes after the request ends. Separate threads and fibers need explicit context transfer. With config.auto_instrument_active_job = true, Active Job copies the session and distinct IDs into queued jobs, so job spans get them too. The processor does not create a session, recording, trace provider, or exporter.

Logs

To set up PostHog Logs in your Rails app, follow the Ruby on Rails logs installation guide. 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.

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:

config/environments/test.rb

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

Or in your specs:

spec/rails_helper.rb

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 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:

   Copy

   Rails.console
   > PostHog.initialized?
   => true

2. Check your excluded exceptions list.

3. Verify middleware is installed:

   Copy

   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.