references/EXAMPLE.md
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 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
bundle install
2. Configure environment variables
cp .env.example .env
# Edit .env and add your PostHog project token
Get your PostHog project token from your PostHog project settings.
3. Setup database
bin/rails db:create db:migrate db:seed
4. Run the development server
bin/rails server
Open http://localhost:3000 with your browser. Login with [email protected] / 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)
# 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)
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)
# 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)
# 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:
# 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
begin
risky_operation
rescue => e
PostHog.capture_exception(e, current_user.posthog_distinct_id)
end
Error tracking — Rails.error integration
# posthog-rails subscribes to Rails.error automatically
Rails.error.handle(context: { user_id: user.id }) do
risky_operation
end
ActiveJob instrumentation
# 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
- posthog-js (frontend) captures pageviews, clicks, and session replay
- posthog-ruby + posthog-rails (backend) captures business logic events, errors, and feature flag evaluations
- Shared distinct_id — frontend and backend events are linked when the same
distinct_idis used on both sides. Callposthog.identify(user.email)in posthog-js after login, matching theposthog_distinct_idused on the backend - 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
- PostHog Ruby SDK
- PostHog Error Tracking
- Ruby on Rails documentation
.env.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
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
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
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
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
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
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
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
class ApplicationJob < ActiveJob::Base
end
app/jobs/example_job.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
class ApplicationRecord < ActiveRecord::Base
primary_abstract_class
end
app/models/user.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
<% content_for(:title) { 'Burrito - PostHog Rails example' } %>
<div class="card">
<h1>Burrito consideration tracker</h1>
<p>This page demonstrates custom event tracking with PostHog.</p>
</div>
<div class="card" style="text-align: center;">
<h2>Times considered</h2>
<div class="count" id="burrito-count"><%= @burrito_count %></div>
<button onclick="considerBurrito()" style="font-size: 18px; padding: 15px 30px;">
Consider a burrito
</button>
</div>
<div class="card">
<h3>How event tracking works</h3>
<p>Each time you click the button, a <code>burrito_considered</code> event is sent to PostHog:</p>
<pre style="background: #f3f4f6; padding: 15px; border-radius: 5px; overflow-x: auto; margin-top: 15px;"><code>PostHog.capture(
distinct_id: user.posthog_distinct_id,
event: 'burrito_considered',
properties: { total_considerations: count }
)</code></pre>
</div>
<% content_for :scripts do %>
<script>
async function considerBurrito() {
try {
const response = await fetch('/api/burrito/consider', {
method: 'POST',
headers: {
'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content,
'Content-Type': 'application/json',
},
});
const data = await response.json();
if (data.success) {
document.getElementById('burrito-count').textContent = data.count;
}
} catch (error) {
console.error('Error:', error);
}
}
</script>
<% end %>
app/views/dashboard/show.html.erb
<% content_for(:title) { 'Dashboard - PostHog Rails example' } %>
<div class="card">
<h1>Dashboard</h1>
<p>Welcome back, <strong><%= current_user.email %></strong>!</p>
</div>
<div class="card">
<h2>Feature flags</h2>
<p>Feature flags allow you to control feature rollouts and run A/B tests.</p>
<% if @show_new_feature %>
<div class="feature-flag">
<h3>New feature enabled!</h3>
<p>
This section is only visible because the <code>new-dashboard-feature</code>
flag is enabled for your user.
</p>
<% if @feature_config %>
<p><strong>Feature config:</strong> <%= @feature_config %></p>
<% end %>
</div>
<% else %>
<div style="background: #f3f4f6; padding: 15px; border-radius: 8px; margin-top: 15px;">
<p>
The <code>new-dashboard-feature</code> flag is not enabled for your user.
Create this flag in your PostHog project to see it in action.
</p>
</div>
<% end %>
</div>
<div class="card">
<h2>ActiveJob instrumentation</h2>
<p>
Click below to enqueue a background job that will fail.
<code>posthog-rails</code> automatically captures the exception — no extra code needed.
</p>
<button onclick="enqueueTestJob()" style="margin-top: 10px;">Enqueue failing job</button>
<div id="job-result" style="margin-top: 15px; display: none;"></div>
</div>
<div class="card">
<h3>How feature flags work</h3>
<pre style="background: #f3f4f6; padding: 15px; border-radius: 5px; overflow-x: auto;"><code># 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
)</code></pre>
</div>
<% content_for :scripts do %>
<script>
async function enqueueTestJob() {
const resultDiv = document.getElementById('job-result');
try {
const response = await fetch('/api/test-job', {
method: 'POST',
headers: {
'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content,
'Content-Type': 'application/json',
},
});
const data = await response.json();
resultDiv.style.display = 'block';
resultDiv.innerHTML = '<div class="flash success">' + data.message + '</div>';
} catch (error) {
resultDiv.style.display = 'block';
resultDiv.innerHTML = '<div class="flash error">Request failed: ' + error + '</div>';
}
}
</script>
<% end %>
app/views/layouts/application.html.erb
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><%= content_for?(:title) ? yield(:title) : 'PostHog Rails example' %></title>
<%= csrf_meta_tags %>
<style>
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
line-height: 1.6;
background-color: #f5f5f5;
color: #333;
}
.container {
max-width: 800px;
margin: 0 auto;
padding: 20px;
}
nav {
background: #1d4ed8;
padding: 15px 20px;
margin-bottom: 30px;
}
nav a {
color: white;
text-decoration: none;
margin-right: 20px;
}
nav a:hover {
text-decoration: underline;
}
.card {
background: white;
border-radius: 8px;
padding: 20px;
margin-bottom: 20px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
h1, h2, h3 {
margin-bottom: 15px;
color: #1d4ed8;
}
button, .btn {
background: #1d4ed8;
color: white;
border: none;
padding: 10px 20px;
border-radius: 5px;
cursor: pointer;
font-size: 14px;
display: inline-block;
text-decoration: none;
}
button:hover, .btn:hover {
background: #1e40af;
}
button.danger {
background: #dc2626;
}
button.danger:hover {
background: #b91c1c;
}
input {
width: 100%;
padding: 10px;
margin-bottom: 15px;
border: 1px solid #ddd;
border-radius: 5px;
font-size: 14px;
}
.flash {
padding: 10px 15px;
border-radius: 5px;
margin-bottom: 20px;
}
.flash.error {
background: #fee2e2;
color: #dc2626;
}
.flash.success {
background: #d1fae5;
color: #059669;
}
.feature-flag {
background: #fef3c7;
border: 2px dashed #f59e0b;
padding: 15px;
border-radius: 8px;
margin: 20px 0;
}
code {
background: #f3f4f6;
padding: 2px 6px;
border-radius: 3px;
font-family: monospace;
}
.count {
font-size: 48px;
font-weight: bold;
color: #1d4ed8;
text-align: center;
padding: 20px;
}
</style>
<!-- PostHog frontend tracking (posthog-js) -->
<script>
!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=fun