txlemetry-rails 4.0.0

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

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'txlemetry/logging'
+require 'txlemetry/rails/configuration'
+require 'txlemetry/rails/logs/appender'
+require 'txlemetry/rails/logs/rate_limiter'
+
+module Txlemetry
+  module Rails
+    module Logs
+      # Bootstraps the OpenTelemetry logs pipeline that ships Txlemetry Logs.
+      #
+      # The OpenTelemetry gems are optional/soft dependencies. They are required
+      # lazily here so that apps which do not enable logs (or run on a Ruby
+      # version the logs SDK does not support) are unaffected.
+      #
+      # @api private
+      module Setup
+        # Bounds the at_exit flush. Without a timeout, the batch processor
+        # joins its worker thread unbounded and the exporter retries each
+        # batch with backoff — during an outage that can eat the whole
+        # SIGTERM grace period and starve the events client of its flush.
+        SHUTDOWN_TIMEOUT_SECONDS = 2
+
+        class << self
+          # @return [OpenTelemetry::SDK::Logs::LoggerProvider, nil]
+          attr_reader :provider
+
+          # @return [Txlemetry::Rails::Logs::Appender, nil]
+          attr_reader :appender
+
+          # Build the logs pipeline and return the broadcastable appender.
+          #
+          # Idempotent: subsequent calls return the previously built appender
+          # (or nil if setup was skipped).
+          #
+          # @return [Txlemetry::Rails::Logs::Appender, nil]
+          def install
+            return @appender if @installed
+
+            @installed = true
+
+            # Respect the core client's test_mode: when it is on, the client
+            # swaps in a NoopWorker so events never ship, and the logs pipeline
+            # should likewise stay off so test suites don't emit real records.
+            # Intentional state, so skip quietly (no warning).
+            return nil if @client_test_mode
+
+            return nil unless require_otel_gems
+
+            config = Txlemetry::Rails.config
+            token = resolve_token
+            if token.nil?
+              warn_once(
+                'Txlemetry Logs enabled but no project token could be resolved ' \
+                '(set config.api_key or TXLEMETRY_API_KEY); skipping.'
+              )
+              return nil
+            end
+
+            @provider = build_provider(token)
+            otel_logger = @provider.logger(name: 'txlemetry-rails', version: Txlemetry::Rails::VERSION)
+            level = resolve_level(config.logs_level) || rails_logger_level
+            @appender = Appender.new(
+              otel_logger,
+              level: level,
+              rate_limiter: build_rate_limiter(config),
+              before_send: config.logs_before_send
+            )
+          rescue StandardError => e
+            warn_once("Failed to initialize Txlemetry Logs: #{e.message}")
+            nil
+          end
+
+          # Shut the pipeline down, flushing buffered records.
+          #
+          # @param timeout [Numeric] Max seconds to spend; see {SHUTDOWN_TIMEOUT_SECONDS}.
+          # @return [void]
+          def shutdown(timeout: SHUTDOWN_TIMEOUT_SECONDS)
+            @provider&.shutdown(timeout: timeout)
+          rescue StandardError => e
+            logger.warn("Error shutting down Txlemetry Logs: #{e.message}")
+          end
+
+          # Remembers the api_key/host the Txlemetry client was initialized with
+          # (called by Txlemetry.init) so the logs pipeline can reuse them without
+          # the core client exposing public readers.
+          #
+          # @api private
+          # @param options [Hash] The options passed to {Txlemetry::Client.new}.
+          # @return [void]
+          def remember_client_options(options)
+            return unless options.is_a?(Hash)
+
+            @client_api_key = options[:api_key] || options['api_key']
+            @client_host = options[:host] || options['host']
+            @client_test_mode = options[:test_mode] || options['test_mode']
+          end
+
+          # Resets memoized state. Intended for tests.
+          #
+          # @return [void]
+          def reset
+            @installed = false
+            @provider = nil
+            @appender = nil
+            @warned = false
+            @client_api_key = nil
+            @client_host = nil
+            @client_test_mode = nil
+          end
+
+          private
+
+          # The logs token is the same project token the core client uses
+          # (i.e. config.api_key, captured by Txlemetry.init), falling back to
+          # ENV['TXLEMETRY_API_KEY'].
+          def resolve_token
+            normalize(@client_api_key) || normalize(ENV.fetch('TXLEMETRY_API_KEY', nil))
+          end
+
+          # The logs host follows the core client's configured host (captured by
+          # Txlemetry.init), falling back to ENV['TXLEMETRY_HOST'] and finally the
+          # US cloud endpoint.
+          def resolve_host
+            normalize(@client_host) ||
+              normalize(ENV.fetch('TXLEMETRY_HOST', nil)) ||
+              'https://app.txlemetry.com'
+          end
+
+          # nil, 0, and negative values intentionally disable the cap. Numeric
+          # strings (e.g. from ENV) are coerced — deliberately via Integer()
+          # rather than to_i, since "abc".to_i == 0 would silently disable the
+          # cap. Unparseable values warn and fall back to the default cap:
+          # a misconfiguration should not switch the protection off.
+          def build_rate_limiter(config)
+            raw = config.logs_max_records_per_minute
+            return nil if raw.nil?
+
+            limit = Integer(raw, exception: false)
+            if limit.nil?
+              logger.warn(
+                "logs_max_records_per_minute=#{raw.inspect} is not a number; using the default cap " \
+                "of #{Configuration::DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE} records/minute"
+              )
+              limit = Configuration::DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE
+            end
+            return nil unless limit.positive?
+
+            RateLimiter.new(limit)
+          end
+
+          def require_otel_gems
+            require 'opentelemetry-sdk'
+            require 'opentelemetry-logs-sdk'
+            require 'opentelemetry/exporter/otlp_logs'
+            true
+          rescue LoadError => e
+            warn_once(
+              "Txlemetry Logs enabled but the OpenTelemetry gems are missing (#{e.message}). " \
+              "Add 'opentelemetry-sdk', 'opentelemetry-logs-sdk', and " \
+              "'opentelemetry-exporter-otlp-logs' (each with require: false) to your Gemfile " \
+              'to enable log forwarding.'
+            )
+            false
+          end
+
+          def build_provider(token)
+            resource = OpenTelemetry::SDK::Resources::Resource.create(resource_attributes)
+            provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: resource)
+            exporter = OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+              endpoint: logs_endpoint(resolve_host),
+              headers: { 'Authorization' => "Bearer #{token}" }
+            )
+            processor = OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter)
+            provider.add_log_record_processor(processor)
+            provider
+          end
+
+          def resource_attributes
+            # service.version is intentionally omitted. Per OpenTelemetry semantic
+            # conventions it is the deployed application's version, not this gem's.
+            # The txlemetry-rails name/version travel with each record via the
+            # instrumentation scope (see LoggerProvider#logger above).
+            {
+              # Identifies these records as the Txlemetry Ruby SDK so Txlemetry's usage
+              # report can attribute log volume to Ruby (mirrors txlemetry-ios/android/
+              # flutter/react-native). Overrides the OpenTelemetry SDK default of
+              # 'opentelemetry'; the txlemetry-rails integration name stays on the scope.
+              'telemetry.sdk.name' => 'txlemetry-ruby',
+              'service.name' => service_name,
+              'deployment.environment' => ::Rails.env.to_s
+            }
+          end
+
+          def service_name
+            app = ::Rails.application
+            return 'unknown_service' unless app
+
+            name = app.class.respond_to?(:module_parent_name) ? app.class.module_parent_name : nil
+            name && !name.empty? ? name.to_s : 'unknown_service'
+          rescue StandardError
+            'unknown_service'
+          end
+
+          def logs_endpoint(host)
+            base = (host || 'https://app.txlemetry.com').to_s.sub(%r{/+\z}, '')
+            "#{base}/i/v1/logs"
+          end
+
+          def resolve_level(level)
+            return nil if level.nil?
+            return level if level.is_a?(Integer)
+
+            # const_get can return non-severity values without raising: Logger's
+            # own VERSION/SEV_LABEL, and (via the default inherited lookup) any
+            # top-level all-caps constant like ENV/ARGV/STDOUT. The Integer guard
+            # rejects them so they don't later blow up the severity comparison.
+            # (inherit must stay true — the severity constants live in the
+            # included Logger::Severity module.)
+            result = ::Logger.const_get(level.to_s.upcase)
+            raise NameError, 'not a severity integer' unless result.is_a?(Integer)
+
+            result
+          rescue NameError
+            warn_once(
+              "Invalid logs_level #{level.inspect}; expected one of :debug, :info, :warn, " \
+              ':error, :fatal, :unknown (or an Integer). Falling back to the Rails logger level.'
+            )
+            nil
+          end
+
+          def rails_logger_level
+            ::Rails.logger&.level
+          rescue StandardError
+            nil
+          end
+
+          def normalize(value)
+            return nil unless value.is_a?(String)
+
+            stripped = value.strip
+            stripped.empty? ? nil : stripped
+          end
+
+          def warn_once(message)
+            return if @warned
+
+            @warned = true
+            logger.warn(message)
+          end
+
+          def logger
+            Txlemetry::Logging.logger
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Txlemetry
+  module Rails
+    module Logs
+      # Maps Ruby `Logger` severities to OpenTelemetry log severity numbers and text.
+      #
+      # OpenTelemetry defines severity ranges (DEBUG=5-8, INFO=9-12, WARN=13-16,
+      # ERROR=17-20, FATAL=21-24); we map each Ruby level to the base of its range.
+      #
+      # @api private
+      module Severity
+        module_function
+
+        # @param severity [Integer, nil] A Ruby `Logger` severity constant.
+        # @return [Symbol] The severity name (:debug, :info, :warn, :error, :fatal).
+        def name_for(severity)
+          NAMES.fetch(severity, :info)
+        end
+
+        # @param name [Symbol, String, nil] A severity name such as :warn.
+        # @return [Array(Integer, String)] OpenTelemetry severity number and text;
+        #   unrecognized names fall back to INFO.
+        def for_name(name)
+          OTEL.fetch(name.to_s.downcase.to_sym, OTEL[:info])
+        end
+
+        NAMES = {
+          ::Logger::DEBUG => :debug,
+          ::Logger::INFO => :info,
+          ::Logger::WARN => :warn,
+          ::Logger::ERROR => :error,
+          ::Logger::FATAL => :fatal,
+          ::Logger::UNKNOWN => :info
+        }.freeze
+
+        OTEL = {
+          debug: [5, 'DEBUG'],
+          info: [9, 'INFO'],
+          warn: [13, 'WARN'],
+          error: [17, 'ERROR'],
+          fatal: [21, 'FATAL']
+        }.freeze
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/parameter_filter.rb

@@ -0,0 +1,136 @@
+# 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
+    # Shared utility module for filtering sensitive parameters
+    #
+    # This module provides consistent parameter filtering across all Txlemetry Rails
+    # components, leveraging Rails' built-in parameter filtering when available.
+    # It automatically detects the correct Rails parameter filtering API based on
+    # the Rails version.
+    #
+    # @api private
+    #
+    # @example Usage in a class
+    #   class MyClass
+    #     include Txlemetry::Rails::ParameterFilter
+    #
+    #     def my_method(params)
+    #       filtered = filter_sensitive_params(params)
+    #       Txlemetry.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
+        # @return [Class] Rails parameter filter backend.
+        def self.backend
+          ActiveSupport::ParameterFilter
+        end
+      else
+        # @return [Class] Rails parameter filter backend.
+        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