langfuse-rb 0.10.1 → 0.12.0

data/lib/langfuse/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "uri"
 
 module Langfuse
   # Configuration object for Langfuse client
@@ -33,7 +34,7 @@ module Langfuse
     attr_accessor :timeout
 
     # @return [Logger] Logger instance for debugging
-    attr_accessor :logger
+    attr_reader :logger
 
     # @return [Integer] Cache TTL in seconds
     attr_accessor :cache_ttl
@@ -63,16 +64,22 @@ module Langfuse
     # @return [Boolean] Use OpenTelemetry batch scheduling for trace export
     attr_accessor :tracing_async
 
+    # @return [Boolean] Enable Langfuse tracing and scoring
+    attr_accessor :tracing_enabled
+
     # @return [Integer] Number of events to batch before sending
     attr_accessor :batch_size
 
     # @return [Integer] Interval in seconds to flush buffered events
     attr_accessor :flush_interval
 
+    # @return [Integer] Maximum number of asynchronous scores held in memory
+    attr_accessor :score_queue_capacity
+
     # @return [Symbol] Reserved no-op queue name for future async job integration
     attr_accessor :job_queue
 
-    # @return [String, nil] Default tracing environment applied to new traces/observations
+    # @return [String, nil] Default environment applied to traces, observations, and scores
     attr_accessor :environment
 
     # @return [String, nil] Default release identifier applied to new traces/observations
@@ -81,13 +88,40 @@ module Langfuse
     # @return [Float] Trace sampling rate from 0.0 to 1.0
     attr_reader :sample_rate
 
-    # @return [#call, nil] Callback that decides whether an ended span should export to Langfuse.
+    # @return [#call, nil] Callback that decides whether a span should export to Langfuse.
+    #   The span processor calls it once after each span finishes.
     attr_accessor :should_export_span
 
     # @return [#call, nil] Mask callable applied to input, output, and metadata before serialization.
     #   Receives `data:` keyword argument. nil disables masking.
+    #   This is a creation-time hook for Langfuse-owned attributes; it never sees
+    #   raw third-party span attributes. See {#mask_otel_spans} for those.
     attr_accessor :mask
 
+    # @return [#call, nil] Export-stage masking hook for spans exported to Langfuse.
+    #   Receives a +params:+ keyword argument containing {MaskOtelSpansParams}.
+    #   Its frozen +spans+ Hash maps {OtelSpanIdentifier} keys to {OtelSpanData}
+    #   snapshots for one export batch, including third-party spans. Returns nil
+    #   to export the batch unchanged or {MaskOtelSpansResult} with sparse
+    #   {OtelSpanPatch} values. Deletes run before sets.
+    #   Only the copy exported to Langfuse is transformed — any other
+    #   OpenTelemetry exporter receives the original, unmasked spans, so
+    #   Langfuse masking does not protect other telemetry backends.
+    #   The hook is synchronous and must not rely on request context, the
+    #   current span, async work, or network calls. Exceptions and invalid
+    #   results fail closed by dropping the Langfuse export batch.
+    attr_accessor :mask_otel_spans
+
+    # @return [#add_to_counter, #record_value, #observe_value, nil] Reporter for
+    #   OpenTelemetry batch span processor metrics. The reporter must be fast,
+    #   thread-safe, and nonblocking. The application owns its lifecycle.
+    attr_accessor :metrics_reporter
+
+    # @return [#export, #force_flush, #shutdown, nil] Span exporter used by
+    #   Langfuse's internal tracer provider. The provider owns the exporter
+    #   lifecycle after tracing starts. nil selects the default OTLP exporter.
+    attr_accessor :span_exporter
+
     # @return [String] Default Langfuse API base URL
     DEFAULT_BASE_URL = "https://cloud.langfuse.com"
 
@@ -115,18 +149,35 @@ module Langfuse
     # @return [Boolean] Default async processing setting
     DEFAULT_TRACING_ASYNC = true
 
+    # @return [Boolean] Default telemetry setting
+    DEFAULT_TRACING_ENABLED = true
+
     # @return [Integer] Default number of events to batch before sending
     DEFAULT_BATCH_SIZE = 50
 
     # @return [Integer] Default flush interval in seconds
     DEFAULT_FLUSH_INTERVAL = 10
 
