posthog-rails 3.5.0 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c928e33ae64462619dd81b5b785402c17f4cc5ebba9d7858cb33d7b38b426d4a
-  data.tar.gz: 5ee1084fde161538e21b53f257bc485aa9fafc0b6b4549776a28ab5d56c2de7a
+  metadata.gz: ea6edcb493fd06b49850a250f1c4c4b41ececd9c875918472419a8c7ccf7cca0
+  data.tar.gz: f2ef41e5646688bbd593b6f002b0a7b6514cce97a65d60013c6a4664cebf854d
 SHA512:
-  metadata.gz: 3e3cc76336d84ab77d948e5a0504694926565bec21f8b535d70e5eb6671449b0676e60677f9257170b5e84c703e351baf9fe35ee091544df26859fdba7210f4c
-  data.tar.gz: 54d4dd5aee80aa5f85961672934cb7c565e16342327678f9352ed7ed6e9d484479418585ef4e9cbf39eed6e00063290c2a9e253f50621796f8e50774c97a5ade
+  metadata.gz: 3941f7f40575f422511be6326f421bafa4d4b24b5996d84aa0c7a24b4e30b79770449ce6064248a1af6a9b61121990fd838394666a0fed16ae5cb661af53c608
+  data.tar.gz: 0edf54ddca0d8f08d674dd8bf0102a6bfd77378ce4ce92027256f7331178d20c56bc3787d30b1b9610c9b74ef5b08bcb0e3f4d66b040d10300ecb8584044b1bc

data/lib/generators/posthog/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Posthog
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc 'Creates a PostHog initializer file at config/initializers/posthog.rb'
+
+      source_root File.expand_path('../../..', __dir__)
+
+      def copy_initializer
+        copy_file 'examples/posthog.rb', 'config/initializers/posthog.rb'
+      end
+
+      def show_readme
+        say ''
+        say 'PostHog Rails has been installed!', :green
+        say ''
+        say 'Next steps:', :yellow
+        say '  1. Edit config/initializers/posthog.rb with your PostHog API key'
+        say '  2. Set environment variables:'
+        say '     - POSTHOG_API_KEY (required)'
+        say '     - POSTHOG_PERSONAL_API_KEY (optional, for feature flags)'
+        say ''
+        say 'For more information, see: https://posthog.com/docs/libraries/ruby'
+        say ''
+      end
+    end
+  end
+end

