langfuse-rb 0.10.1 → 0.12.0

data/lib/langfuse/masking_exporter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require_relative "otel_span_batch"
+require_relative "otel_span_patch_applier"
+
+module Langfuse
+  # Export-stage masking wrapper around the Langfuse OTLP exporter.
+  #
+  # Only the copy exported to Langfuse is transformed. Original span data and
+  # any other OpenTelemetry exporter remain unchanged.
+  #
+  # @api private
+  class MaskingExporter
+    SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
+    private_constant :SUCCESS
+
+    # Distinguishes "the hook raised" from a hook that legitimately returned nil.
+    # A constant rather than a memoized ivar because BatchSpanProcessor#force_flush
+    # exports on the caller's thread while the background thread may also be exporting.
+    HOOK_FAILURE = Object.new.freeze
+    private_constant :HOOK_FAILURE
+
+    # @param delegate [#export, #force_flush, #shutdown] Langfuse OTLP exporter
+    # @param hook [#call] configured mask_otel_spans callable
+    # @param logger [Logger]
+    def initialize(delegate:, hook:, logger:)
+      @delegate = delegate
+      @hook = hook
+      @logger = logger
+      @patch_applier = OtelSpanPatchApplier.new(logger: logger)
+    end
+
+    # Mask the batch and delegate export.
+    #
+    # @param span_data [Enumerable<OpenTelemetry::SDK::Trace::SpanData>]
+    # @param timeout [Numeric, nil]
+    # @return [Integer] OpenTelemetry export result code
+    def export(span_data, timeout: nil)
+      masked_spans = mask_batch(span_data.to_a)
+      return SUCCESS if masked_spans.nil? || masked_spans.empty?
+
+      @delegate.export(masked_spans, timeout: timeout)
+    end
+
+    # @return [Object] delegate's force_flush result
+    def force_flush(timeout: nil)
+      @delegate.force_flush(timeout: timeout)
+    end
+
+    # @return [Object] delegate's shutdown result
+    def shutdown(timeout: nil)
+      @delegate.shutdown(timeout: timeout)
+    end
+
+    private
+
+    # Returns nil to drop the whole Langfuse batch, otherwise the spans to export.
+    def mask_batch(span_data)
+      batch = OtelSpanBatch.new(span_data: span_data, logger: @logger)
+      return [] if batch.empty?
+
+      # Build snapshots outside call_hook so a snapshot failure is never reported as a hook failure.
+      result = call_hook(batch.masking_params, batch)
+      return if result.equal?(HOOK_FAILURE)
+      return batch.spans if result.nil?
+      return unless valid_result?(result, batch)
+
+      batch.apply(result.span_patches, patch_applier: @patch_applier)
+    end
+
+    def call_hook(params, batch)
+      @hook.call(params: params)
+    rescue StandardError => e
+      # Hook exception messages can contain the sensitive values being masked.
+      @logger.error("Langfuse mask_otel_spans raised #{e.class}; #{dropping_batch(batch)}")
+      HOOK_FAILURE
+    end
+
+    def valid_result?(result, batch)
+      unless result.is_a?(MaskOtelSpansResult) && result.span_patches.is_a?(Hash)
+        @logger.error("Langfuse mask_otel_spans returned an invalid result; #{dropping_batch(batch)}")
+        return false
+      end
+
+      return true if result.span_patches.each_key.all? { |identifier| batch.include_identifier?(identifier) }
+
+      @logger.error(
+        "Langfuse mask_otel_spans returned a patch for an unknown span identifier; #{dropping_batch(batch)}"
+      )
+      false
+    end
+
+    def dropping_batch(batch)
+      "dropping the Langfuse export batch of #{batch.size} spans"
+    end
+  end
+end

data/lib/langfuse/observations.rb

@@ -201,7 +201,7 @@ module Langfuse
     # @param value [Numeric, String, Boolean] score value
     # @param comment [String, nil] optional comment
     # @param metadata [Hash, nil] optional metadata
