posthog-rails 3.8.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f7082d07840d3127b46409cfaa97b2d169cb0520d1589c9c5fdf7cf875a403b
-  data.tar.gz: 2371da2d51b6977fd8a2544270fae72c8c6e5e9465783ca9fd32bf118b85ae8c
+  metadata.gz: e9d0502771ef899181fbcf4acbbaf7b3c72000e5082ef69e98163bf43ae57002
+  data.tar.gz: 6002687536b139e97f4e4afc361f17ec519fc0fa54b16416bf888ba55e9b37f7
 SHA512:
-  metadata.gz: 1eb75d92349a07684187e06367675d7e4a844f7c9fb04616e9c85a0c88e94f33a8adce88f092c1a476813523ebfb0b5ee317cb5013b17b9eb15b31209218fed1
-  data.tar.gz: '0338af574847d6c9f52e1c3f43b7f7b7401ee9966a1d0816d3b1a5967b3a4689d584e1801cfa50101e0106f4692239eb0ac2a9be5e7f7533099bca7266730705'
+  metadata.gz: 339d21bdceb568ff493da11539db72fb0ca32d61cc50e18d12facc6a7920761554cc15a2cc85a45adf60a9b8fa324ad6129fb09ca176e180b3c7a4002f08e2ec
+  data.tar.gz: b6f2417f98317d42a5cdad3f15e7b2ae1d00254fd63571768a01956ffbb4cc0e398892409f65eb69167941a19392fc549c33406723b3cc36cef38b8f0f49017c

data/lib/generators/posthog/templates/posthog.rb

@@ -22,7 +22,13 @@ PostHog::Rails.configure do |config|
   # Set to true to enable automatic ActiveJob exception tracking
   # config.auto_instrument_active_job = true
 
-  # Capture user context with exceptions (default: true)
+  # Use PostHog tracing headers for request-scoped identity/session context (default: true)
+  # Request metadata (current URL, method, path, user agent, and IP) is always captured during Rails requests
+  # Set to false to ignore client-supplied X-PostHog-Distinct-Id and X-PostHog-Session-Id headers
+  # config.use_tracing_headers = true
+
+  # Capture authenticated user context with exceptions (default: true)
+  # Authenticated Rails user context takes precedence over client-supplied tracing headers for exception identity
   # config.capture_user_context = true
 
   # Controller method name to get current user (default: :current_user)

data/lib/posthog/rails/capture_exceptions.rb

@@ -18,6 +18,7 @@ module PostHog
         PostHog::Rails.enter_web_request
 
         response = @app.call(env)
+        env['posthog.response_status_code'] = response_status(response)
 
         # Check if there was an exception that Rails handled
         exception = collect_exception(env)
@@ -51,7 +52,7 @@ module PostHog
 
       def capture_exception(exception, env)
         request = ActionDispatch::Request.new(env)
-        distinct_id = extract_distinct_id(env, request)
+        distinct_id = extract_distinct_id(env)
         additional_properties = build_properties(request, env)
 
         PostHog.capture_exception(exception, distinct_id, additional_properties)
