Add posthog-rails gem for automatic Rails exception tracking by popcorn · Pull Request #81 · PostHog/posthog-ruby

popcorn · 2025-10-28T14:00:12Z

What is this?

This PR introduces the posthog-rails gem which provides automatic exception tracking for Rails applications, inspired by Sentry's gem.

Features:

Automatic capture of unhandled exceptions via Rails middleware
Automatic capture of rescued exceptions (configurable)
Automatic instrumentation of ActiveJob failures
Integration with Rails 7.0+ error reporter
Configurable exception exclusion list
User context capture from controllers

Please read posthog-ruby/posthog-rails/IMPLEMENTATION.md to learn more.

How to test this?

Put both gems in your Rails app's Gemfile, and then reference them via path on your local machine:

gem "posthog-ruby", path: "/Users/drago/code/posthog-ruby"
gem "posthog-rails", path: "/Users/drago/code/posthog-ruby/posthog-rails"

PS

There's only about ~550 new lines of code, other ~950 lines are readmes, code examples etc.
I wrote this for myself to test PostHog so I haven't added any specs. If you are happy with this approach let me know and I will write tests.

popcorn · 2025-10-28T14:23:08Z

posthog-rails/lib/posthog/rails/active_job.rb

+      def extract_distinct_id_from_job
+        # Try to find a user ID in job arguments
+        arguments.each do |arg|
+          if arg.respond_to?(:id)
+            return arg.id
+          elsif arg.is_a?(Hash) && arg['user_id']
+            return arg['user_id']
+          elsif arg.is_a?(Hash) && arg[:user_id]
+            return arg[:user_id]
+          end
+        end
+
+        nil # No user context found
+      end


I am not super-happy with this. Will probably change it to use a proc-based / dynamic configuration.

So you'll be able to define distinct ID in the job itself like this:

class MyJob < ApplicationJob posthog_distinct_id ->(user, arg1, arg2) { user.id } def perform(user, arg1, arg2) # ... end end

This commit introduces the posthog-rails gem which provides automatic exception tracking for Rails applications, including: - Automatic capture of unhandled exceptions via Rails middleware - Automatic capture of rescued exceptions (configurable) - Automatic instrumentation of ActiveJob failures - Integration with Rails 7.0+ error reporter - Configurable exception exclusion list - User context capture from controllers Core library improvements: - Added comprehensive logging throughout exception capture flow - Added ExceptionCapture module for standardized exception parsing - Fixed field handling in Transport to strip internal-only fields (type, library, library_version, messageId) that are not part of PostHog's RawEvent struct - Fixed UUID field handling to avoid sending null values - Added capture_exception method to Client for explicit exception tracking The posthog-rails gem includes: - Railtie for automatic initialization and middleware insertion - Multiple middleware layers for capturing different exception types - ErrorSubscriber for Rails 7.0+ error reporter integration - ActiveJob extensions for job failure tracking - Comprehensive configuration options

popcorn · 2025-10-29T13:09:52Z

Hey @rafaeelaudibert, I saw you closing another PR for automating Rails error tracking because it was too big and included many integrations at once.

This one hooks into Rails middleware and ActiveJob, and also lets you integrate with error reporter if you're on Rails >7.0.

Can you take a look?

popcorn · 2025-11-03T09:23:14Z

cc @dmarticus @daibhin @mariusandra

I cannot add any reviewers for this PR, so I'm tagging you. Please let me know if you're ok with this approach to implementing Rails SDK.

popcorn · 2025-11-06T16:02:25Z

@daibhin, it seems @hpouillot triggered a few CI actions that are failing.

I'll sort it out tomorrow or during the weekend. In the meantime, let me know if you agree with the general approach.

rafaeelaudibert

This looks very very good! Sorry for taking this long to review, but here it is!

I've left a handful of comments on things I'd like to see changed/improved. This is already 95% of the way there!