-    # @param data_type [Symbol] one of :numeric, :boolean, :categorical
+    # @param data_type [Symbol] one of :numeric, :boolean, :categorical, :text, :correction
     # @return [Hash] created score data from the API
     def score_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
       Langfuse.create_score(
@@ -254,6 +254,7 @@ module Langfuse
     def run_in_context
       parent_ctx = OpenTelemetry::Context.current
       span_ctx = OpenTelemetry::Trace.context_with_span(@otel_span, parent_context: parent_ctx)
+      span_ctx = Propagation._set_langfuse_trace_id_in_baggage(trace_id, context: span_ctx)
       OpenTelemetry::Context.with_current(span_ctx) { yield self }
     ensure
       safe_end

data/lib/langfuse/otel_attributes.rb

@@ -53,6 +53,7 @@ module Langfuse
     OBSERVATION_PROMPT_NAME = "langfuse.observation.prompt.name"
     OBSERVATION_PROMPT_VERSION = "langfuse.observation.prompt.version"
     OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
+    IS_APP_ROOT = "langfuse.internal.is_app_root"
 
     # Common attributes
     VERSION = "langfuse.version"

data/lib/langfuse/otel_setup.rb

@@ -3,6 +3,8 @@
 require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
 require "base64"
+require_relative "masking_exporter"
+require_relative "trace_export_guard"
 
 module Langfuse
   # OpenTelemetry initialization and setup for Langfuse tracing.
@@ -16,6 +18,9 @@ module Langfuse
       release
       sample_rate
       should_export_span
+      mask_otel_spans
+      metrics_reporter
+      span_exporter
       tracing_async
       batch_size
       flush_interval
@@ -31,20 +36,10 @@ module Langfuse
       # @param config [Langfuse::Config] The Langfuse configuration
       # @return [OpenTelemetry::SDK::Trace::TracerProvider]
       def setup(config)
-        validate_tracing_config!(config)
-        return existing_provider_for(config) if initialized?
+        config.validate_tracing!
+        provider, created = setup_mutex.synchronize { setup_locked(config) }
 
-        candidate_provider = nil
-        provider = nil
-        created = false
-        candidate_provider = build_tracer_provider(config)
-        provider, created = publish_provider(candidate_provider, tracing_config_snapshot(config))
-        unless created
-          candidate_provider.shutdown(timeout: 30)
-          return existing_provider_for(config)
-        end
-
-        log_initialized(config)
+        log_initialized(config) if created
         provider
       rescue StandardError
         rollback_provider(provider) if created
@@ -95,23 +90,13 @@ module Langfuse
         @tracer_provider
       end
 
-      def publish_provider(provider, snapshot)
-        created = false
-        current = nil
-
-        # This mutex only guards publication so setup never exposes a half-built provider.
-        setup_mutex.synchronize do
-          if @tracer_provider
-            current = @tracer_provider
-          else
-            @tracer_provider = provider
-            @config_snapshot = snapshot
-            current = provider
-            created = true
-          end
-        end
+      def setup_locked(config)
+        return [existing_provider_for(config), false] if @tracer_provider
 
-        [current, created]
+        provider = build_tracer_provider(config)
+        @tracer_provider = provider
+        @config_snapshot = tracing_config_snapshot(config)
+        [provider, true]
       end
 
       def rollback_provider(provider)
@@ -131,12 +116,22 @@ module Langfuse
           sampler: build_sampler(config.sample_rate)
         )
         provider.add_span_processor(
-          SpanProcessor.new(config: config, exporter: build_exporter(config))
+          SpanProcessor.new(
+            config: config,
+            exporter: TraceExportGuard.new(delegate: build_exporter(config), config: config)
+          )
         )
         provider
       end
 
       def build_exporter(config)
