# PostHog ruby-on-rails Example Project
Repository: https://github.com/PostHog/context-mill
Path: basics/ruby-on-rails
---
## README.md
# PostHog Ruby on Rails example
This is a [Ruby on Rails](https://rubyonrails.org) example demonstrating PostHog integration with product analytics, error tracking (auto-instrumentation), feature flags, user identification, and ActiveJob instrumentation via the `posthog-rails` gem.
## Features
- **Product analytics**: Track user events and behaviors with `PostHog.capture`
- **Error tracking (auto)**: Unhandled exceptions captured automatically by `posthog-rails`
- **Error tracking (manual)**: Handled errors captured with `PostHog.capture_exception`
- **Rails.error integration**: Rails 7+ error reporting captured automatically
- **ActiveJob instrumentation**: Background job failures captured automatically
- **User identification**: Associate events with authenticated users via `PostHog.identify`
- **Feature flags**: Control feature rollouts with `PostHog.is_feature_enabled`
- **User context**: Exceptions automatically associated with `current_user`
- **Frontend tracking**: posthog-js captures pageviews and session replay alongside backend events
## Getting started
### 1. Install dependencies
```bash
bundle install
```
### 2. Configure environment variables
```bash
cp .env.example .env
# Edit .env and add your PostHog project token
```
Get your PostHog project token from your [PostHog project settings](https://app.posthog.com/project/settings).
### 3. Setup database
```bash
bin/rails db:create db:migrate db:seed
```
### 4. Run the development server
```bash
bin/rails server
```
Open [http://localhost:3000](http://localhost:3000) with your browser. Login with `admin@example.com` / `admin`.
## Project structure
```
ruby-on-rails/
├── config/
│ ├── routes.rb # URL routing
│ └── initializers/
│ └── posthog.rb # PostHog + posthog-rails configuration
├── app/
│ ├── controllers/
│ │ ├── application_controller.rb # Base controller with current_user
│ │ ├── sessions_controller.rb # Login/logout with PostHog identify
│ │ ├── registrations_controller.rb # Signup with PostHog identify
│ │ ├── dashboard_controller.rb # Feature flags + ActiveJob demo
│ │ ├── burritos_controller.rb # Custom event tracking
│ │ ├── profiles_controller.rb # Page view tracking
│ │ └── errors_controller.rb # Error tracking demos
│ ├── jobs/
│ │ └── example_job.rb # ActiveJob auto-instrumentation demo
│ ├── models/
│ │ └── user.rb # posthog_distinct_id + posthog_properties
│ └── views/
│ ├── layouts/application.html.erb # Base layout with posthog-js snippet
│ ├── sessions/new.html.erb # Login page
│ ├── registrations/new.html.erb # Signup page
│ ├── dashboard/show.html.erb # Feature flags demo
│ ├── burritos/show.html.erb # Event tracking demo
│ └── profiles/show.html.erb # Error tracking demo
├── db/
│ ├── migrate/ # Database migrations
│ └── seeds.rb # Default admin user
├── .env.example # Environment variable template
├── Gemfile # Ruby dependencies
└── README.md # This file
```
## Key integration points
### PostHog initialization (config/initializers/posthog.rb)
```ruby
# Rails-specific auto-instrumentation
PostHog::Rails.configure do |config|
config.auto_capture_exceptions = true
config.report_rescued_exceptions = true
config.auto_instrument_active_job = true
config.capture_user_context = true
config.current_user_method = :current_user
config.user_id_method = :posthog_distinct_id
end
PostHog.init do |config|
config.api_key = ENV.fetch('POSTHOG_PROJECT_TOKEN', nil)
config.host = ENV.fetch('POSTHOG_HOST', 'https://us.i.posthog.com')
end
```
### User model (app/models/user.rb)
```ruby
class User < ApplicationRecord
has_secure_password
# Called by posthog-rails for automatic user association in error reports
def posthog_distinct_id
email
end
def posthog_properties
{ email: email, is_staff: is_staff, date_joined: created_at&.iso8601 }
end
end
```
### User identification (app/controllers/sessions_controller.rb)
```ruby
# Identify the user and capture login event
PostHog.identify(
distinct_id: user.posthog_distinct_id,
properties: user.posthog_properties
)
PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'user_logged_in',
properties: { login_method: 'email' }
)
```
### Feature flags (app/controllers/dashboard_controller.rb)
```ruby
# Check if a feature flag is enabled
@show_new_feature = PostHog.is_feature_enabled(
'new-dashboard-feature',
user.posthog_distinct_id,
person_properties: user.posthog_properties
)
# Get feature flag payload for configuration
@feature_config = PostHog.get_feature_flag_payload(
'new-dashboard-feature',
user.posthog_distinct_id
)
```
### Error tracking — auto-capture
With `auto_capture_exceptions: true`, unhandled exceptions in controllers are captured automatically. No code needed:
```ruby
# This exception is automatically captured by posthog-rails
# with the current_user's posthog_distinct_id attached
def show
raise "Something went wrong" # Captured automatically!
end
```
### Error tracking — manual capture
```ruby
begin
risky_operation
rescue => e
PostHog.capture_exception(e, current_user.posthog_distinct_id)
end
```
### Error tracking — Rails.error integration
```ruby
# posthog-rails subscribes to Rails.error automatically
Rails.error.handle(context: { user_id: user.id }) do
risky_operation
end
```
### ActiveJob instrumentation
```ruby
# config: auto_instrument_active_job = true
# Job failures are captured automatically.
# Use the posthog_distinct_id DSL to associate errors with a user.
class ExampleJob < ApplicationJob
posthog_distinct_id ->(distinct_id, *) { distinct_id }
def perform(distinct_id, should_fail: false)
raise "Job failed" # Captured automatically with user context
end
end
# In the controller, pass the distinct_id when enqueuing:
ExampleJob.perform_later(current_user.posthog_distinct_id, should_fail: true)
```
## Frontend + Backend integration
This example includes the posthog-js snippet in the layout template to demonstrate how frontend and backend tracking work together.
### How it works
1. **posthog-js** (frontend) captures pageviews, clicks, and session replay
2. **posthog-ruby + posthog-rails** (backend) captures business logic events, errors, and feature flag evaluations
3. **Shared distinct_id** — frontend and backend events are linked when the same `distinct_id` is used on both sides. Call `posthog.identify(user.email)` in posthog-js after login, matching the `posthog_distinct_id` used on the backend
4. **Session replay** lets you watch user sessions where errors occurred
**Note:** Unlike the Django SDK, posthog-rails does not include a context middleware that reads `X-POSTHOG-SESSION-ID` or `X-POSTHOG-DISTINCT-ID` tracing headers. Frontend and backend events are correlated through the shared `distinct_id`.
### When to track frontend vs backend
- **Frontend**: UI interactions, client-side errors, session replay, pageviews
- **Backend**: Business logic (signups, purchases), server errors, feature flag evaluations, background jobs
## Learn more
- [PostHog Ruby on Rails integration](https://posthog.com/docs/libraries/ruby-on-rails)
- [PostHog Ruby SDK](https://posthog.com/docs/libraries/ruby)
- [PostHog Error Tracking](https://posthog.com/docs/error-tracking)
- [Ruby on Rails documentation](https://guides.rubyonrails.org/)
---
## .env.example
```example
# PostHog Configuration
POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
POSTHOG_HOST=https://us.i.posthog.com
# Optional: Enable debug mode to see PostHog requests
# POSTHOG_DEBUG=true
```
---
## app/controllers/application_controller.rb
```rb
class ApplicationController < ActionController::Base
protect_from_forgery with: :exception
private
def current_user
@current_user ||= User.find_by(id: session[:user_id]) if session[:user_id]
end
helper_method :current_user
def require_login
unless current_user
redirect_to login_path
end
end
end
```
---
## app/controllers/burritos_controller.rb
```rb
class BurritosController < ApplicationController
before_action :require_login
def show
@burrito_count = session[:burrito_count] || 0
end
def consider
count = (session[:burrito_count] || 0) + 1
session[:burrito_count] = count
user = current_user
# PostHog: Track custom event
PostHog.identify(
distinct_id: user.posthog_distinct_id,
properties: user.posthog_properties
)
PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'burrito_considered',
properties: { total_considerations: count }
)
render json: { success: true, count: count }
end
end
```
---
## app/controllers/dashboard_controller.rb
```rb
class DashboardController < ApplicationController
before_action :require_login
def show
user = current_user
# PostHog: Track dashboard view
PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'dashboard_viewed',
properties: { is_staff: user.is_staff }
)
# PostHog: Check feature flag
@show_new_feature = PostHog.is_feature_enabled(
'new-dashboard-feature',
user.posthog_distinct_id,
person_properties: user.posthog_properties
)
# PostHog: Get feature flag payload for configuration
@feature_config = PostHog.get_feature_flag_payload(
'new-dashboard-feature',
user.posthog_distinct_id
)
end
def enqueue_test_job
# Enqueue a job that will fail — posthog-rails captures the error automatically.
# The distinct_id is passed so the posthog_distinct_id DSL can associate the error with this user.
ExampleJob.perform_later(current_user.posthog_distinct_id, should_fail: true)
render json: {
success: true,
message: 'Job enqueued. The job will fail and posthog-rails will capture the error automatically.'
}
end
end
```
---
## app/controllers/errors_controller.rb
```rb
class ErrorsController < ApplicationController
before_action :require_login
def test
# Manual exception capture — catch the error and report it explicitly
begin
raise StandardError, 'Test exception from critical operation'
rescue StandardError => e
# PostHog: Manually capture the exception
PostHog.capture_exception(e, current_user.posthog_distinct_id)
PostHog.capture(
distinct_id: current_user.posthog_distinct_id,
event: 'error_triggered',
properties: {
error_type: e.class.name,
error_message: e.message
}
)
render json: {
success: false,
error: e.message,
message: 'Error has been captured by PostHog'
}, status: :internal_server_error
end
end
def test_rails_error
# Rails.error.handle — Rails 7+ error reporting integration.
# posthog-rails subscribes to Rails.error, so exceptions reported
# via Rails.error.handle are automatically captured in PostHog.
Rails.error.handle(context: { user_id: current_user.id }) do
raise StandardError, 'Test error via Rails.error.handle — captured automatically by posthog-rails'
end
render json: {
success: true,
message: 'Error was handled via Rails.error.handle and captured by posthog-rails'
}
end
end
```
---
## app/controllers/profiles_controller.rb
```rb
class ProfilesController < ApplicationController
before_action :require_login
def show
# PostHog: Track profile view
PostHog.capture(
distinct_id: current_user.posthog_distinct_id,
event: 'profile_viewed'
)
end
end
```
---
## app/controllers/registrations_controller.rb
```rb
class RegistrationsController < ApplicationController
def new
redirect_to dashboard_path if current_user
end
def create
user = User.new(
email: params[:email],
password: params[:password],
password_confirmation: params[:password_confirmation]
)
if user.save
session[:user_id] = user.id
# PostHog: Identify the new user and capture signup event
PostHog.identify(
distinct_id: user.posthog_distinct_id,
properties: user.posthog_properties
)
PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'user_signed_up',
properties: { signup_method: 'form' }
)
redirect_to dashboard_path
else
flash[:error] = user.errors.full_messages.join(', ')
render :new, status: :unprocessable_entity
end
end
end
```
---
## app/controllers/sessions_controller.rb
```rb
class SessionsController < ApplicationController
def new
redirect_to dashboard_path if current_user
end
def create
user = User.find_by(email: params[:email])
if user&.authenticate(params[:password])
session[:user_id] = user.id
# PostHog: Identify the user and capture login event
PostHog.identify(
distinct_id: user.posthog_distinct_id,
properties: user.posthog_properties
)
PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'user_logged_in',
properties: { login_method: 'email' }
)
redirect_to dashboard_path
else
flash[:error] = 'Invalid email or password'
render :new, status: :unprocessable_entity
end
end
def destroy
if current_user
# PostHog: Track logout before session ends
PostHog.capture(
distinct_id: current_user.posthog_distinct_id,
event: 'user_logged_out'
)
end
session.delete(:user_id)
redirect_to login_path
end
end
```
---
## app/jobs/application_job.rb
```rb
class ApplicationJob < ActiveJob::Base
end
```
---
## app/jobs/example_job.rb
```rb
# Example ActiveJob demonstrating posthog-rails auto-instrumentation.
#
# When auto_instrument_active_job is enabled in the PostHog config,
# posthog-rails automatically captures exceptions from failed jobs.
# The job class name, queue, and arguments are included as properties
# on the error event.
#
# Use the posthog_distinct_id DSL to associate job errors with a user.
# The proc receives the same arguments as perform and should return
# the distinct_id string. Without this, job errors have no user context.
class ExampleJob < ApplicationJob
queue_as :default
# Extract distinct_id from the first argument so posthog-rails
# can associate the error with the user who triggered the job.
posthog_distinct_id ->(distinct_id, *) { distinct_id }
def perform(distinct_id, should_fail: false)
if should_fail
raise StandardError, 'Example job failure - this error is automatically captured by posthog-rails'
end
Rails.logger.info "ExampleJob completed successfully for #{distinct_id}"
end
end
```
---
## app/models/application_record.rb
```rb
class ApplicationRecord < ActiveRecord::Base
primary_abstract_class
end
```
---
## app/models/user.rb
```rb
class User < ApplicationRecord
has_secure_password
validates :email, presence: true, uniqueness: true
# Called by posthog-rails for automatic user association in error reports.
# When auto_capture_exceptions and capture_user_context are enabled,
# posthog-rails calls this method on current_user to get the distinct_id.
def posthog_distinct_id
email
end
# Helper used by controllers when calling PostHog.identify to set person properties.
# These properties appear on the person profile in PostHog.
def posthog_properties
{
email: email,
is_staff: is_staff,
date_joined: created_at&.iso8601
}
end
end
```
---
## app/views/burritos/show.html.erb
```erb
<% content_for(:title) { 'Burrito - PostHog Rails example' } %>
Burrito consideration tracker
This page demonstrates custom event tracking with PostHog.
Times considered
<%= @burrito_count %>
How event tracking works
Each time you click the button, a burrito_considered event is sent to PostHog:
Feature flags allow you to control feature rollouts and run A/B tests.
<% if @show_new_feature %>
New feature enabled!
This section is only visible because the new-dashboard-feature
flag is enabled for your user.
<% if @feature_config %>
Feature config: <%= @feature_config %>
<% end %>
<% else %>
The new-dashboard-feature flag is not enabled for your user.
Create this flag in your PostHog project to see it in action.
<% end %>
ActiveJob instrumentation
Click below to enqueue a background job that will fail.
posthog-rails automatically captures the exception — no extra code needed.
How feature flags work
# Check if a feature flag is enabled
show_feature = PostHog.is_feature_enabled(
'new-dashboard-feature',
user.posthog_distinct_id,
person_properties: user.posthog_properties
)
# Get feature flag payload for configuration
config = PostHog.get_feature_flag_payload(
'new-dashboard-feature',
user.posthog_distinct_id
)
<% content_for :scripts do %>
<% end %>
```
---
## app/views/layouts/application.html.erb
```erb
<%= content_for?(:title) ? yield(:title) : 'PostHog Rails example' %>
<%= csrf_meta_tags %>
<% if current_user %>
<% end %>
Rails.error integration — Rails 7+ error reporting captured by posthog-rails
Frontend tracking — posthog-js captures pageviews and session replay
```
---
## bin/rails
```
#!/usr/bin/env ruby
APP_PATH = File.expand_path('../config/application', __dir__)
require_relative '../config/boot'
require 'rails/commands'
```
---
## config.ru
```ru
require_relative 'config/environment'
run Rails.application
```
---
## config/application.rb
```rb
require_relative 'boot'
require 'rails/all'
Bundler.require(*Rails.groups)
module PosthogExample
class Application < Rails::Application
config.load_defaults 7.1
# Use SQLite for all stores
config.active_job.queue_adapter = :async
end
end
```
---
## config/boot.rb
```rb
ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
require 'bundler/setup'
```
---
## config/environment.rb
```rb
require_relative 'application'
Rails.application.initialize!
```
---
## config/environments/development.rb
```rb
require 'active_support/core_ext/integer/time'
Rails.application.configure do
config.enable_reloading = true
config.eager_load = false
config.consider_all_requests_local = true
config.server_timing = true
# Secret key for development (not used in production)
config.secret_key_base = 'dev-secret-key-for-posthog-example-only'
config.action_controller.perform_caching = false
config.cache_store = :memory_store
config.active_support.deprecation = :log
config.active_support.disallowed_deprecation = :raise
config.active_support.disallowed_deprecation_warnings = []
config.active_record.migration_error = :page_load
config.active_record.verbose_query_logs = true
end
```
---
## config/initializers/posthog.rb
```rb
# PostHog configuration with posthog-rails auto-instrumentation
#
# The posthog-rails gem provides:
# - Automatic exception capture for unhandled controller errors
# - ActiveJob instrumentation for background job failures
# - User context detection from current_user
# - Rails.error integration for rescued exceptions
PostHog.init do |config|
config.api_key = ENV.fetch('POSTHOG_PROJECT_TOKEN', nil)
config.host = ENV.fetch('POSTHOG_HOST', 'https://us.i.posthog.com')
end
PostHog::Rails.configure do |config|
# Auto-capture unhandled exceptions in controllers
config.auto_capture_exceptions = true
# Also capture exceptions that Rails rescues (e.g. ActiveRecord::RecordNotFound)
config.report_rescued_exceptions = true
# Auto-instrument ActiveJob failures
config.auto_instrument_active_job = true
# Automatically associate errors with the current user
config.capture_user_context = true
config.current_user_method = :current_user
config.user_id_method = :posthog_distinct_id
end
```
---
## config/routes.rb
```rb
Rails.application.routes.draw do
# Auth
get 'login', to: 'sessions#new'
post 'login', to: 'sessions#create'
delete 'logout', to: 'sessions#destroy'
get 'signup', to: 'registrations#new'
post 'signup', to: 'registrations#create'
# App
get 'dashboard', to: 'dashboard#show'
get 'burrito', to: 'burritos#show'
post 'api/burrito/consider', to: 'burritos#consider'
get 'profile', to: 'profiles#show'
# Error tracking demos
post 'api/test-error', to: 'errors#test'
post 'api/test-rails-error', to: 'errors#test_rails_error'
# Background job demo
post 'api/test-job', to: 'dashboard#enqueue_test_job'
root 'sessions#new'
end
```
---
## db/migrate/20240101000000_create_users.rb
```rb
class CreateUsers < ActiveRecord::Migration[7.1]
def change
create_table :users do |t|
t.string :email, null: false
t.string :password_digest, null: false
t.boolean :is_staff, default: false
t.timestamps
end
add_index :users, :email, unique: true
end
end
```
---
## db/schema.rb
```rb
# This file is auto-generated from the current state of the database. Instead
# of editing this file, please use the migrations feature of Active Record to
# incrementally modify your database, and then regenerate this schema definition.
#
# This file is the source Rails uses to define your schema when running `bin/rails
# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
# be faster and is potentially less error prone than running all of your
# migrations from scratch. Old migrations may fail to apply correctly if those
# migrations use external dependencies or application code.
#
# It's strongly recommended that you check this file into your version control system.
ActiveRecord::Schema[7.2].define(version: 2024_01_01_000000) do
create_table "users", force: :cascade do |t|
t.string "email", null: false
t.string "password_digest", null: false
t.boolean "is_staff", default: false
t.datetime "created_at", null: false
t.datetime "updated_at", null: false
t.index ["email"], name: "index_users_on_email", unique: true
end
end
```
---
## db/seeds.rb
```rb
# Create a default admin user for testing
User.find_or_create_by!(email: 'admin@example.com') do |user|
user.password = 'admin'
user.password_confirmation = 'admin'
user.is_staff = true
end
puts 'Seed data created: admin@example.com / admin'
```
---
## Gemfile
```
source 'https://rubygems.org'
gem 'rails', '~> 7.1'
gem 'sqlite3', '~> 1.7'
gem 'puma', '~> 6.0'
gem 'bcrypt', '~> 3.1'
gem 'dotenv-rails', '~> 3.0'
# PostHog
gem 'posthog-ruby', '~> 3.0'
gem 'posthog-rails'
```
---
## Rakefile
```
require_relative 'config/application'
Rails.application.load_tasks
```
---