+    # @return [Integer] Default maximum number of queued asynchronous scores
+    DEFAULT_SCORE_QUEUE_CAPACITY = 100_000
+
     # @return [Symbol] Default ActiveJob queue name
     DEFAULT_JOB_QUEUE = :default
 
     # @return [Float] Default trace sampling rate (sample all traces)
     DEFAULT_SAMPLE_RATE = 1.0
 
+    # @return [Array<Symbol>] Methods required from a custom logger
+    LOGGER_METHODS = %i[debug info warn error].freeze
+
+    # Methods defined by OpenTelemetry's metrics reporter contract.
+    METRICS_REPORTER_METHODS = %i[add_to_counter record_value observe_value].freeze
+    private_constant :METRICS_REPORTER_METHODS
+
+    # Methods required by OpenTelemetry's span exporter contract.
+    SPAN_EXPORTER_METHODS = %i[export force_flush shutdown].freeze
+    private_constant :SPAN_EXPORTER_METHODS
+
     # @return [Integer] Number of seconds representing indefinite cache duration (~1000 years)
     INDEFINITE_SECONDS = 1000 * 365 * 24 * 60 * 60
 
@@ -153,52 +204,88 @@ module Langfuse
       @public_key = ENV.fetch("LANGFUSE_PUBLIC_KEY", nil)
       @secret_key = ENV.fetch("LANGFUSE_SECRET_KEY", nil)
       @base_url = ENV.fetch("LANGFUSE_BASE_URL", DEFAULT_BASE_URL)
-      @timeout = DEFAULT_TIMEOUT
-      @cache_ttl = DEFAULT_CACHE_TTL
-      @cache_max_size = DEFAULT_CACHE_MAX_SIZE
-      @cache_backend = DEFAULT_CACHE_BACKEND
-      @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
-      @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
-      @cache_stale_ttl = 0 # Default to 0 (SWR disabled, entries expire immediately after TTL)
-      @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
-      @prompt_cache_observer = nil
-      @tracing_async = DEFAULT_TRACING_ASYNC
-      @batch_size = DEFAULT_BATCH_SIZE
-      @flush_interval = DEFAULT_FLUSH_INTERVAL
-      @job_queue = DEFAULT_JOB_QUEUE
+      initialize_client_defaults
       initialize_tracing_defaults
-      @logger = default_logger
+      initialize_logger
 
       yield(self) if block_given?
     end
 
+    # Set the logger. A nil value disables output while preserving the logger contract.
+    #
+    # @param value [Logger, nil] Logger instance, or nil to disable logging
+    # @return [Logger] The normalized logger
+    def logger=(value)
+      @logger = value || Logger.new(IO::NULL)
+    end
+
     # Validate the configuration
     #
     # @raise [ConfigurationError] if configuration is invalid
     # @return [void]
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def validate!
-      raise ConfigurationError, "public_key is required" if public_key.nil? || public_key.empty?
-      raise ConfigurationError, "secret_key is required" if secret_key.nil? || secret_key.empty?
-      raise ConfigurationError, "base_url cannot be empty" if base_url.nil? || base_url.empty?
-      raise ConfigurationError, "timeout must be positive" if timeout.nil? || timeout <= 0
-      raise ConfigurationError, "cache_ttl must be non-negative" if cache_ttl.nil? || cache_ttl.negative?
-      raise ConfigurationError, "cache_max_size must be positive" if cache_max_size.nil? || cache_max_size <= 0
-
-      if cache_lock_timeout.nil? || cache_lock_timeout <= 0
-        raise ConfigurationError,
-              "cache_lock_timeout must be positive"
-      end
+      validate_tracing_enabled!
+      validate_connection_settings!
+      validate_batching_settings!
+      validate_sample_rate!
+      validate_client_settings!
+      validate_callable!(prompt_cache_observer, "prompt_cache_observer")
+      validate_logger!
+    end
 
-      validate_swr_config!
+    # Check whether the configuration can construct a client.
+    #
+    # This check is local. It does not validate credentials or network access.
+    #
+    # @return [Boolean] true when {#validate!} succeeds
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
 