data/lib/posthog/rails/active_job.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'posthog/rails/parameter_filter'
+
+module PostHog
+  module Rails
+    # ActiveJob integration to capture exceptions from background jobs
+    module ActiveJobExtensions
+      include ParameterFilter
+
+      def self.prepended(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # DSL for defining how to extract distinct_id from job arguments
+        # Example:
+        #   class MyJob < ApplicationJob
+        #     posthog_distinct_id ->(user, arg1, arg2) { user.id }
+        #     def perform(user, arg1, arg2)
+        #       # ...
+        #     end
+        #   end
+        def posthog_distinct_id(proc = nil, &block)
+          @posthog_distinct_id_proc = proc || block
+        end
+
+        def posthog_distinct_id_proc
+          @posthog_distinct_id_proc
+        end
+      end
+
+      def perform_now
+        super
+      rescue StandardError => e
+        # Capture the exception with job context
+        capture_job_exception(e)
+        raise
+      end
+
+      private
+
+      def capture_job_exception(exception)
+        return unless PostHog::Rails.config&.auto_instrument_active_job
+
+        # Build distinct_id from job arguments if possible
+        distinct_id = extract_distinct_id_from_job
+
+        properties = {
+          '$exception_source' => 'active_job',
+          '$job_class' => self.class.name,
+          '$job_id' => job_id,
+          '$queue_name' => queue_name,
+          '$job_priority' => priority,
+          '$job_executions' => executions
+        }
+
+        # Add serialized job arguments (be careful with sensitive data)
+        properties['$job_arguments'] = sanitize_job_arguments(arguments) if arguments.present?
+
+        PostHog.capture_exception(exception, distinct_id, properties)
+      rescue StandardError => e
+        # Don't let PostHog errors break job processing
+        PostHog::Logging.logger.error("Failed to capture job exception: #{e.message}")
+      end
+
+      def extract_distinct_id_from_job
+        # First, check if the job class defines a custom extractor
+        return self.class.posthog_distinct_id_proc.call(*arguments) if self.class.posthog_distinct_id_proc
+
+        # Fallback: look for explicit user_id in hash arguments only
+        arguments.each do |arg|
+          if 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
+
+      def sanitize_job_arguments(args)
+        # Convert arguments to a safe format
+        args.map do |arg|
+          case arg
+          when String
+            # Truncate long strings to prevent huge payloads
+            arg.length > 100 ? "[FILTERED: #{arg.length} chars]" : arg
+          when Integer, Float, TrueClass, FalseClass, NilClass
+            arg
+          when Hash
+            # Use Rails' filter_parameters to filter sensitive data
+            filter_sensitive_params(arg)
+          when defined?(ActiveRecord::Base) && ActiveRecord::Base
+            { class: arg.class.name, id: arg.id }
+          else
+            arg.class.name
+          end
+        end
+      rescue StandardError
+        ['<serialization error>']
+      end
+    end
+  end
+end

data/lib/posthog/rails/capture_exceptions.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'posthog/rails/parameter_filter'
+
+module PostHog
+  module Rails
+    # Middleware that captures exceptions and sends them to PostHog
+    class CaptureExceptions
+      include ParameterFilter
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # Signal that we're in a web request context
+        # ErrorSubscriber will skip capture for web requests to avoid duplicates
+        PostHog::Rails.enter_web_request
+
+        response = @app.call(env)
+
+        # Check if there was an exception that Rails handled
+        exception = collect_exception(env)
+
+        capture_exception(exception, env) if exception && should_capture?(exception)
+
+        response
+      rescue StandardError => e
+        # Capture unhandled exceptions
+        capture_exception(e, env) if should_capture?(e)
+        raise
+      ensure
+        PostHog::Rails.exit_web_request
+      end
+
+      private
+
+      def collect_exception(env)
+        # Rails stores exceptions in these env keys
+        env['action_dispatch.exception'] ||
+          env['rack.exception'] ||
+          env['posthog.rescued_exception']
+      end
+
+      def should_capture?(exception)
+        return false unless PostHog::Rails.config&.auto_capture_exceptions
+        return false unless PostHog::Rails.config&.should_capture_exception?(exception)
+
+        true
+      end
+
+      def capture_exception(exception, env)
+        request = ActionDispatch::Request.new(env)
+        distinct_id = extract_distinct_id(env, request)
+        additional_properties = build_properties(request, env)
+
+        PostHog.capture_exception(exception, distinct_id, additional_properties)
+      rescue StandardError => e
+        PostHog::Logging.logger.error("Failed to capture exception: #{e.message}")
+        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
+        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
+          end
+        end
+
+        # Fallback to session ID or nil
+        request.session&.id&.to_s
+      end
+
+      def extract_user_id(user)
+        # Use configured method if specified
+        method_name = PostHog::Rails.config&.user_id_method
+        return user.send(method_name) if method_name && user.respond_to?(method_name)
+
+        # Try explicit PostHog method (allows users to customize without config)
+        return user.posthog_distinct_id if user.respond_to?(:posthog_distinct_id)
+        return user.distinct_id if user.respond_to?(:distinct_id)
+
+        # Try common ID methods
+        return user.id if user.respond_to?(:id)
+        return user['id'] if user.respond_to?(:[]) && user['id']
+        return user.pk if user.respond_to?(:pk)
+        return user['pk'] if user.respond_to?(:[]) && user['pk']
+        return user.uuid if user.respond_to?(:uuid)
+        return user['uuid'] if user.respond_to?(:[]) && user['uuid']
+
+        user.to_s
+      end
+
+      def build_properties(request, env)
+        properties = {
+          '$exception_source' => 'rails',
+          '$request_url' => safe_serialize(request.url),
+          '$request_method' => safe_serialize(request.method),
+          '$request_path' => safe_serialize(request.path)
+        }
+
+        # Add controller and action if available
+        if env['action_controller.instance']
+          controller = env['action_controller.instance']
+          properties['$controller'] = safe_serialize(controller.controller_name)
+          properties['$action'] = safe_serialize(controller.action_name)
+        end
+
+        # Add request parameters (be careful with sensitive data)
+        if request.params.present?
+          filtered_params = filter_sensitive_params(request.params)
+          # Safe serialize to handle any complex objects in params
+          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
+
+        # Add referrer
+        properties['$referrer'] = safe_serialize(request.referrer) if request.referrer
+
+        properties
+      end
+    end
+  end
+end

data/lib/posthog/rails/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Rails
+    class Configuration
+      # Whether to automatically capture exceptions from Rails
+      attr_accessor :auto_capture_exceptions
+
+      # Whether to capture exceptions that Rails rescues (e.g., with rescue_from)
+      attr_accessor :report_rescued_exceptions
+
+      # Whether to automatically instrument ActiveJob
+      attr_accessor :auto_instrument_active_job
+
+      # List of exception classes to ignore (in addition to default)
+      attr_accessor :excluded_exceptions
+
+      # Whether to capture the current user context in exceptions
+      attr_accessor :capture_user_context
+
+      # Method name to call on controller to get user ID (default: :current_user)
+      attr_accessor :current_user_method
+
+      # Method name to call on user object to get distinct_id (default: auto-detect)
+      # When nil, tries: posthog_distinct_id, distinct_id, id, pk, uuid in order
+      attr_accessor :user_id_method
+
+      def initialize
+        @auto_capture_exceptions = false
+        @report_rescued_exceptions = false
+        @auto_instrument_active_job = false
+        @excluded_exceptions = []
+        @capture_user_context = true
+        @current_user_method = :current_user
+        @user_id_method = nil
+      end
+
+      # Default exceptions that Rails apps typically don't want to track
+      def default_excluded_exceptions
+        [
+          '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'
+        ]
+      end
+
+      def should_capture_exception?(exception)
+        exception_name = exception.class.name
+        !all_excluded_exceptions.include?(exception_name)
+      end
+
+      private
+
+      def all_excluded_exceptions
+        default_excluded_exceptions + excluded_exceptions
+      end
+    end
+  end
+end

data/lib/posthog/rails/error_subscriber.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'posthog/rails/parameter_filter'
+
+module PostHog
+  module Rails
+    # Rails 7.0+ error reporter integration
+    # This integrates with Rails.error.handle and Rails.error.record
+    class ErrorSubscriber
+      include ParameterFilter
+
+      def report(error, handled:, severity:, context:, source: nil)
+        return unless PostHog::Rails.config&.auto_capture_exceptions
+        return unless PostHog::Rails.config&.should_capture_exception?(error)
+        # Skip if in a web request - CaptureExceptions middleware will handle it
+        # with richer context (URL, params, controller, etc.)
+        return if PostHog::Rails.in_web_request?
+
+        distinct_id = context[:user_id] || context[:distinct_id]
+
+        properties = {
+          '$exception_source' => source || 'rails_error_reporter',
+          '$exception_handled' => handled,
+          '$exception_severity' => severity.to_s
+        }
+
+        # Add context information (safely serialized to avoid circular references)
+        if context.present?
+          context.each do |key, value|
+            next if key.in?(%i[user_id distinct_id])
+
+            properties["$context_#{key}"] = safe_serialize(value)
+          end
+        end
+
+        PostHog.capture_exception(error, distinct_id, properties)
+      rescue StandardError => e
+        PostHog::Logging.logger.error("Failed to report error via subscriber: #{e.message}")
+        PostHog::Logging.logger.error("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
+      end
+    end
+  end
+end

data/lib/posthog/rails/parameter_filter.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Rails
+    # Shared utility module for filtering sensitive parameters
+    #
+    # This module provides consistent parameter filtering across all PostHog Rails
+    # components, leveraging Rails' built-in parameter filtering when available.
+    # It automatically detects the correct Rails parameter filtering API based on
+    # the Rails version.
+    #
+    # @example Usage in a class
+    #   class MyClass
+    #     include PostHog::Rails::ParameterFilter
+    #
+    #     def my_method(params)
+    #       filtered = filter_sensitive_params(params)
+    #       PostHog.capture(event: 'something', properties: filtered)
+    #     end
+    #   end
+    module ParameterFilter
+      EMPTY_HASH = {}.freeze
+      MAX_STRING_LENGTH = 10_000
+      MAX_DEPTH = 10
+
+      if ::Rails.version.to_f >= 6.0
+        def self.backend
+          ActiveSupport::ParameterFilter
+        end
+      else
+        def self.backend
+          ActionDispatch::Http::ParameterFilter
+        end
+      end
+
+      # Filter sensitive parameters from a hash, respecting Rails configuration.
+      #
+      # Uses Rails' configured filter_parameters (e.g., :password, :token, :api_key)
+      # to automatically filter sensitive data that the Rails app has configured.
+      #
+      # @param params [Hash] The parameters to filter
+      # @return [Hash] Filtered parameters with sensitive data masked
+      def filter_sensitive_params(params)
+        return EMPTY_HASH unless params.is_a?(Hash)
+        return params unless ::Rails.application
+
+        filter_parameters = ::Rails.application.config.filter_parameters
+        parameter_filter = ParameterFilter.backend.new(filter_parameters)
+
+        parameter_filter.filter(params)
+      end
+
+      # Safely serialize a value to a JSON-compatible format.
+      #
+      # Handles circular references and complex objects by converting them to
+      # simple primitives or string representations. This prevents SystemStackError
+      # when serializing objects with circular references (like ActiveRecord models).
+      #
+      # @param value [Object] The value to serialize
+      # @param seen [Set] Set of object_ids already visited (for cycle detection)
+      # @param depth [Integer] Current recursion depth
+      # @return [Object] A JSON-safe value (String, Numeric, Boolean, nil, Array, or Hash)
+      def safe_serialize(value, seen = Set.new, depth = 0)
+        return '[max depth exceeded]' if depth > MAX_DEPTH
+
+        case value
+        when nil, true, false, Integer, Float
+          value
+        when String
+          truncate_string(value)
+        when Symbol
+          value.to_s
+        when Time, DateTime
+          value.iso8601(3)
+        when Date
+          value.iso8601
+        when Array
+          serialize_array(value, seen, depth)
+        when Hash
+          serialize_hash(value, seen, depth)
+        else
+          serialize_object(value, seen)
+        end
+      rescue StandardError => e
+        "[serialization error: #{e.class}]"
+      end
+
+      private
+
+      def truncate_string(str)
+        return str if str.length <= MAX_STRING_LENGTH
+
+        "#{str[0...MAX_STRING_LENGTH]}... (truncated)"
+      end
+
+      def serialize_array(array, seen, depth)
+        return '[circular reference]' if seen.include?(array.object_id)
+
+        seen = seen.dup.add(array.object_id)
+        array.first(100).map { |item| safe_serialize(item, seen, depth + 1) }
+      end
+
+      def serialize_hash(hash, seen, depth)
+        return '[circular reference]' if seen.include?(hash.object_id)
+
+        seen = seen.dup.add(hash.object_id)
+        result = {}
+        hash.first(100).each do |key, val|
+          result[key.to_s] = safe_serialize(val, seen, depth + 1)
+        end
+        result
+      end
+
+      def serialize_object(obj, seen)
+        return '[circular reference]' if seen.include?(obj.object_id)
+
+        # For ActiveRecord and similar objects, use id if available
+        return "#{obj.class.name}##{obj.id}" if obj.respond_to?(:id) && obj.respond_to?(:class)
+
+        # Try to_s as fallback, but limit length
+        str = obj.to_s
+        truncate_string(str)
+      rescue StandardError
+        "[#{obj.class.name}]"
+      end
+    end
+  end
+end