txlemetry-rails 4.0.0

data/lib/txlemetry/rails/configuration.rb

@@ -0,0 +1,120 @@
+# 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
+    class Configuration
+      # Default cap on log records forwarded to Txlemetry Logs per minute.
+      DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE = 6_000
+
+      # @return [Boolean] Whether to automatically capture exceptions from Rails. Defaults to false.
+      attr_accessor :auto_capture_exceptions
+
+      # @return [Boolean] Whether to capture exceptions that Rails rescues (e.g., with rescue_from). Defaults to false.
+      attr_accessor :report_rescued_exceptions
+
+      # @return [Boolean] Whether to automatically instrument ActiveJob. Defaults to false.
+      attr_accessor :auto_instrument_active_job
+
+      # @return [Array<String>] Exception class names to ignore in addition to the defaults.
+      attr_accessor :excluded_exceptions
+
+      # @return [Boolean] Whether to use Txlemetry tracing headers for request-scoped identity/session context.
+      #   Defaults to true.
+      attr_accessor :use_tracing_headers
+
+      # @return [Boolean] Whether to capture the current user context in exceptions. Defaults to true.
+      attr_accessor :capture_user_context
+
+      # @return [Symbol] Method name to call on controller to get the current user. Defaults to :current_user.
+      attr_accessor :current_user_method
+
+      # @return [Proc, nil] Callable used to resolve the current user. When set, this takes precedence over
+      #   current_user_method. The callable may accept the controller instance or no arguments.
+      attr_accessor :current_user_resolver
+
+      # @return [Symbol, nil] Method name to call on the user object to get distinct_id. When nil, tries:
+      #   txlemetry_distinct_id, distinct_id, id, pk, uuid in order.
+      attr_accessor :user_id_method
+
+      # @return [Boolean] Master switch for forwarding logs to Txlemetry Logs over OTLP. Defaults to false.
+      attr_accessor :logs_enabled
+
+      # @return [Boolean] Whether to broadcast Rails.logger output into the Txlemetry Logs sink. Defaults to true
+      #   (only takes effect when {#logs_enabled} is true).
+      attr_accessor :logs_forward_rails_logger
+
+      # @return [Integer, Symbol, nil] Minimum severity to forward to Txlemetry Logs. When nil, inherits the
+      #   current Rails.logger level. Accepts a Logger severity constant (e.g. Logger::INFO) or symbol (:info).
+      attr_accessor :logs_level
+
+      # @return [Integer, String, nil] Maximum log records forwarded to Txlemetry Logs per minute, protecting
+      #   the ingestion quota from runaway log volume. Defaults to 6000. Numeric strings (e.g. from ENV) are
+      #   coerced. Set to nil, 0, or a negative value to disable the cap; an unparseable value falls back to
+      #   the default with a warning.
+      attr_accessor :logs_max_records_per_minute
+
+      # @return [Proc, nil] Callback invoked with each log record hash (:timestamp, :severity, :body,
+      #   :attributes — where :severity is a symbol such as :warn) before it is sent to Txlemetry Logs.
+      #   Return a (possibly modified) hash to send, or nil to drop the record — useful for scrubbing
+      #   PII. If the callback raises, the record is dropped. Defaults to nil.
+      attr_accessor :logs_before_send
+
+      # @return [Txlemetry::Rails::Configuration]
+      def initialize
+        @auto_capture_exceptions = false
+        @report_rescued_exceptions = false
+        @auto_instrument_active_job = false
+        @excluded_exceptions = []
+        @use_tracing_headers = true
+        @capture_user_context = true
+        @current_user_method = :current_user
+        @current_user_resolver = nil
+        @user_id_method = nil
+        @logs_enabled = false
+        @logs_forward_rails_logger = true
+        @logs_level = nil
+        @logs_max_records_per_minute = DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE
+        @logs_before_send = nil
+      end
+
+      # Default exceptions that Rails apps typically don't want to track.
+      #
+      # @return [Array<String>]
+      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::MimeNegotiation::InvalidType',
+          'ActionDispatch::Http::Parameters::ParseError',
+          'ActiveRecord::RecordNotFound',
+          'ActiveRecord::RecordNotUnique'
+        ]
+      end
+
+      # @param exception [Exception] The exception to check.
+      # @return [Boolean] Whether the exception should be captured.
+      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/txlemetry/rails/error_subscriber.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/parameter_filter'
+
+module Txlemetry
+  module Rails
+    # Rails 7.0+ error reporter integration.
+    # This integrates with Rails.error.handle and Rails.error.record.
+    #
+    # @api private
+    class ErrorSubscriber
+      include ParameterFilter
+
+      # @param error [Exception] Error reported by Rails.
+      # @param handled [Boolean]
+      # @param severity [Symbol, String]
+      # @param context [Hash]
+      # @param source [String, nil]
+      # @return [void]
+      def report(error, handled:, severity:, context:, source: nil)
+        return unless Txlemetry::Rails.config&.auto_capture_exceptions
+        return unless Txlemetry::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 Txlemetry::Rails.in_web_request?
+        # ActionDispatch::Executor reports the exception once the response has
+        # unwound past our middleware, so the flag above is already cleared.
+        # CaptureExceptions marks what it captured to catch that late report.
+        return if Txlemetry::Rails.web_exception_captured?(error)
+        return if Txlemetry::Rails.config&.auto_instrument_active_job &&
+                  Txlemetry::Rails.active_job_exception_captured?(error)
+
+        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
+
+        Txlemetry.capture_exception(
+          error,
+          distinct_id,
+          properties,
+          mechanism: { 'type' => 'rails_error_reporter', 'handled' => handled }
+        )
+      rescue StandardError => e
+        Txlemetry::Logging.logger.error("Failed to report error via subscriber: #{e.message}")
+        Txlemetry::Logging.logger.error("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/facade.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/version'
+
+module Txlemetry
+  module Rails
+    # Install the Rails singleton-style Txlemetry facade at load time so Rails app
+    # initializers can call Txlemetry.init before Railtie initializers run.
+    #
+    # @api private
+    # @return [void]
+    def self.install_txlemetry_facade!
+      return if @txlemetry_facade_installed
+
+      Txlemetry.class_eval do
+        class << self
+          attr_accessor :client
+
+          # Initialize the singleton Txlemetry client used by Rails delegators.
+          #
+          # @param options [Hash] Core {Txlemetry::Client} options.
+          # @yieldparam config [Txlemetry::Rails::InitConfig] Block-based core SDK configuration.
+          # @return [Txlemetry::Client]
+          def init(options = {})
+            # If block given, yield to configuration
+            if block_given?
+              config = Txlemetry::Rails::InitConfig.new(options)
+              yield config
+              options = config.to_client_options
+            end
+
+            # Let the Txlemetry Logs pipeline reuse the same api_key/host without
+            # the core client exposing public readers.
+            Txlemetry::Rails::Logs::Setup.remember_client_options(options) if defined?(Txlemetry::Rails::Logs::Setup)
+
+            # Create the Txlemetry client. If a client already exists, shut it down
+            # after replacement so repeated init calls do not leave background
+            # resources from the previous instance running.
+            previous_client = @client
+            @client = Txlemetry::Client.new(
+              options.merge(_lib: 'txlemetry-rails', _lib_version: Txlemetry::Rails::VERSION)
+            )
+            begin
+              previous_client&.shutdown
+            rescue StandardError => e
+              Txlemetry::Logging.logger.warn("Failed to shut down previous Txlemetry client: #{e.message}")
+            end
+            @client
+          end
+
+          # @return [Boolean] Whether {Txlemetry.init} has created a client.
+          def initialized?
+            !@client.nil?
+          end
+
+          # Fallback for any client methods not explicitly defined.
+          #
+          # @api private
+          def method_missing(method_name, ...)
+            ensure_initialized!
+
+            if client.respond_to?(method_name)
+              client.public_send(method_name, ...)
+            else
+              super
+            end
+          end
+
+          # @api private
+          def respond_to_missing?(method_name, include_private = false)
+            ensure_initialized!
+            client.respond_to?(method_name, include_private) || super
+          end
+
+          private
+
+          def ensure_initialized!
+            return if initialized?
+
+            @client = Txlemetry::Client.new(api_key: nil, silence_disabled_client_error: true)
+          end
+        end
+      end
+
+      %i[
+        capture
+        capture_exception
+        identify
+        alias
+        group_identify
+        is_feature_enabled
+        get_feature_flag
+        get_all_flags
+      ].each do |method_name|
+        Txlemetry.define_singleton_method(method_name) do |*args, **kwargs, &block|
+          ensure_initialized!
+          client.public_send(method_name, *args, **kwargs, &block)
+        end
+      end
+
+      @txlemetry_facade_installed = true
+    end
+  end
+end

data/lib/txlemetry/rails/logs/appender.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'time'
+require 'txlemetry/internal/context'
+require 'txlemetry/logging'
+require 'txlemetry/rails/logs/severity'
+
+module Txlemetry
+  module Rails
+    module Logs
+      # A `Logger`-compatible sink that forwards each log record to an
+      # OpenTelemetry logger as an OTLP log record.
+      #
+      # It is designed to be broadcast alongside the app's existing
+      # `Rails.logger` so that ordinary `Rails.logger.info(...)` calls flow to
+      # Txlemetry Logs in addition to the normal output. Each record is stamped
+      # with the request-scoped Txlemetry identity captured by
+      # {Txlemetry::Rails::RequestContext}.
+      #
+      # Thread-safety: intentionally lock-free apart from the optional rate
+      # limiter's counter. Emitting touches no shared mutable state
+      # (`@otel_logger` is assigned once, attributes are built per call, and
+      # `Internal::Context.current` is thread/fiber-local), and the OTel
+      # BatchLogRecordProcessor synchronizes its buffer internally — the same
+      # split as stdlib `Logger`, which locks in `LogDevice`, not
+      # `Logger#add`. A mutex around emit would serialize all app logging
+      # needlessly.
+      #
+      # @api private
+      class Appender < ::Logger
+        SELF_LOG_PREFIX = '[txlemetry-ruby]'
+        SELF_LOG_PROGNAME = 'Txlemetry'
+        # Maps Txlemetry event-property names (as stored in Internal::Context) to
+        # the OTel semantic-convention attribute names used on log records,
+        # matching the web SDK so one filter works across SDKs.
+        REQUEST_ATTRIBUTE_NAMES = {
+          '$current_url' => 'url.full',
+          '$request_method' => 'http.request.method',
+          '$request_path' => 'url.path'
+        }.freeze
+
+        # @param otel_logger [#on_emit] An OpenTelemetry logger.
+        # @param level [Integer, nil] Minimum severity to forward.
+        # @param rate_limiter [Txlemetry::Rails::Logs::RateLimiter, nil] Optional cap on
+        #   forwarded records, protecting the ingestion quota from runaway log volume.
+        # @param before_send [#call, nil] Optional callback invoked with each record hash
+        #   (:timestamp, :severity, :body, :attributes — where :severity is a symbol such
+        #   as :warn) before it is emitted. Return a (possibly modified) hash to send, or
+        #   nil to drop — useful for scrubbing PII. If the callback raises, the record is
+        #   dropped.
+        def initialize(otel_logger, level: nil, rate_limiter: nil, before_send: nil)
+          super(nil)
+          @otel_logger = otel_logger
+          @rate_limiter = rate_limiter
+          @before_send = before_send
+          # The forwarding threshold deliberately does NOT live in Logger#level.
+          # Rails 7.1+ BroadcastLogger computes #level as the min and #debug?
+          # etc. as the any? across sinks, so storing it there would widen the
+          # app-wide predicates (logs_level = :debug would flip
+          # Rails.logger.debug? true and make e.g. ActiveRecord start
+          # generating SQL debug lines), and a broadcast-wide
+          # `Rails.logger.level =` would clobber the configured logs_level.
+          # Pinning the inherited level to UNKNOWN keeps this sink invisible
+          # to those calculations; filtering happens against @threshold in #add.
+          @threshold = level || ::Logger::DEBUG
+          self.level = ::Logger::UNKNOWN
+        end
+
+        # Re-entrancy guard key. Fiber-local (Thread.current[]), which is what
+        # recursion needs: if anything inside #add logs through a broadcast
+        # that includes this appender (e.g. a logs_before_send callback calling
+        # Rails.logger), the nested call would recurse until SystemStackError —
+        # which, as an Exception, escapes the rescue below and breaks the app.
+        REENTRANCY_KEY = :txlemetry_rails_logs_emitting
+
+        # Mirrors `Logger#add` message/progname resolution, then emits to OTel
+        # instead of writing to a log device.
+        #
+        # @return [Boolean] Always true so it composes with broadcast loggers.
+        def add(severity, message = nil, progname = nil)
+          return true if Thread.current[REENTRANCY_KEY]
+
+          begin
+            Thread.current[REENTRANCY_KEY] = true
+
+            severity ||= ::Logger::UNKNOWN
+            return true if severity < @threshold
+
+            if message.nil?
+              if block_given?
+                message = yield
+              else
+                message = progname
+                progname = nil
+              end
+            end
+
+            return true if message.nil?
+            return true if self_log?(message, progname)
+
+            record = apply_before_send(build_record(severity, message, progname))
+            return true if record.nil?
+
+            case @rate_limiter&.record
+            when :reject
+              return true
+            when :reject_first
+              emit_rate_cap_notice
+              return true
+            end
+
+            emit(record)
+            true
+          rescue StandardError => e
+            # Never let log forwarding break the calling code path, but leave
+            # one breadcrumb: a persistent emit failure would otherwise drop
+            # 100% of records with no signal anywhere.
+            warn_emit_error(e)
+            true
+          ensure
+            Thread.current[REENTRANCY_KEY] = nil
+          end
+        end
+
+        private
+
+        def build_record(severity, message, progname)
+          {
+            timestamp: Time.now,
+            severity: Severity.name_for(severity),
+            body: body_for(message),
+            attributes: attributes_for(progname)
+          }
+        end
+
+        def emit(record)
+          # The before_send callback sees a single :severity enum; the OTel
+          # number/text pair is derived here so the two can never be set
+          # inconsistently.
+          severity_number, severity_text = Severity.for_name(record[:severity])
+          @otel_logger.on_emit(
+            timestamp: record[:timestamp],
+            severity_number: severity_number,
+            severity_text: severity_text,
+            body: record[:body],
+            attributes: record[:attributes]
+          )
+        end
+
+        # One discoverable notice per window so truncation isn't silent. Emitted
+        # directly (bypassing before_send) so a scrubber can't accidentally
+        # suppress the only signal that records are being dropped.
+        def emit_rate_cap_notice
+          emit(
+            timestamp: Time.now,
+            severity: :warn,
+            body: "Txlemetry Logs rate cap reached (#{@rate_limiter.limit} records/minute); " \
+                  'dropping further records for the remainder of this window',
+            attributes: {}
+          )
+        end
+
+        # Runs before the rate-cap check (matching the other Txlemetry SDKs) so
+        # records dropped by the callback never consume window budget — a
+        # before_send that drops noisy logs must not starve the legitimate
+        # records behind them.
+        #
+        # A failing callback drops the record: the likeliest use is PII
+        # scrubbing, where shipping the unscrubbed original is worse than losing
+        # the line.
+        def apply_before_send(record)
+          return record unless @before_send
+
+          result = @before_send.call(record)
+          return result if result.is_a?(Hash)
+
+          # nil is an intentional drop and stays silent; any other type is
+          # likely a bug (e.g. a proc whose last expression isn't the record).
+          warn_before_send("returned #{result.class} instead of a Hash or nil") unless result.nil?
+          nil
+        rescue StandardError => e
+          warn_before_send("raised (#{e.class}: #{e.message})")
+          nil
+        end
+
+        def warn_before_send(description)
+          # Benign race: concurrent first failures may warn more than once.
+          return if @before_send_warned
+
+          @before_send_warned = true
+          Txlemetry::Logging.logger.warn("logs_before_send #{description}; dropping the record")
+        end
+
+        def warn_emit_error(error)
+          # Benign race: concurrent first failures may warn more than once.
+          return if @emit_error_warned
+
+          @emit_error_warned = true
+          Txlemetry::Logging.logger.warn(
+            "Txlemetry Logs failed to emit a record (#{error.class}: #{error.message}); " \
+            'further failures will be dropped silently'
+          )
+        end
+
+        def body_for(message)
+          str = stringify(message)
+          str = str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless str.encoding == Encoding::UTF_8
+          str.valid_encoding? ? str : str.scrub
+        end
+
+        # Mirrors stdlib Logger::Formatter#msg2str so the body matches what the
+        # file logger writes — most importantly, an Exception renders with its
+        # class, message, and backtrace instead of a backtrace-less #inspect.
+        # Array() guards a never-raised exception whose backtrace is nil. The
+        # returned String is always freshly built (dup/interpolation/inspect)
+        # so a logs_before_send callback can mutate it without touching frozen
+        # app strings.
+        def stringify(message)
+          case message
+          when String
+            message.dup
+          when Exception
+            "#{message.message} (#{message.class})\n#{Array(message.backtrace).join("\n")}"
+          else
+            message.inspect
+          end
+        end
+
+        def attributes_for(progname)
+          attributes = {}
+          # Ruby's progname is the closest analog to the OTel-world "logger name";
+          # logger.name is the key users coming from other ecosystems will expect.
+          attributes['logger.name'] = progname.to_s if progname
+
+          context = Internal::Context.current
+          return attributes unless context
+
+          attributes['posthogDistinctId'] = context.distinct_id if context.distinct_id
+          attributes['sessionId'] = context.session_id if context.session_id
+
+          properties = context.properties || {}
+          REQUEST_ATTRIBUTE_NAMES.each do |key, attribute_name|
+            value = properties[key] || properties[key.to_sym]
+            attributes[attribute_name] = value if value
+          end
+
+          attributes
+        end
+
+        def self_log?(message, progname)
+          return true if progname.to_s == SELF_LOG_PROGNAME
+
+          # PrefixedLogger always places the prefix at the start of the message,
+          # so start_with? suffices and avoids suppressing app logs that merely
+          # mention the SDK mid-string.
+          message.is_a?(String) && message.start_with?(SELF_LOG_PREFIX)
+        end
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/logs/rate_limiter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module Rails
+    module Logs
+      # Fixed-window rate limiter protecting the Txlemetry Logs ingestion quota
+      # from runaway log volume (Txlemetry Logs bills by data ingested).
+      #
+      # Thread-safe: the counter is the one piece of shared mutable state in
+      # the logs pipeline, guarded by a mutex scoped to a counter bump.
+      #
+      # @api private
+      class RateLimiter
+        WINDOW_SECONDS = 60
+
+        # @return [Integer] Maximum records allowed per window.
+        attr_reader :limit
+
+        # @param limit [Integer] Maximum records allowed per {WINDOW_SECONDS} window.
+        def initialize(limit)
+          @limit = limit
+          @mutex = Mutex.new
+          @window = nil
+          @count = 0
+        end
+
+        # Records one attempt and returns the verdict.
+        #
+        # @return [Symbol] :allow when under the cap, :reject_first for the
+        #   first rejection of a window (callers may emit a single notice),
+        #   :reject thereafter.
+        def record
+          @mutex.synchronize do
+            window = Process.clock_gettime(Process::CLOCK_MONOTONIC).to_i / WINDOW_SECONDS
+            if window != @window
+              @window = window
+              @count = 0
+            end
+            @count += 1
+            next :allow if @count <= @limit
+
+            @count == @limit + 1 ? :reject_first : :reject
+          end
+        end
+      end
+    end
+  end
+end