-      validate_cache_backend!
-      validate_prompt_cache_observer!
+    # Validate only settings consumed by tracing setup and export.
+    #
+    # @api private
+    # @raise [ConfigurationError] if tracing configuration is invalid
+    # @return [void]
+    def validate_tracing!
+      validate_tracing_enabled!
+      validate_connection_settings!
+      validate_batching_settings!
       validate_sample_rate!
-      validate_should_export_span!
-      validate_mask!
+      validate_callable!(should_export_span, "should_export_span")
+      validate_callable!(mask, "mask")
+      validate_callable!(mask_otel_spans, "mask_otel_spans")
+      validate_metrics_reporter!
+      validate_span_exporter!
+      validate_logger!
+    end
+
+    # Validate settings needed while telemetry is disabled.
+    #
+    # @api private
+    # @raise [ConfigurationError] if disabled-client configuration is invalid
+    # @return [void]
+    def validate_telemetry_disabled!
+      validate_tracing_enabled!
+      validate_logger!
+    end
+
+    # Check whether Langfuse tracing and scoring are enabled.
+    #
+    # @return [Boolean] true when Langfuse telemetry is enabled
+    def telemetry_enabled?
+      tracing_enabled == true
+    end
+
+    # Check whether OpenTelemetry trace export is enabled.
+    #
+    # @return [Boolean] true when Langfuse tracing is enabled and the OpenTelemetry SDK is active
+    def trace_export_enabled?
+      telemetry_enabled? && !@otel_sdk_disabled
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Normalize stale_ttl value
     #
@@ -228,34 +315,182 @@ module Langfuse
 
     private
 
+    def initialize_client_defaults
+      @timeout = env_integer("LANGFUSE_TIMEOUT") || DEFAULT_TIMEOUT
+      @cache_ttl = DEFAULT_CACHE_TTL
+      @cache_max_size = DEFAULT_CACHE_MAX_SIZE
+      @cache_backend = DEFAULT_CACHE_BACKEND
+      @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
+      @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
+      @cache_stale_ttl = 0 # Default to 0 (SWR disabled, entries expire immediately after TTL)
+      @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
+      @prompt_cache_observer = nil
+      @tracing_async = DEFAULT_TRACING_ASYNC
+      @batch_size = env_integer("LANGFUSE_FLUSH_AT") || DEFAULT_BATCH_SIZE
+      @flush_interval = env_float("LANGFUSE_FLUSH_INTERVAL") || DEFAULT_FLUSH_INTERVAL
+      @score_queue_capacity = DEFAULT_SCORE_QUEUE_CAPACITY
+      @job_queue = DEFAULT_JOB_QUEUE
+    end
+
+    def initialize_logger
+      self.logger = if env_true?("LANGFUSE_DEBUG")
+                      Logger.new($stdout, level: Logger::DEBUG)
+                    else
+                      default_logger
+                    end
+    end
+
     def default_logger
-      if defined?(Rails) && Rails.respond_to?(:logger)
-        Rails.logger
-      else
-        Logger.new($stdout, level: Logger::WARN)
-      end
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Logger.new($stdout, level: Logger::WARN)
     end
 
     def initialize_tracing_defaults
+      @tracing_enabled = boolean_env("LANGFUSE_TRACING_ENABLED", default: DEFAULT_TRACING_ENABLED)
+      @otel_sdk_disabled = otel_sdk_disabled?
       @environment = env_value("LANGFUSE_TRACING_ENVIRONMENT")
       @release = env_value("LANGFUSE_RELEASE") || detect_release_from_ci_env
       self.sample_rate = env_value("LANGFUSE_SAMPLE_RATE") || DEFAULT_SAMPLE_RATE
       @should_export_span = nil
       @mask = nil
