txlemetry-rails 4.0.0

data/lib/txlemetry/rails/railtie.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/facade'
+
+module Txlemetry
+  module Rails
+    class Railtie < ::Rails::Railtie
+      # Keep the historical Railtie initializer name, but install the facade at
+      # load time so application initializers can call Txlemetry.init.
+      initializer 'txlemetry.set_configs' do |_app|
+        Txlemetry::Rails.install_txlemetry_facade!
+      end
+
+      # Insert middleware for request context and exception capturing
+      initializer 'txlemetry.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,
+          Txlemetry::Rails::RequestContext
+        )
+
+        # Insert after DebugExceptions to catch rescued exceptions
+        insert_middleware_after(
+          app, ActionDispatch::DebugExceptions,
+          Txlemetry::Rails::RescuedExceptionInterceptor
+        )
+
+        # Insert after ShowExceptions to capture all exceptions
+        insert_middleware_after(
+          app, ActionDispatch::ShowExceptions,
+          Txlemetry::Rails::CaptureExceptions
+        )
+      end
+
+      # After initialization, set up remaining integrations
+      config.after_initialize do |_app|
+        # Hook into ActiveJob only if enabled
+        if Txlemetry::Rails.config&.auto_instrument_active_job
+          ActiveSupport.on_load(:active_job) do
+            prepend Txlemetry::Rails::ActiveJobExtensions
+          end
+        end
+
+        next unless Txlemetry.initialized?
+
+        # Register with Rails error reporter (Rails 7.0+)
+        register_error_subscriber if rails_version_above_7?
+      end
+
+      # Opt-in: forward logs to Txlemetry Logs over OTLP
+      config.after_initialize do
+        install_txlemetry_logs if Txlemetry::Rails.config&.logs_enabled
+      end
+
+      # Ensure Txlemetry shuts down gracefully (register only once)
+      config.after_initialize do
+        next if @txlemetry_at_exit_registered
+
+        @txlemetry_at_exit_registered = true
+        at_exit do
+          Txlemetry::Rails::Logs::Setup.shutdown
+          Txlemetry.client&.shutdown if Txlemetry.initialized?
+        end
+      end
+
+      MISSING_MIDDLEWARE_MESSAGE = 'No such middleware to insert'
+      MIDDLEWARE_FALLBACK_OPERATION = :txlemetry_insert_middleware_with_fallback
+
+      module MiddlewareStackFallback
+        def txlemetry_insert_middleware_with_fallback(location, target, middleware)
+          Txlemetry::Rails::Railtie.instance.send(
+            :insert_middleware_with_fallback,
+            self,
+            location,
+            target,
+            middleware
+          )
+        end
+
+        private :txlemetry_insert_middleware_with_fallback
+      end
+
+      private_constant :MISSING_MIDDLEWARE_MESSAGE,
+                       :MIDDLEWARE_FALLBACK_OPERATION,
+                       :MiddlewareStackFallback
+
+      # @api private
+      # @return [void]
+      def insert_middleware_after(app, target, middleware)
+        insert_middleware(app.config.middleware, :after, target, middleware)
+      end
+
+      # @api private
+      # @return [void]
+      def insert_middleware_before(app, target, middleware)
+        insert_middleware(app.config.middleware, :before, target, middleware)
+      end
+
+      # During initialization, app.config.middleware is usually a
+      # Rails::Configuration::MiddlewareStackProxy. The proxy only records
+      # operations, so missing-target errors happen later when Rails builds the
+      # real ActionDispatch::MiddlewareStack. Add our own deferred operation so
+      # we can fall back at build time instead of crashing or silently skipping.
+      def insert_middleware(middleware_stack, location, target, middleware)
+        if middleware_stack_proxy?(middleware_stack)
+          append_middleware_operation(middleware_stack, location, target, middleware)
+        else
+          insert_middleware_with_fallback(middleware_stack, location, target, middleware)
+        end
+      end
+
+      def middleware_stack_proxy?(middleware_stack)
+        defined?(::Rails::Configuration::MiddlewareStackProxy) &&
+          middleware_stack.instance_of?(::Rails::Configuration::MiddlewareStackProxy) &&
+          middleware_stack.instance_variable_defined?(:@operations)
+      end
+
+      def append_middleware_operation(middleware_stack, location, target, middleware)
+        operations = middleware_stack.instance_variable_get(:@operations)
+
+        if callable_middleware_operations?(middleware_stack, operations)
+          operations << lambda do |resolved_stack|
+            insert_middleware_with_fallback(resolved_stack, location, target, middleware)
+          end
+        else
+          ensure_middleware_stack_fallback_operation!
+          operations << [MIDDLEWARE_FALLBACK_OPERATION, [location, target, middleware], nil]
+        end
+      end
+
+      def callable_middleware_operations?(middleware_stack, operations)
+        operation = operations.first || probe_middleware_operation(middleware_stack)
+
+        operation.respond_to?(:call)
+      end
+
+      def probe_middleware_operation(middleware_stack)
+        probe = middleware_stack.class.new
+        probe.use(Object)
+        probe.instance_variable_get(:@operations).first
+      end
+
+      def ensure_middleware_stack_fallback_operation!
+        require 'action_dispatch/middleware/stack' unless defined?(::ActionDispatch::MiddlewareStack)
+        return if ::ActionDispatch::MiddlewareStack < MiddlewareStackFallback
+
+        ::ActionDispatch::MiddlewareStack.include(MiddlewareStackFallback)
+      end
+
+      def insert_middleware_with_fallback(middleware_stack, location, target, middleware)
+        perform_middleware_insert(middleware_stack, location, target, middleware)
+      rescue RuntimeError => e
+        raise unless missing_middleware_error?(e)
+
+        fallback_insert_middleware(middleware_stack, location, target, middleware)
+      end
+
+      def perform_middleware_insert(middleware_stack, location, target, middleware)
+        if location == :after
+          middleware_stack.insert_after(target, middleware)
+        else
+          middleware_stack.insert_before(target, middleware)
+        end
+      end
+
+      def fallback_insert_middleware(middleware_stack, location, target, middleware)
+        fallback_position = if location == :before && middleware_stack.respond_to?(:unshift)
+                              middleware_stack.unshift(middleware)
+                              'beginning'
+                            else
+                              middleware_stack.use(middleware)
+                              'end'
+                            end
+
+        Txlemetry::Logging.logger.warn(
+          "Could not find #{target.inspect} in the Rails middleware stack; " \
+          "inserted #{middleware.inspect} at the #{fallback_position} " \
+          'of the stack instead.'
+        )
+      end
+
+      def missing_middleware_error?(error)
+        error.message.start_with?(MISSING_MIDDLEWARE_MESSAGE)
+      end
+
+      private :insert_middleware,
+              :middleware_stack_proxy?,
+              :append_middleware_operation,
+              :callable_middleware_operations?,
+              :probe_middleware_operation,
+              :ensure_middleware_stack_fallback_operation!,
+              :insert_middleware_with_fallback,
+              :perform_middleware_insert,
+              :fallback_insert_middleware,
+              :missing_middleware_error?
+
+      # Build the Txlemetry Logs pipeline and broadcast Rails.logger into it.
+      #
+      # @api private
+      # @return [void]
+      def self.install_txlemetry_logs
+        unless Txlemetry.initialized?
+          # logs_enabled is an explicit opt-in, so leave a breadcrumb instead
+          # of silently skipping when Txlemetry.init never ran.
+          Txlemetry::Logging.logger.warn(
+            'Txlemetry Logs is enabled but Txlemetry.init has not been called; ' \
+            'skipping log forwarding. Call Txlemetry.init in your initializer.'
+          )
+          return
+        end
+
+        # Mirror the core client: when it is disabled (missing/blank api_key)
+        # every capture no-ops, so log forwarding should stay off too. The
+        # client already logs its own missing-api_key error, so skip quietly.
+        return unless Txlemetry.client.enabled?
+
+        appender = Txlemetry::Rails::Logs::Setup.install
+        return if appender.nil?
+
+        broadcast_rails_logger(appender) if Txlemetry::Rails.config&.logs_forward_rails_logger
+      rescue StandardError => e
+        Txlemetry::Logging.logger.warn("Failed to set up Txlemetry Logs: #{e.message}")
+      end
+
+      # Attach the appender to Rails.logger, supporting both the Rails 7.1+
+      # BroadcastLogger and the older ActiveSupport::Logger.broadcast mechanism.
+      #
+      # @api private
+      # @return [void]
+      def self.broadcast_rails_logger(appender)
+        logger = ::Rails.logger
+        return unless logger
+
+        if logger.respond_to?(:broadcast_to)
+          logger.broadcast_to(appender)
+        elsif defined?(ActiveSupport::Logger) && ActiveSupport::Logger.respond_to?(:broadcast)
+          logger.extend(ActiveSupport::Logger.broadcast(appender))
+        else
+          Txlemetry::Logging.logger.warn(
+            'Txlemetry Logs could not broadcast Rails.logger; no compatible broadcast mechanism found.'
+          )
+        end
+      end
+
+      # @api private
+      # @return [void]
+      def self.register_error_subscriber
+        return unless Txlemetry::Rails.config&.auto_capture_exceptions
+
+        subscriber = Txlemetry::Rails::ErrorSubscriber.new
+        ::Rails.error.subscribe(subscriber)
+      rescue StandardError => e
+        Txlemetry::Logging.logger.warn("Failed to register error subscriber: #{e.message}")
+        Txlemetry::Logging.logger.warn("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
+      end
+
+      # @api private
+      # @return [Boolean]
+      def self.rails_version_above_7?
+        ::Rails.version.to_f >= 7.0
+      end
+    end
+
+    # Configuration wrapper for the init block
+    class InitConfig
+      # @param base_options [Hash] Initial core SDK options.
+      def initialize(base_options = {})
+        @base_options = base_options
+      end
+
+      # Core Txlemetry options
+      #
+      # @param value [String]
+      # @return [String]
+      def api_key=(value)
+        @base_options[:api_key] = value
+      end
+
+      # The credential used for local feature flag evaluation and remote config. Accepts either a
+      # Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`).
+      #
+      # @param value [String, nil]
+      # @return [String, nil]
+      def secret_key=(value)
+        @base_options[:secret_key] = value
+      end
+
+      # @deprecated Use {#secret_key=} instead. Retained as an alias.
+      # @param value [String, nil]
+      # @return [String, nil]
+      def personal_api_key=(value)
+        @base_options[:personal_api_key] = value
+      end
+
+      # @param value [String]
+      # @return [String]
+      def host=(value)
+        @base_options[:host] = value
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def max_queue_size=(value)
+        @base_options[:max_queue_size] = value
+      end
+
+      # @param value [Boolean]
+      # @return [Boolean]
+      def test_mode=(value)
+        @base_options[:test_mode] = value
+      end
+
+      # @param value [Boolean]
+      # @return [Boolean]
+      def sync_mode=(value)
+        @base_options[:sync_mode] = value
+      end
+
+      # @param value [Boolean]
+      # @return [Boolean]
+      def compress_request=(value)
+        @base_options[:compress_request] = value
+      end
+
+      # @param value [Proc]
+      # @return [Proc]
+      def on_error=(value)
+        @base_options[:on_error] = value
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def feature_flags_polling_interval=(value)
+        @base_options[:feature_flags_polling_interval] = value
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def feature_flag_request_timeout_seconds=(value)
+        @base_options[:feature_flag_request_timeout_seconds] = value
+      end
+
+      # @param value [Proc]
+      # @return [Proc]
+      def before_send=(value)
+        @base_options[:before_send] = value
+      end
+
+      # @return [Hash] Core SDK options suitable for {Txlemetry::Client.new}.
+      def to_client_options
+        @base_options
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/request_context.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'txlemetry/internal/context'
+require 'txlemetry/rails/tracing_headers'
+require 'txlemetry/rails/request_metadata'
+
+module Txlemetry
+  module Rails
+    # Rack middleware that creates a request-local Txlemetry context from tracing headers.
+    #
+    # @api private
+    class RequestContext
+      # @param app [#call] Rack application.
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
+      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?
+        Txlemetry::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/txlemetry/rails/request_metadata.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/tracing_headers'
+
+module Txlemetry
+  module Rails
+    # Internal helpers for extracting request metadata owned by RequestContext.
+    #
+    # @api private
+    module RequestMetadata
+      module_function
+
+      # @param request [Object] Rack or Rails request object.
+      # @return [Hash] Event properties extracted from the request.
+      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))
+        user_agent = TracingHeaders.extract_header(request, 'User-Agent')
+        add_property(properties, '$user_agent', user_agent)
+        # Mirrored into $raw_user_agent, the standardized property Txlemetry's
+        # server-side classification (e.g. bot detection) reads
+        add_property(properties, '$raw_user_agent', 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/txlemetry/rails/rescued_exception_interceptor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Portions of this file are derived from getsentry/sentry-ruby
+# Copyright (c) 2020 Sentry
+# Licensed under the MIT License: https://github.com/getsentry/sentry-ruby/blob/master/LICENSE
+
+module Txlemetry
+  module Rails
+    # Middleware that intercepts exceptions that are rescued by Rails.
+    # This middleware runs before ShowExceptions and captures the exception
+    # so we can report it even if Rails rescues it.
+    #
+    # @api private
+    class RescuedExceptionInterceptor
+      # @param app [#call] Rack application.
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
+      def call(env)
+        @app.call(env)
+      rescue StandardError => e
+        # Store the exception so CaptureExceptions middleware can report it
+        env['txlemetry.rescued_exception'] = e if should_intercept?
+        raise e
+      end
+
+      private
+
+      def should_intercept?
+        Txlemetry::Rails.config&.report_rescued_exceptions
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/tracing_headers.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module Rails
+    # Helpers for extracting and sanitizing Txlemetry tracing headers from Rack/Rails requests.
+    #
+    # @api private
+    module TracingHeaders
+      MAX_HEADER_VALUE_LENGTH = 1000
+      CONTROL_CHARACTERS = /[[:cntrl:]]/
+
+      module_function
+
+      # @param value [Object]
+      # @return [String, nil]
+      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
+
+      # @param request_or_env [Object, Hash] Rack request, Rails request, or Rack env hash.
+      # @param header_name [String]
+      # @return [String, nil]
+      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/txlemetry/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module Rails
+    VERSION = '4.0.0'
+  end
+end