+        exporter = config.span_exporter || build_otlp_exporter(config)
+        return exporter unless config.mask_otel_spans
+
+        MaskingExporter.new(delegate: exporter, hook: config.mask_otel_spans, logger: config.logger)
+      end
+
+      def build_otlp_exporter(config)
         OpenTelemetry::Exporter::OTLP::Exporter.new(
           endpoint: "#{config.base_url}/api/public/otel/v1/traces",
           headers: build_headers(config.public_key, config.secret_key),
@@ -149,15 +144,6 @@ module Langfuse
         config.logger.info("Langfuse tracing initialized with OpenTelemetry (#{mode} mode)")
       end
 
-      def validate_tracing_config!(config)
-        raise ConfigurationError, "public_key is required" if blank?(config.public_key)
-        raise ConfigurationError, "secret_key is required" if blank?(config.secret_key)
-        raise ConfigurationError, "base_url cannot be empty" if blank?(config.base_url)
-        return if config.should_export_span.nil? || config.should_export_span.respond_to?(:call)
-
-        raise ConfigurationError, "should_export_span must respond to #call"
-      end
-
       def tracing_config_snapshot(config)
         TRACING_CONFIG_FIELDS.to_h { |field| [field, config.public_send(field)] }.freeze
       end
@@ -166,14 +152,16 @@ module Langfuse
         @setup_mutex ||= Mutex.new
       end
 
-      def blank?(value)
-        value.nil? || value.empty?
-      end
-
       def build_headers(public_key, secret_key)
         credentials = "#{public_key}:#{secret_key}"
         encoded = Base64.strict_encode64(credentials)
-        { "Authorization" => "Basic #{encoded}" }
+        {
+          "Authorization" => "Basic #{encoded}",
+          "x-langfuse-ingestion-version" => "4",
+          "x-langfuse-sdk-name" => "ruby",
+          "x-langfuse-sdk-version" => Langfuse::VERSION,
+          "x-langfuse-public-key" => public_key
+        }
       end
 
       def build_sampler(sample_rate)

data/lib/langfuse/otel_span_batch.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require_relative "otel_span_masking"
+
+module Langfuse
+  # Builds immutable hook input while retaining original spans for export.
+  # @api private
+  class OtelSpanBatch
+    attr_reader :spans
+
+    def initialize(span_data:, logger:)
+      @logger = logger
+      @spans_by_identifier = index_spans(span_data)
+      @spans = @spans_by_identifier.values.freeze
+    end
+
+    def empty?
+      @spans_by_identifier.empty?
+    end
+
+    def size
+      @spans_by_identifier.size
+    end
+
+    def include_identifier?(identifier)
+      @spans_by_identifier.key?(identifier)
+    end
+
+    def masking_params
+      MaskOtelSpansParams.new(spans: snapshots)
+    end
+
+    def apply(patches, patch_applier:)
+      @spans_by_identifier.filter_map do |identifier, span|
+        patch = patches[identifier]
+        patch.nil? ? span : patch_applier.apply(span, patch)
+      end
+    end
+
+    private
+
+    def index_spans(span_data)
+      span_data.each_with_object({}) do |span, indexed_spans|
+        unless valid_span_context?(span)
+          # No usable IDs here, so the span name is the only way to identify the drop.
+          @logger.warn("Langfuse mask_otel_spans dropped a span with an invalid span context (name=#{span.name})")
+          next
+        end
+
+        identifier = span_identifier(span)
+        # Delete before re-inserting so a duplicated identifier takes the position of
+        # its last occurrence rather than its first, matching the Python SDK.
+        indexed_spans.delete(identifier)
+        indexed_spans[identifier] = span
+      end
+    end
+
+    def valid_span_context?(span)
+      span.trace_id.is_a?(String) && span.trace_id.bytesize == 16 &&
+        span.span_id.is_a?(String) && span.span_id.bytesize == 8 &&
+        span.trace_id != OpenTelemetry::Trace::INVALID_TRACE_ID &&
+        span.span_id != OpenTelemetry::Trace::INVALID_SPAN_ID
+    end
+
+    def span_identifier(span)
+      OtelSpanIdentifier.new(trace_id: span.hex_trace_id, span_id: span.hex_span_id)
+    end
+
+    def snapshots
+      @snapshots ||= @spans_by_identifier.to_h do |identifier, span|
+        [identifier, snapshot_span(identifier, span)]
+      end.freeze
+    end
+
+    def snapshot_span(identifier, span)
+      scope = span.instrumentation_scope
+      OtelSpanData.new(
+        trace_id: identifier.trace_id,
+        span_id: identifier.span_id,
+        parent_span_id: parent_span_id(span),
+        name: frozen_copy(span.name),
+        instrumentation_scope_name: frozen_copy(scope&.name),
+        instrumentation_scope_version: frozen_copy(scope&.version),
+        attributes: frozen_attributes(span.attributes),
+        resource_attributes: frozen_attributes(span.resource&.attribute_enumerator&.to_h)
+      )
+    end
+
+    def parent_span_id(span)
+      return if span.parent_span_id.nil? || span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID
+
+      span.hex_parent_span_id.freeze
+    end
+
+    def frozen_attributes(attributes)
+      (attributes || {}).to_h do |key, value|
+        [frozen_copy(key), frozen_copy(value)]
+      end.freeze
+    end
+
+    # Attribute payloads can be large serialized prompts, so skip copying anything
+    # already immutable rather than duplicating it on every export.
+    def frozen_copy(value)
+      case value
+      when String then value.frozen? ? value : value.dup.freeze
+      when Array then value.map { |element| frozen_copy(element) }.freeze
+      else value
+      end
+    end
+  end
+  private_constant :OtelSpanBatch
+end

data/lib/langfuse/otel_span_masking.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Stable key for one OpenTelemetry span in a masking batch.
+  #
+  # Reuse identifiers from {MaskOtelSpansParams#spans} when returning patches.
+  #
+  # @!attribute [r] trace_id
+  #   @return [String] 32-character lowercase hexadecimal trace ID
+  # @!attribute [r] span_id
+  #   @return [String] 16-character lowercase hexadecimal span ID
+  OtelSpanIdentifier = Data.define(:trace_id, :span_id) do
+    # @param trace_id [String] 32-character lowercase hexadecimal trace ID
+    # @param span_id [String] 16-character lowercase hexadecimal span ID
+    # @return [OtelSpanIdentifier]
+    # @raise [ArgumentError] if an unknown keyword is given
+    def initialize(trace_id:, span_id:)
+      super(trace_id: trace_id.dup.freeze, span_id: span_id.dup.freeze)
+    end
+  end
+
+  # Read-only OpenTelemetry span snapshot passed to +mask_otel_spans+.
+  #
+  # The hook can inspect every field but can only patch +attributes+.
+  #
+  # @!attribute [r] trace_id
+  #   @return [String] 32-character lowercase hexadecimal trace ID
+  # @!attribute [r] span_id
+  #   @return [String] 16-character lowercase hexadecimal span ID
+  # @!attribute [r] parent_span_id
+  #   @return [String, nil] 16-character lowercase hexadecimal parent span ID
+  # @!attribute [r] name
+  #   @return [String] span name
+  # @!attribute [r] instrumentation_scope_name
+  #   @return [String, nil] instrumentation scope name
+  # @!attribute [r] instrumentation_scope_version
+  #   @return [String, nil] instrumentation scope version
+  # @!attribute [r] attributes
+  #   @return [Hash] frozen span attributes
+  # @!attribute [r] resource_attributes
+  #   @return [Hash] frozen resource attributes
+  OtelSpanData = Data.define(
+    :trace_id,
+    :span_id,
+    :parent_span_id,
+    :name,
+    :instrumentation_scope_name,
+    :instrumentation_scope_version,
+    :attributes,
+    :resource_attributes
+  )
+
+  # Input passed to the export-stage masking hook.
+  #
+  # @!attribute [r] spans
+  #   @return [Hash{OtelSpanIdentifier => OtelSpanData}] frozen batch snapshot
+  MaskOtelSpansParams = Data.define(:spans)
+
+  # Attribute changes for one exported OpenTelemetry span.
+  #
+  # Deletes run before sets, so a set wins when the same key is in both fields.
+  #
+  # @!attribute [r] set_attributes
+  #   @return [Hash] attributes to add or replace
+  # @!attribute [r] delete_attributes
+  #   @return [Array<String>] attribute keys to remove
+  OtelSpanPatch = Data.define(:set_attributes, :delete_attributes) do
+    # @param set_attributes [Object] attributes to add or replace
+    # @param delete_attributes [Object] attribute keys to remove
+    # @return [OtelSpanPatch]
+    # @raise [ArgumentError] if an unknown keyword is given
+    def initialize(set_attributes: {}, delete_attributes: [])
+      super
+    end
+  end
+
+  # Sparse patches returned by an export-stage masking hook.
+  #
+  # @!attribute [r] span_patches
+  #   @return [Hash{OtelSpanIdentifier => OtelSpanPatch, nil}]
+  MaskOtelSpansResult = Data.define(:span_patches) do
+    # @param span_patches [Object] sparse patches keyed by batch identifiers
+    # @return [MaskOtelSpansResult]
+    # @raise [ArgumentError] if an unknown keyword is given
+    def initialize(span_patches: {})
+      super
+    end
+  end
+end

data/lib/langfuse/otel_span_patch_applier.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require_relative "otel_span_masking"
+
+module Langfuse
+  # Validates and applies one sparse patch to a cloned OpenTelemetry span.
+  # @api private
+  class OtelSpanPatchApplier
+    def initialize(logger:)
+      @logger = logger
+    end
+
+    def apply(span, patch)
+      unless valid_patch_containers?(patch)
+        @logger.error(
+          "Langfuse mask_otel_spans produced an invalid span patch; dropping the span " \
+          "from the Langfuse export (#{span_identity(span)})"
+        )
+        return nil
+      end
+
+      clone_with_attributes(span, patched_attributes(span, patch))
+    end
+
+    private
+
+    def valid_patch_containers?(patch)
+      patch.is_a?(OtelSpanPatch) &&
+        patch.delete_attributes.is_a?(Array) &&
+        patch.set_attributes.is_a?(Hash)
+    end
+
+    def patched_attributes(span, patch)
+      attributes = (span.attributes || {}).dup
+      patch.delete_attributes.each do |key|
+        next warn_invalid_key("delete", span) unless valid_attribute_key?(key)
+
+        attributes.delete(key)
+      end
+      patch.set_attributes.each do |key, value|
+        next warn_invalid_key("set", span) unless valid_attribute_key?(key)
+
+        apply_replacement(attributes, key, value, span)
+      end
+      attributes.freeze
+    end
+
+    def warn_invalid_key(operation, span)
+      @logger.warn(
+        "Langfuse mask_otel_spans ignored an invalid #{operation} attribute key (#{span_identity(span)})"
+      )
+    end
+
+    def apply_replacement(attributes, key, value, span)
+      if OpenTelemetry::SDK::Internal.valid_value?(value)
+        attributes[key] = frozen_copy(value)
+      else
+        attributes.delete(key)
+        @logger.warn(
+          "Langfuse mask_otel_spans replacement for attribute '#{key}' is not a valid " \
+          "OpenTelemetry attribute value (#{value.class}); omitting the attribute (#{span_identity(span)})"
+        )
+      end
+    end
+
+    # Trace and span IDs are opaque hex, unlike the attribute values being masked.
+    def span_identity(span)
+      "trace_id=#{span.hex_trace_id} span_id=#{span.hex_span_id}"
+    end
+
+    def valid_attribute_key?(key)
+      OpenTelemetry::SDK::Internal.valid_key?(key) && !key.empty?
+    end
+
+    # Replacement payloads can be large, so skip copying anything already immutable.
+    def frozen_copy(value)
+      case value
+      when String then value.frozen? ? value : value.dup.freeze
+      when Array then value.map { |element| frozen_copy(element) }.freeze
+      else value
+      end
+    end
+
+    def clone_with_attributes(span, attributes)
+      copy = span.dup
+      copy.attributes = attributes
+      copy.total_recorded_attributes = attributes.size + dropped_attribute_count(span)
+      copy
+    end
+
+    def dropped_attribute_count(span)
+      [span.total_recorded_attributes.to_i - (span.attributes || {}).size, 0].max
+    end
+  end
+  private_constant :OtelSpanPatchApplier
+end

data/lib/langfuse/pending_score_queue.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Thread-safe bounded queue that keeps scores until delivery succeeds.
+  #
+  # @api private
+  class PendingScoreQueue
+    # @return [Integer] Maximum number of pending scores
+    attr_reader :capacity
+
+    # @param capacity [Integer] Maximum number of pending scores
+    def initialize(capacity:)
+      @capacity = capacity
+      @events = []
+      @mutex = Mutex.new
+    end
+
+    # Add an event without waiting for queue capacity.
+    #
+    # @param event [Hash] Score ingestion event
+    # @return [Boolean] true when accepted, false when full
+    def push(event)
+      @mutex.synchronize do
+        return false if @events.length >= capacity
+
+        @events << event
+        true
+      end
+    end
+
+    # @return [Array<Hash>] Stable copy of pending events in insertion order
+    def snapshot
+      @mutex.synchronize { @events.dup }
+    end
+
+    # Return up to limit events from the front without removing them.
+    #
+    # @param limit [Integer] Maximum number of events to return
+    # @return [Array<Hash>] Stable copy of the pending prefix
+    def first(limit)
+      @mutex.synchronize { @events.first(limit) }
+    end
+
+    # Remove a delivered prefix while preserving newer events.
+    #
+    # @param count [Integer] Number of delivered events
+    # @return [void]
+    def remove_prefix(count)
+      @mutex.synchronize { @events.shift(count) }
+    end
+
+    # @return [Integer] Number of pending events
+    def size
+      @mutex.synchronize { @events.size }
+    end
+
+    # @return [Boolean] true when no events are pending
+    def empty?
+      @mutex.synchronize { @events.empty? }
+    end
+  end
+end

data/lib/langfuse/prompt_cache.rb

@@ -3,6 +3,7 @@
 require "monitor"
 require "base64"
 require_relative "stale_while_revalidate"
+require_relative "fork_safety"
 
 module Langfuse
   # Simple in-memory cache for prompt data with TTL
@@ -92,6 +93,7 @@ module Langfuse
       @monitor = Monitor.new
       @locks = {} # Track locks for in-memory locking
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
+      ForkSafety.register(self)
     end
 
     # Get a value from the cache
@@ -284,6 +286,12 @@ module Langfuse
 
     private
 
+    # Replace inherited synchronization and worker state in the child process.
+    def reset_after_fork
+      @monitor = Monitor.new
+      @locks = {}
+    end
+
     # Implementation of StaleWhileRevalidate abstract methods
 
     # Get value from cache (SWR interface)