+      @mask_otel_spans = nil
+      @metrics_reporter = nil
+      @span_exporter = nil
+    end
+
+    def validate_connection_settings!
+      validate_required_string!("public_key", public_key)
+      validate_required_string!("secret_key", secret_key)
+      validate_base_url!
+    end
+
+    def validate_tracing_enabled!
+      return if [true, false].include?(tracing_enabled)
+
+      raise ConfigurationError, "tracing_enabled must be true or false"
+    end
+
+    def boolean_env(key, default:)
+      value = env_value(key)
+      return default if value.nil?
+      return true if value.casecmp("true").zero?
+      return false if value.casecmp("false").zero?
+
+      raise ConfigurationError, "#{key} must be true or false"
+    end
+
+    def otel_sdk_disabled?
+      env_value("OTEL_SDK_DISABLED")&.casecmp?("true") || false
+    end
+
+    def validate_batching_settings!
+      unless batch_size.is_a?(Integer) && batch_size.positive?
+        raise ConfigurationError, "batch_size must be a positive Integer"
+      end
+
+      validate_positive_number!("flush_interval", flush_interval)
+    end
+
+    def validate_client_settings!
+      validate_positive_number!("timeout", timeout)
+      validate_non_negative_number!("cache_ttl", cache_ttl)
+      validate_positive_number!("cache_max_size", cache_max_size)
+      validate_positive_number!("cache_lock_timeout", cache_lock_timeout)
+      unless score_queue_capacity.is_a?(Integer) && score_queue_capacity.positive?
+        raise ConfigurationError, "score_queue_capacity must be a positive Integer"
+      end
+
+      validate_swr_config!
+      validate_cache_backend!
+    end
+
+    # Credentials reach the API as interpolated strings, so a value that only
+    # answers #to_str would authenticate with its #to_s output instead.
+    def validate_required_string!(name, value, empty_message: "#{name} is required")
+      raise ConfigurationError, empty_message if value.nil?
+
+      raise ConfigurationError, "#{name} must be a String" unless value.is_a?(String)
+
+      raise ConfigurationError, empty_message if value.empty?
+    end
+
+    def validate_base_url!
+      validate_required_string!("base_url", base_url, empty_message: "base_url cannot be empty")
+      uri = URI.parse(base_url)
+      return if %w[http https].include?(uri.scheme) && !uri.host.to_s.empty?
+
+      raise ConfigurationError, "base_url must be an absolute HTTP or HTTPS URL"
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "base_url must be an absolute HTTP or HTTPS URL"
+    end
+
+    def validate_positive_number!(name, value)
+      return if finite_ordered_number?(value) && value.positive?
+
+      raise ConfigurationError, "#{name} must be positive"
+    end
+
+    def validate_non_negative_number!(name, value)
+      return if finite_ordered_number?(value) && !value.negative?
+
+      raise ConfigurationError, "#{name} must be non-negative"
+    end
+
+    def finite_ordered_number?(value)
+      value.is_a?(Numeric) && value.respond_to?(:positive?) && value.finite?
     end
 
     def validate_cache_backend!
       valid_backends = %i[memory rails auto]
-      return if valid_backends.include?(cache_backend)
+      unless valid_backends.include?(cache_backend)
+        raise ConfigurationError,
+              "cache_backend must be one of #{valid_backends.inspect}, got #{cache_backend.inspect}"
+      end
+
+      return unless cache_backend == :rails && cache_ttl.positive?
+      return if RailsCacheAdapter.available?
 
       raise ConfigurationError,
-            "cache_backend must be one of #{valid_backends.inspect}, got #{cache_backend.inspect}"
+            "Rails.cache is not available. Rails cache backend requires Rails with a configured cache store."
     end
 
-    def validate_prompt_cache_observer!
-      return if prompt_cache_observer.nil? || prompt_cache_observer.respond_to?(:call)
+    def validate_callable!(value, name)
+      return if value.nil? || value.respond_to?(:call)
 