@@ -60,20 +61,21 @@ module PostHog
         PostHog::Logging.logger.error("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
       end
 
-      def extract_distinct_id(env, request)
-        # Try to get user from controller if capture_user_context is enabled
+      def extract_distinct_id(env)
+        # Prefer authenticated Rails user context. Request/tracing context is
+        # applied later by the core capture path if this returns nil.
         if PostHog::Rails.config&.capture_user_context && env['action_controller.instance']
           controller = env['action_controller.instance']
           method_name = PostHog::Rails.config&.current_user_method || :current_user
 
           if controller.respond_to?(method_name, true)
             user = controller.send(method_name)
-            return extract_user_id(user) if user
+            user_id = extract_user_id(user) if user
+            return user_id if present?(user_id)
           end
         end
 
-        # Fallback to session ID or nil
-        request.session&.id&.to_s
+        nil
       end
 
       def extract_user_id(user)
@@ -98,10 +100,7 @@ module PostHog
 
       def build_properties(request, env)
         properties = {
-          '$exception_source' => 'rails',
-          '$current_url' => safe_serialize(request.url),
-          '$request_method' => safe_serialize(request.method),
-          '$request_path' => safe_serialize(request.path)
+          '$exception_source' => 'rails'
         }
 
         # Add controller and action if available
@@ -118,14 +117,23 @@ module PostHog
           properties['$request_params'] = safe_serialize(filtered_params) unless filtered_params.empty?
         end
 
-        # Add user agent
-        properties['$user_agent'] = safe_serialize(request.user_agent) if request.user_agent
+        response_status_code = env['posthog.response_status_code']
+        properties['$response_status_code'] = response_status_code if response_status_code
 
         # Add referrer
         properties['$referrer'] = safe_serialize(request.referrer) if request.referrer
 
         properties
       end
+
+      def response_status(response)
+        status = response.respond_to?(:[]) ? response[0] : nil
+        status if status.is_a?(Integer)
+      end
+
+      def present?(value)
+        !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+      end
     end
   end
 end

data/lib/posthog/rails/configuration.rb

@@ -15,6 +15,9 @@ module PostHog
       # List of exception classes to ignore (in addition to default)
       attr_accessor :excluded_exceptions
 
+      # Whether to use PostHog tracing headers for request-scoped identity/session context
+      attr_accessor :use_tracing_headers
+
       # Whether to capture the current user context in exceptions
       attr_accessor :capture_user_context
 
@@ -30,6 +33,7 @@ module PostHog
         @report_rescued_exceptions = false
         @auto_instrument_active_job = false
         @excluded_exceptions = []
+        @use_tracing_headers = true
         @capture_user_context = true
         @current_user_method = :current_user
         @user_id_method = nil

data/lib/posthog/rails/railtie.rb

@@ -73,8 +73,15 @@ module PostHog
         end
       end
 
-      # Insert middleware for exception capturing
+      # Insert middleware for request context and exception capturing
       initializer 'posthog.insert_middlewares' do |app|
+        # Wrap the Rails exception middleware so request context is active for
+        # downstream handlers and exception capture.
+        insert_middleware_before(
+          app, ActionDispatch::ShowExceptions,
+          PostHog::Rails::RequestContext
+        )
+
         # Insert after DebugExceptions to catch rescued exceptions
         insert_middleware_after(
           app, ActionDispatch::DebugExceptions,
@@ -118,6 +125,13 @@ module PostHog
         app.config.middleware.insert_after(target, middleware)
       end
 
+      def insert_middleware_before(app, target, middleware)
+        # During initialization, app.config.middleware is a MiddlewareStackProxy
+        # which only supports recording operations (insert_before, use, etc.)
+        # and does NOT support query methods like include?.
+        app.config.middleware.insert_before(target, middleware)
+      end
+
       def self.register_error_subscriber
         return unless PostHog::Rails.config&.auto_capture_exceptions
 

data/lib/posthog/rails/request_context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'posthog/internal/context'
+require 'posthog/rails/tracing_headers'
+require 'posthog/rails/request_metadata'
+
+module PostHog
+  module Rails
+    # Rack middleware that creates a request-local PostHog context from tracing headers.
+    class RequestContext
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = build_request(env)
+
+        Internal::Context.with_context(context_data(request), fresh: true) do
+          @app.call(env)
+        end
+      end
+
+      private
+
+      def context_data(request)
+        data = { properties: request_properties(request) }
+        return data unless use_tracing_headers?
+
+        data.merge(
+          distinct_id: tracing_header(request, 'X-POSTHOG-DISTINCT-ID'),
+          session_id: tracing_header(request, 'X-POSTHOG-SESSION-ID')
+        )
+      end
+
+      def use_tracing_headers?
+        PostHog::Rails.config&.use_tracing_headers != false
+      end
+
+      def request_properties(request)
+        RequestMetadata.extract(request)
+      end
+
+      def tracing_header(request, header_name)
+        TracingHeaders.extract_header(request, header_name)
+      end
+
+      def build_request(env)
+        if defined?(ActionDispatch::Request)
+          ActionDispatch::Request.new(env)
+        elsif defined?(Rack::Request)
+          Rack::Request.new(env)
+        else
+          env
+        end
+      end
+    end
+  end
+end

data/lib/posthog/rails/request_metadata.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'posthog/rails/tracing_headers'
+
+module PostHog
+  module Rails
+    # Internal helpers for extracting request metadata owned by RequestContext.
+    module RequestMetadata
+      module_function
+
+      def extract(request)
+        properties = {}
+        add_property(properties, '$current_url', current_url(request))
+        request_method = request_value(request, :request_method) || request_value(request, :method)
+        add_property(properties, '$request_method', request_method)
+        add_property(properties, '$request_path', request_value(request, :path) || request_value(request, :path_info))
+        add_property(properties, '$user_agent', TracingHeaders.extract_header(request, 'User-Agent'))
+        add_property(properties, '$ip', client_ip(request))
+        properties
+      end
+
+      def current_url(request)
+        url = request_value(request, :url)
+        return if url.nil?
+
+        url.to_s.split('?', 2).first
+      end
+      private_class_method :current_url
+
+      def client_ip(request)
+        trusted_ip = request_value(request, :remote_ip) || request_value(request, :ip)
+        return trusted_ip if present?(trusted_ip)
+
+        forwarded_for = TracingHeaders.extract_header(request, 'X-Forwarded-For')
+        forwarded_ip = forwarded_for.split(',').first&.strip if forwarded_for
+        return forwarded_ip if present?(forwarded_ip)
+
+        env_value(request, 'REMOTE_ADDR')
+      end
+      private_class_method :client_ip
+
+      def present?(value)
+        !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+      end
+      private_class_method :present?
+
+      def add_property(properties, key, value)
+        return if value.nil?
+
+        serialized = value.to_s
+        return if serialized.empty?
+
+        properties[key] = serialized
+      end
+      private_class_method :add_property
+
+      def request_value(request, method_name)
+        return unless request.respond_to?(method_name)
+
+        request.public_send(method_name)
+      rescue StandardError
+        nil
+      end
+      private_class_method :request_value
+
+      def env_value(request, key)
+        request.respond_to?(:get_header) ? request.get_header(key) : request.env[key]
+      rescue StandardError
+        nil
+      end
+      private_class_method :env_value
+    end
+
+    private_constant :RequestMetadata
+  end
+end

data/lib/posthog/rails/tracing_headers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Rails
+    # Helpers for extracting and sanitizing PostHog tracing headers from Rack/Rails requests.
+    module TracingHeaders
+      MAX_HEADER_VALUE_LENGTH = 1000
+      CONTROL_CHARACTERS = /[[:cntrl:]]/
+
+      module_function
+
+      def sanitize_header_value(value)
+        return nil unless value.is_a?(String)
+
+        sanitized = value.strip.gsub(CONTROL_CHARACTERS, '').strip
+        return nil if sanitized.empty?
+
+        sanitized[0, MAX_HEADER_VALUE_LENGTH]
+      end
+
+      def extract_header(request_or_env, header_name)
+        candidates = header_candidates(header_name)
+
+        candidates.each do |candidate|
+          value = header_value(request_or_env, candidate)
+          sanitized = sanitize_header_value(value)
+          return sanitized if sanitized
+        end
+
+        env = request_env(request_or_env)
+        return nil unless env.respond_to?(:each)
+
+        target_names = candidates.map { |candidate| normalize_header_name(candidate) }
+        env.each do |key, value|
+          next unless target_names.include?(normalize_header_name(key))
+
+          sanitized = sanitize_header_value(value)
+          return sanitized if sanitized
+        end
+
+        nil
+      end
+
+      def header_candidates(header_name)
+        canonical = header_name.to_s
+        rack = "HTTP_#{canonical.upcase.tr('-', '_')}"
+        [canonical, canonical.downcase, rack]
+      end
+      private_class_method :header_candidates
+
+      def header_value(request_or_env, header_name)
+        if request_or_env.respond_to?(:headers)
+          value = request_or_env.headers[header_name]
+          return value unless value.nil?
+        end
+
+        env = request_env(request_or_env)
+        return nil unless env.respond_to?(:[])
+
+        env[header_name]
+      end
+      private_class_method :header_value
+
+      def request_env(request_or_env)
+        request_or_env.respond_to?(:env) ? request_or_env.env : request_or_env
+      end
+      private_class_method :request_env
+
+      def normalize_header_name(header_name)
+        header_name.to_s.upcase.tr('-', '_')
+      end
+      private_class_method :normalize_header_name
+    end
+
+    private_constant :TracingHeaders
+  end
+end

data/lib/posthog/rails.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'posthog/rails/configuration'
+require 'posthog/rails/tracing_headers'
+require 'posthog/rails/request_metadata'
+require 'posthog/rails/request_context'
 require 'posthog/rails/capture_exceptions'
 require 'posthog/rails/rescued_exception_interceptor'
 require 'posthog/rails/active_job'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-rails
 version: !ruby/object:Gem::Version
-  version: 3.8.1
+  version: 3.9.0
 platform: ruby
 authors:
 - PostHog
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
 description: Automatic exception tracking and instrumentation for Ruby on Rails applications
   using PostHog
 email: engineering@posthog.com
@@ -54,7 +54,10 @@ files:
 - lib/posthog/rails/error_subscriber.rb
 - lib/posthog/rails/parameter_filter.rb
 - lib/posthog/rails/railtie.rb
+- lib/posthog/rails/request_context.rb
+- lib/posthog/rails/request_metadata.rb
 - lib/posthog/rails/rescued_exception_interceptor.rb
+- lib/posthog/rails/tracing_headers.rb
 homepage: https://github.com/PostHog/posthog-ruby
 licenses:
 - MIT