posthog-rails/examples/posthog.rb

posthog-rails/lib/posthog-rails.rb

posthog-rails/IMPLEMENTATION.md

posthog-rails/README.md

rafaeelaudibert · 2025-11-24T16:19:10Z

Hey @popcorn pinging you just in case you're still interested in getting this merged :)

miharekar · 2025-12-23T08:56:03Z

I'd certainly be interested in getting it merged for my own selfish reasons 😅

johnnagro · 2026-01-13T18:10:17Z

hey @popcorn i'd be happy to lend a hand

popcorn · 2026-01-13T22:34:07Z

hey @popcorn i'd be happy to lend a hand

Hey @johnnagro, I'd love it if you could take over. I've been super-busy lately and will be for the next few months at least. I can help with a review once you do the changes. Would that work for you? My apologies I can't be more helpful atm.

johnnagro · 2026-01-13T23:01:06Z

@popcorn no worries, let me see what i can do. thanks for getting a start on this feature.

johnnagro · 2026-01-15T01:35:35Z

@popcorn mind adding me with write permissions to your fork of the repo? so i can push to your branch. seems like the simplest way to continue the PR and maintain all the history

popcorn · 2026-01-15T10:53:24Z

@popcorn mind adding me with write permissions to your fork of the repo? so i can push to your branch. seems like the simplest way to continue the PR and maintain all the history

Just added you as collaborator on the forked repo, cheers!

…tracking Resolve CHANGELOG.md conflict by keeping both the Unreleased posthog-rails entry and the 3.4.0 release notes.

johnnagro · 2026-01-16T15:33:15Z

I'm all set up now. Resolved the CHANGELOG conflict. I will begin to address the review feedback.

Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>

Added direct links to PostHog settings pages: - Project API key: https://app.posthog.com/settings/project-details#variables - Personal API key: https://app.posthog.com/settings/user-api-keys

Keep it as an example users can uncomment if needed, consistent with other optional callbacks like before_send.

Move Rails-specific configuration from PostHog.rails_config to PostHog::Rails.config for cleaner namespacing.

Add configurable `user_id_method` option and support for `posthog_distinct_id`, `distinct_id`, and `pk` methods when extracting user IDs for exception tracking.

Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>

Move Rails-specific options (auto_capture_exceptions, etc.) to PostHog::Rails.configure, keeping core SDK options in PostHog.init. This follows the common Rails gem pattern of namespaced configuration.

…ontext

Replace repetitive method definitions with define_method loop and add method_missing fallback for future client methods.

- Use request.session.id instead of session_options.dig(:id) - session_options returns Session::Options, not a Hash

johnnagro · 2026-01-17T16:01:54Z

@rafaeelaudibert cc @popcorn - please take another look. I think i've addressed all of your feedback and even went a bit further in a couple spots. I've been testing these changes on a local test rails app and noticed some potential issues in the main gem, see #87 and #88. I could work on fixes there too in dedicated PRs if you're interested.

Let me know your thoughts, happy to continue to iterate on this if need be.

Add safe_serialize to handle circular references and complex objects in exception context. Tracks visited objects, limits depth/size, and converts non-serializable objects to safe string representations. Prevents SystemStackError when Rails error reporter context contains ActiveRecord models or other objects with circular references.

When auto_capture_exceptions was enabled, exceptions in web requests were being captured twice: 1. By CaptureExceptions middleware (after ShowExceptions) 2. By ErrorSubscriber (via Rails.error.subscribe in Rails 7.0+) The ErrorSubscriber fires from within DebugExceptions before the CaptureExceptions middleware catches the exception, causing both to report the same error to PostHog. Fix by tracking web request context via thread-local flag: - CaptureExceptions sets flag at request start, clears in ensure block - ErrorSubscriber checks flag and skips if in web request context This ensures web requests are captured only by the middleware (which has richer context: URL, params, controller, action), while ErrorSubscriber still handles non-web contexts (ActiveJob, manual Rails.error.record).