-      raise ConfigurationError, "prompt_cache_observer must respond to #call"
+      raise ConfigurationError, "#{name} must respond to #call"
+    end
+
+    def validate_logger!
+      missing_methods = LOGGER_METHODS.reject { |method_name| logger.respond_to?(method_name) }
+      return if missing_methods.empty?
+
+      required_methods = LOGGER_METHODS.map { |method_name| "##{method_name}" }.join(", ")
+      raise ConfigurationError, "logger must respond to #{required_methods}"
+    end
+
+    def validate_metrics_reporter!
+      return if metrics_reporter.nil?
+
+      missing_methods = METRICS_REPORTER_METHODS.reject do |method_name|
+        metrics_reporter.respond_to?(method_name)
+      end
+      return if missing_methods.empty?
+
+      required_methods = METRICS_REPORTER_METHODS.map { |method_name| "##{method_name}" }.join(", ")
+      raise ConfigurationError, "metrics_reporter must respond to #{required_methods}"
+    end
+
+    def validate_span_exporter!
+      return if span_exporter.nil?
+
+      missing_methods = SPAN_EXPORTER_METHODS.reject do |method_name|
+        span_exporter.respond_to?(method_name)
+      end
+      return if missing_methods.empty?
+
+      required_methods = SPAN_EXPORTER_METHODS.map { |method_name| "##{method_name}" }.join(", ")
+      raise ConfigurationError, "span_exporter must respond to #{required_methods}"
     end
 
     def validate_swr_config!
@@ -277,17 +512,15 @@ module Langfuse
               "cache_stale_ttl must be non-negative or :indefinite"
       end
 
-      # Validate numeric values are non-negative
-      return unless cache_stale_ttl.is_a?(Integer) && cache_stale_ttl.negative?
+      return if cache_stale_ttl == :indefinite
+      return if finite_ordered_number?(cache_stale_ttl) && !cache_stale_ttl.negative?
 
       raise ConfigurationError,
             "cache_stale_ttl must be non-negative or :indefinite"
     end
 
     def validate_refresh_threads!
-      return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
-
-      raise ConfigurationError, "cache_refresh_threads must be positive"
+      validate_positive_number!("cache_refresh_threads", cache_refresh_threads)
     end
 
     def validate_sample_rate!
@@ -296,18 +529,6 @@ module Langfuse
       raise ConfigurationError, "sample_rate must be between 0.0 and 1.0"
     end
 
-    def validate_mask!
-      return if mask.nil? || mask.respond_to?(:call)
-
-      raise ConfigurationError, "mask must respond to #call"
-    end
-
-    def validate_should_export_span!
-      return if should_export_span.nil? || should_export_span.respond_to?(:call)
-
-      raise ConfigurationError, "should_export_span must respond to #call"
-    end
-
     def detect_release_from_ci_env
       COMMON_RELEASE_ENV_KEYS.each do |key|
         value = env_value(key)
@@ -324,6 +545,28 @@ module Langfuse
       value
     end
 
+    def env_integer(key)
+      value = env_value(key)
+      return nil unless value
+
+      Integer(value, 10)
+    rescue ArgumentError, TypeError
+      raise ConfigurationError, "#{key} must be an integer"
+    end
+
+    def env_float(key)
+      value = env_value(key)
+      return nil unless value
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise ConfigurationError, "#{key} must be numeric"
+    end
+
+    def env_true?(key)
+      env_value(key)&.casecmp?("true") || false
+    end
+
     def coerce_sample_rate(value)
       numeric_value = if value.is_a?(Numeric)
                         value.to_f
@@ -336,7 +579,7 @@ module Langfuse
       return numeric_value if numeric_value.between?(0.0, 1.0)
 
       raise ConfigurationError, "sample_rate must be between 0.0 and 1.0"
-    rescue ArgumentError, TypeError
+    rescue ArgumentError, RangeError, TypeError
       raise ConfigurationError, "sample_rate must be numeric"
     end
   end

data/lib/langfuse/evaluation.rb

@@ -26,17 +26,21 @@ module Langfuse
     # @param name [String] Score name (required, must be non-empty)
     # @param value [Numeric, Boolean, String] Score value (type depends on data_type)
     # @param comment [String, nil] Optional comment describing the evaluation
-    # @param data_type [Symbol] One of :numeric, :boolean, or :categorical
+    # @param data_type [Symbol] One of :numeric, :boolean, or :categorical.
+    #   Experiment evaluations are metrics, so the general-score :text and
+    #   :correction types are rejected here; create those through
+    #   {Client#create_score} instead.
     # @param config_id [String, nil] Optional score config ID
     # @param metadata [Hash, nil] Optional metadata hash
     # @raise [ArgumentError] if name is nil or empty
-    # @raise [ArgumentError] if data_type is not a valid score data type
+    # @raise [ArgumentError] if data_type is not an experiment score data type
     def initialize(name:, value:, comment: nil, data_type: :numeric, config_id: nil, metadata: nil)
       raise ArgumentError, "name is required" if name.to_s.empty?
 
-      unless Types::SCORE_DATA_TYPES.key?(data_type)
+      unless Types::EXPERIMENT_SCORE_DATA_TYPES.include?(data_type)
         raise ArgumentError,
-              "Invalid data_type: #{data_type}. Valid types: #{Types::VALID_SCORE_DATA_TYPES.join(', ')}"
+              "Invalid data_type: #{data_type}. Experiment evaluations accept: " \
+              "#{Types::EXPERIMENT_SCORE_DATA_TYPES.join(', ')}"
       end
 
       validate_value!(value, data_type)

data/lib/langfuse/exit_hook.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "fork_safety"
+
+module Langfuse
+  # Flushes SDK telemetry during normal process exit.
+  #
+  # @api private
+  module ExitHook
+    class << self
+      # Install the process callback once and enable it.
+      #
+      # @return [void]
+      def install!
+        mutex.synchronize do
+          return if @installed
+
+          Kernel.at_exit { run }
+          @installed = true
+          @active = false
+        end
+      end
+
+      # Enable the installed callback for the current SDK lifecycle.
+      #
+      # @return [void]
+      def enable
+        mutex.synchronize { @active = true }
+      end
+
+      # Disable the callback after an explicit shutdown or reset.
+      #
+      # @return [void]
+      def disable
+        mutex.synchronize { @active = false }
+      end
+
+      # Run the callback once without allowing shutdown errors to escape.
+      #
+      # @return [void]
+      def run
+        return unless consume_active_hook
+
+        Langfuse.shutdown
+      rescue StandardError => e
+        warn_failure(e)
+      end
+
+      private
+
+      def consume_active_hook
+        mutex.synchronize do
+          active = @active
+          @active = false
+          active
+        end
+      end
+
+      def reset_after_fork
+        @mutex = Mutex.new
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def warn_failure(error)
+        Kernel.warn("Langfuse exit flush failed: #{error.class} - #{error.message}")
+      rescue StandardError
+        nil
+      end
+    end
+
+    install!
+    ForkSafety.register(self)
+  end
+end

data/lib/langfuse/fork_safety.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Restores SDK-owned background state in a forked child process.
+  #
+  # @api private
+  module ForkSafety
+    # Ruby routes Kernel#fork, Process.fork, and IO.popen("-") through
+    # Process._fork. Ruby 3.2 documents this override point for monitoring
+    # libraries that need before-fork or after-fork behavior.
+    module ProcessHook
+      def _fork
+        pid = super
+        Langfuse::ForkSafety.after_fork if pid.zero?
+        pid
+      end
+    end
+
+    class << self
+      # Register an SDK resource that implements a private #reset_after_fork method.
+      #
+      # @param resource [Object] Fork-sensitive SDK resource
+      # @return [void]
+      def register(resource)
+        install!
+        registry_mutex.synchronize { registry[resource] = true }
+      end
+
+      # Reset every live registered resource in the child process.
+      #
+      # @return [void]
+      def after_fork
+        reset_inherited_mutexes
+        registry.each_key { |resource| reset_resource(resource) }
+      rescue StandardError => e
+        Kernel.warn("Langfuse fork reset failed: #{e.class} - #{e.message}")
+      end
+
+      private
+
+      def install!
+        install_mutex.synchronize do
+          Process.singleton_class.prepend(ProcessHook) unless Process.singleton_class.ancestors.include?(ProcessHook)
+        end
+      end
+
+      def registry
+        @registry ||= ObjectSpace::WeakMap.new
+      end
+
+      def registry_mutex
+        @registry_mutex ||= Mutex.new
+      end
+
+      def install_mutex
+        @install_mutex ||= Mutex.new
+      end
+
+      def reset_inherited_mutexes
+        @registry_mutex = Mutex.new
+        @install_mutex = Mutex.new
+      end
+
+      def reset_resource(resource)
+        resource.__send__(:reset_after_fork)
+      rescue StandardError => e
+        Kernel.warn("Langfuse fork reset failed for #{resource.class}: #{e.class} - #{e.message}")
+      end
+    end
+  end
+end