johnnagro · 2026-01-17T17:14:32Z

I was doing some addition testing and saw a couple further changes that needed to be made. I noticed exceptions were being captured twice in PostHog - two [posthog-ruby] Sending request for 1 items log lines for each error. I also noticed at times the context serialization was crashing when more complex objects were being serialized or had circular references. I added patches for both.

rafaeelaudibert · 2026-01-23T03:58:25Z

Thanks, John! I'll be reviewing this tomorrow, this looks very good! If we merge this in, I'll gladly add some docs about it too.

rafaeelaudibert

There's only one change I'd like to see here. Can automatic error tracking be off by default? This will match the behavior we have for our other SDKs.

You should update the defaults, docs and examples/posthog.rb to make sure we appropriately clone this

Change auto_capture_exceptions, report_rescued_exceptions, and auto_instrument_active_job to default to false, requiring explicit opt-in for automatic error tracking features.

johnnagro · 2026-01-27T20:40:43Z

@rafaeelaudibert i changed auto_capture_exceptions, report_rescued_exceptions, and auto_instrument_active_job to default to false, requiring explicit opt-in for automatic error tracking features. Updated the example config. Updated the README. Please take a look at your convenience.

johnnagro · 2026-01-31T17:12:14Z

@rafaeelaudibert This is ready for another look whenever you have time. (I can't use the formal review request since I took over the PR.)

rafaeelaudibert · 2026-02-01T21:04:28Z

@johnnagro I'll be reviewing this on Monday, thank you!

This must be prepended to make sure it works as expected

Tiny bugfixes found by Claude

rafaeelaudibert

Thank you! I've added a couple fixes and will be merging this now, appreciate your help!

popcorn force-pushed the popcorn/add-rails-activejob-automatic-error-tracking branch from 2967d45 to 1dfe144 Compare October 28, 2025 14:09

popcorn commented Oct 28, 2025

View reviewed changes

popcorn force-pushed the popcorn/add-rails-activejob-automatic-error-tracking branch from 1dfe144 to b4d5947 Compare October 28, 2025 22:14

popcorn force-pushed the popcorn/add-rails-activejob-automatic-error-tracking branch from b4d5947 to e2e4e6d Compare October 28, 2025 22:21

hpouillot requested a review from daibhin November 6, 2025 13:21

fix rubocop errors

472aaa7

rafaeelaudibert reviewed Nov 11, 2025

View reviewed changes

Merge upstream/main into popcorn/add-rails-activejob-automatic-error-…

f21f966

…tracking Resolve CHANGELOG.md conflict by keeping both the Unreleased posthog-rails entry and the 3.4.0 release notes.

johnnagro and others added 10 commits January 17, 2026 08:40

correct default URL

1ccd588

Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>

test mode example config which includes development

805b79e

Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>

Add URLs to API key documentation in example config

78e4852

Added direct links to PostHog settings pages: - Project API key: https://app.posthog.com/settings/project-details#variables - Personal API key: https://app.posthog.com/settings/user-api-keys

Comment out on_error callback in example config

aca80a5

Keep it as an example users can uncomment if needed, consistent with other optional callbacks like before_send.

Add docs explaining benefits of current_user_method config

b41b3f2

refactor: move rails_config to PostHog::Rails.config namespace

5226fc4

Move Rails-specific configuration from PostHog.rails_config to PostHog::Rails.config for cleaner namespacing.

feat(rails): Add user_id_method config and pk support for ID extraction

5b75d22

Add configurable `user_id_method` option and support for `posthog_distinct_id`, `distinct_id`, and `pk` methods when extracting user IDs for exception tracking.

rescue on individual entries

e177372

Co-authored-by: Rafael Audibert <32079912+rafaeelaudibert@users.noreply.github.com>

Separate Rails config from PostHog.init

ea81dd4

Move Rails-specific options (auto_capture_exceptions, etc.) to PostHog::Rails.configure, keeping core SDK options in PostHog.init. This follows the common Rails gem pattern of namespaced configuration.

remove LLM-y file

e127f14

johnnagro added 3 commits January 17, 2026 09:42

docs: clarify user_id/distinct_id detection in Rails error reporter c…

ddb8242

…ontext

refactor(rails): use metaprogramming for client method delegation

e50ad52

Replace repetitive method definitions with define_method loop and add method_missing fallback for future client methods.

Fix session ID extraction in exception capture middleware

611ee39

- Use request.session.id instead of session_options.dig(:id) - session_options returns Session::Options, not a Hash

johnnagro mentioned this pull request Jan 17, 2026

Empty batch sent after oversized message rejection causes retry loop with JSON parse error #87

Open

rafaeelaudibert self-requested a review January 17, 2026 15:08

johnnagro mentioned this pull request Jan 17, 2026

Exception capture payload exceeds 32KB limit due to context lines for all stack frames #88

Open

johnnagro added 2 commits January 17, 2026 12:02

rafaeelaudibert requested changes Jan 26, 2026

View reviewed changes

feat(rails): make automatic error tracking opt-in by default

ea6a803

Change auto_capture_exceptions, report_rescued_exceptions, and auto_instrument_active_job to default to false, requiring explicit opt-in for automatic error tracking features.

rafaeelaudibert self-requested a review February 1, 2026 21:03

johnnagro and others added 8 commits February 2, 2026 21:01

ensuring the example config we copy over maintains the new defaults

96f9fdb

fix: Fix posthog_distinct_id

b852289

This must be prepended to make sure it works as expected

refactor: Small fixes

09c2f05

Tiny bugfixes found by Claude

fix: Update and point default to us.i.posthog.com

9d4caf8

chore: Bump to v3.5.0

8c635fb

docs: Update release process

09ef2d4

refactor: Simplify rubocop rules

6e8f946

chore: Improve release flow to use new approvals workflow

9d3f8fb

rafaeelaudibert approved these changes Feb 5, 2026

View reviewed changes

rafaeelaudibert added 2 commits February 5, 2026 19:52

chore: Remove inherit call

059b44e

Merge branch 'main' into rails

e97af4d

rafaeelaudibert merged commit 648066a into PostHog:main Feb 5, 2026
10 of 11 checks passed

rafaeelaudibert mentioned this pull request Feb 5, 2026

trigger release #91

Merged

Conversation

popcorn commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is this?

How to test this?

Uh oh!

popcorn Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

popcorn commented Oct 29, 2025

Uh oh!

popcorn commented Nov 3, 2025

Uh oh!

popcorn commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rafaeelaudibert left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rafaeelaudibert commented Nov 24, 2025

Uh oh!

miharekar commented Dec 23, 2025

Uh oh!

johnnagro commented Jan 13, 2026

Uh oh!

popcorn commented Jan 13, 2026

Uh oh!

johnnagro commented Jan 13, 2026

Uh oh!

johnnagro commented Jan 15, 2026

Uh oh!

popcorn commented Jan 15, 2026

Uh oh!

johnnagro commented Jan 16, 2026

Uh oh!

johnnagro commented Jan 17, 2026

Uh oh!

johnnagro commented Jan 17, 2026

Uh oh!

rafaeelaudibert commented Jan 23, 2026

Uh oh!

rafaeelaudibert left a comment

Choose a reason for hiding this comment

Uh oh!

johnnagro commented Jan 27, 2026

Uh oh!

johnnagro commented Jan 31, 2026

Uh oh!

rafaeelaudibert commented Feb 1, 2026

Uh oh!

rafaeelaudibert left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

popcorn commented Oct 28, 2025 •

edited

Loading

popcorn commented Nov 6, 2025 •

edited

Loading