langfuse-rb 0.6.0 → 0.8.0

data/lib/langfuse/otel_setup.rb

@@ -2,104 +2,78 @@
 
 require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
-require "opentelemetry/trace/propagation/trace_context"
 require "base64"
 
 module Langfuse
-  # OpenTelemetry initialization and setup
-  #
-  # Handles configuration of the OTel SDK with Langfuse OTLP exporter
-  # when tracing is enabled.
-  #
+  # OpenTelemetry initialization and setup for Langfuse tracing.
+  # rubocop:disable Metrics/ModuleLength
   module OtelSetup
+    TRACING_CONFIG_FIELDS = %i[
+      public_key
+      secret_key
+      base_url
+      environment
+      release
+      sample_rate
+      should_export_span
+      tracing_async
+      batch_size
+      flush_interval
+    ].freeze
+    private_constant(:TRACING_CONFIG_FIELDS)
+
     class << self
-      # @return [OpenTelemetry::SDK::Trace::TracerProvider, nil] The configured tracer provider
+      # @return [OpenTelemetry::SDK::Trace::TracerProvider, nil] The configured internal tracer provider
       attr_reader :tracer_provider
 
-      # Initialize OpenTelemetry with Langfuse OTLP exporter
+      # Initialize Langfuse's internal tracer provider without mutating global OpenTelemetry state.
       #
       # @param config [Langfuse::Config] The Langfuse configuration
-      # @return [void]
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @return [OpenTelemetry::SDK::Trace::TracerProvider]
       def setup(config)
-        # Create OTLP exporter configured for Langfuse
-        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
-          endpoint: "#{config.base_url}/api/public/otel/v1/traces",
-          headers: build_headers(config.public_key, config.secret_key),
-          compression: "gzip"
-        )
-
-        # Create processor based on async configuration
-        # IMPORTANT: Always use BatchSpanProcessor (even in sync mode) to ensure spans
-        # are exported together, which allows proper parent-child relationship detection
-        processor = if config.tracing_async
-                      # Async: BatchSpanProcessor batches and sends in background
-                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-                        exporter,
-                        max_queue_size: config.batch_size * 2, # Buffer more than batch_size
-                        schedule_delay: config.flush_interval * 1000, # Convert seconds to milliseconds
-                        max_export_batch_size: config.batch_size
-                      )
-                    else
-                      # Sync: BatchSpanProcessor with minimal delay (flushes on force_flush)
-                      # This collects spans from the same trace and exports them together,
-                      # which is critical for correct parent_observation_id calculation
-                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-                        exporter,
-                        max_queue_size: config.batch_size * 2,
-                        schedule_delay: 60_000, # 60 seconds (relies on explicit force_flush)
-                        max_export_batch_size: config.batch_size
-                      )
-                    end
-
-        # Create TracerProvider with processor
-        @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
-        @tracer_provider.add_span_processor(processor)
-
-        # Add span processor for propagated attributes and env/release defaults
-        # This must be added AFTER the BatchSpanProcessor so it runs before export and can
-        # apply all attributes (propagated IDs, environment, release) to the spans being sent
-        span_processor = SpanProcessor.new(config: config)
-        @tracer_provider.add_span_processor(span_processor)
-
-        # Set as global tracer provider
-        OpenTelemetry.tracer_provider = @tracer_provider
-
-        # Configure W3C TraceContext propagator if not already set
-        if OpenTelemetry.propagation.is_a?(OpenTelemetry::Context::Propagation::NoopTextMapPropagator)
-          OpenTelemetry.propagation = OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new
-          config.logger.debug("Langfuse: Configured W3C TraceContext propagator")
-        else
-          config.logger.debug("Langfuse: Using existing propagator: #{OpenTelemetry.propagation.class}")
+        validate_tracing_config!(config)
+        return existing_provider_for(config) if initialized?
+
+        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
 
-        mode = config.tracing_async ? "async" : "sync"
-        config.logger.info("Langfuse tracing initialized with OpenTelemetry (#{mode} mode)")
+        log_initialized(config)
+        provider
+      rescue StandardError
+        rollback_provider(provider) if created
+        raise
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-      # Shutdown the tracer provider and flush any pending spans
+      # Shutdown the internal tracer provider and flush any pending spans.
       #
       # @param timeout [Integer] Timeout in seconds
       # @return [void]
       def shutdown(timeout: 30)
-        return unless @tracer_provider
-
-        @tracer_provider.shutdown(timeout: timeout)
-        @tracer_provider = nil
+        provider = nil
+        setup_mutex.synchronize do
+          provider = @tracer_provider
+          @tracer_provider = nil
+          @config_snapshot = nil
+        end
+        provider&.shutdown(timeout: timeout)
       end
 
-      # Force flush all pending spans
+      # Force flush all pending spans on the internal tracer provider.
       #
       # @param timeout [Integer] Timeout in seconds
       # @return [void]
       def force_flush(timeout: 30)
-        return unless @tracer_provider
-
-        @tracer_provider.force_flush(timeout: timeout)
+        @tracer_provider&.force_flush(timeout: timeout)
       end
 
-      # Check if OTel is initialized
+      # Check if Langfuse tracing has been initialized.
       #
       # @return [Boolean]
       def initialized?
@@ -108,18 +82,104 @@ module Langfuse
 
       private
 
-      # Build HTTP headers for Langfuse OTLP endpoint
-      #
-      # @param public_key [String] Langfuse public API key
-      # @param secret_key [String] Langfuse secret API key
-      # @return [Hash] HTTP headers with Basic Auth
+      def existing_provider_for(config)
+        snapshot = tracing_config_snapshot(config)
+        if @config_snapshot == snapshot
+          config.logger.debug("Langfuse tracing already initialized; reusing existing tracer provider")
+        else
+          config.logger.warn(
+            "Langfuse tracing is already initialized. Changes to #{TRACING_CONFIG_FIELDS.join(', ')} " \
+            "require Langfuse.reset! before they take effect."
+          )
+        end
+        @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
+
+        [current, created]
+      end
+
+      def rollback_provider(provider)
+        setup_mutex.synchronize do
+          return unless @tracer_provider.equal?(provider)
+
+          @tracer_provider = nil
+          @config_snapshot = nil
+        end
+        provider.shutdown(timeout: 1)
+      rescue StandardError
+        nil
+      end
+
+      def build_tracer_provider(config)
+        provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+          sampler: build_sampler(config.sample_rate)
+        )
+        provider.add_span_processor(
+          SpanProcessor.new(config: config, exporter: build_exporter(config))
+        )
+        provider
+      end
+
+      def build_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),
+          compression: "gzip"
+        )
+      end
+
+      def log_initialized(config)
+        mode = config.tracing_async ? "async" : "sync"
+        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
+
+      def setup_mutex
+        @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}" }
+      end
+
+      def build_sampler(sample_rate)
+        Sampling.build_sampler(sample_rate) || OpenTelemetry::SDK::Trace::Samplers::ALWAYS_ON
       end
     end
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/langfuse/sampling.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Shared sampling helpers for trace and score emission.
+  #
+  # @api private
+  module Sampling
+    module_function
+
+    # Build the sampler used by both trace export and trace-linked score emission.
+    #
+    # @param sample_rate [Float] Sampling rate from 0.0 to 1.0
+    # @return [OpenTelemetry::SDK::Trace::Samplers::TraceIdRatioBased, nil]
+    def build_sampler(sample_rate)
+      return nil if sample_rate >= 1.0
+
+      OpenTelemetry::SDK::Trace::Samplers::TraceIdRatioBased.new(sample_rate)
+    end
+  end
+end

data/lib/langfuse/score_client.rb

@@ -31,6 +31,8 @@ module Langfuse
     # @return [Logger] Logger instance
     attr_reader :logger
 
+    HEX_TRACE_ID_PATTERN = /\A[0-9a-f]{32}\z/
+
     # Initialize a new ScoreClient
     #
     # @param api_client [ApiClient] The API client for sending batches
@@ -43,6 +45,9 @@ module Langfuse
       @mutex = Mutex.new
       @flush_thread = nil
       @shutdown = false
+      # Match the immutable tracing setup contract: once this client exists, later config
+      # mutations must not change score sampling without rebuilding the client.
+      @score_sampler = Sampling.build_sampler(config.sample_rate)
 
       start_flush_timer
     end
@@ -76,28 +81,19 @@ module Langfuse
     def create(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
                metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
       validate_name(name)
-      # Keep identifier policy server-side to preserve cross-SDK parity and avoid blocking valid future payloads.
       normalized_value = normalize_value(value, data_type)
       data_type_str = Types::SCORE_DATA_TYPES[data_type] || raise(ArgumentError, "Invalid data_type: #{data_type}")
 
+      return unless enqueue_trace_linked_score?(trace_id)
+
       event = build_score_event(
-        name: name,
-        value: normalized_value,
-        id: id,
-        trace_id: trace_id,
-        session_id: session_id,
-        observation_id: observation_id,
-        comment: comment,
-        metadata: metadata,
-        environment: environment,
-        data_type: data_type_str,
-        dataset_run_id: dataset_run_id,
-        config_id: config_id
+        name: name, value: normalized_value, id: id, trace_id: trace_id,
+        session_id: session_id, observation_id: observation_id, comment: comment,
+        metadata: metadata, environment: environment, data_type: data_type_str,
+        dataset_run_id: dataset_run_id, config_id: config_id
       )
 
       @queue << event
-
-      # Trigger flush if batch size reached
       flush if @queue.size >= config.batch_size
     rescue StandardError => e
       logger.error("Langfuse score creation failed: #{e.message}")
@@ -294,14 +290,43 @@ module Langfuse
     # @return [Hash] Hash with :trace_id and :observation_id (may be nil)
     def extract_ids_from_active_span
       span = OpenTelemetry::Trace.current_span
-      return { trace_id: nil, observation_id: nil } unless span&.recording?
+      span_context = span&.context
+      return { trace_id: nil, observation_id: nil } unless span_context&.valid?
 
       {
-        trace_id: span.context.trace_id.unpack1("H*"),
-        observation_id: span.context.span_id.unpack1("H*")
+        trace_id: span_context.trace_id.unpack1("H*"),
+        observation_id: span_context.span_id.unpack1("H*")
       }
     end
 
+    # Score sampling is decided purely by the configured sampler on the trace_id hash,
+    # matching langfuse-python. Non-hex trace ids and session/dataset-only scores bypass sampling.
+    def enqueue_trace_linked_score?(trace_id)
+      return true if trace_id.nil?
+      return true unless HEX_TRACE_ID_PATTERN.match?(trace_id)
+
+      sampler = score_sampler
+      return true if sampler.nil?
+      return true unless sampler.respond_to?(:should_sample?)
+
+      sample_result = sampler.should_sample?(
+        trace_id: [trace_id].pack("H*"),
+        parent_context: nil,
+        links: [],
+        name: "score",
+        kind: OpenTelemetry::Trace::SpanKind::INTERNAL,
+        attributes: {}
+      )
+      sample_result.sampled?
+    rescue StandardError => e
+      logger.warn("Langfuse score sampling fallback for trace_id=#{trace_id}: #{e.message}")
+      true
+    end
+
+    # Sampler is pinned at ScoreClient construction to match the "sample_rate requires reset!"
+    # contract and to keep each client's sampling scoped to its own config.
+    attr_reader :score_sampler
+
     # Send a batch of events to the API
     #
     # @param events [Array<Hash>] Array of event hashes

data/lib/langfuse/span_filter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Instrumentation scope name used by module-level Langfuse tracing.
+  LANGFUSE_TRACER_NAME = "langfuse-rb"
+
+  # Conservative allowlist of instrumentation scope prefixes that clearly belong to LLM workflows.
+  KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = [
+    LANGFUSE_TRACER_NAME,
+    "agent_framework",
+    "ai",
+    "haystack",
+    "langsmith",
+    "litellm",
+    "openinference",
+    "opentelemetry.instrumentation.anthropic",
+    "strands-agents",
+    "vllm"
+  ].freeze
+
+  # Matched per span in the export path, so avoid allocating the dotted form each call.
+  KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES =
+    KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES.map { |prefix| "#{prefix}." }.freeze
+  private_constant :KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES
+
+  class << self
+    # Return whether the span was created by Langfuse's tracer.
+    #
+    # @param span [#instrumentation_scope] Span or span data to inspect
+    # @return [Boolean]
+    def langfuse_span?(span)
+      instrumentation_scope_name(span) == LANGFUSE_TRACER_NAME
+    end
+
+    # Return whether the span contains `gen_ai.*` attributes.
+    #
+    # @param span [#attributes] Span or span data to inspect
+    # @return [Boolean]
+    def genai_span?(span)
+      attributes = span.attributes
+      return false unless attributes
+
+      attributes.keys.any? { |key| key.is_a?(String) && key.start_with?("gen_ai.") }
+    end
+
+    # Return whether the span came from a known LLM instrumentation scope.
+    #
+    # @param span [#instrumentation_scope] Span or span data to inspect
+    # @return [Boolean]
+    def known_llm_instrumentor?(span)
+      scope_name = instrumentation_scope_name(span)
+      return false unless scope_name
+
+      return true if KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES.include?(scope_name)
+
+      KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES.any? do |dotted_prefix|
+        scope_name.start_with?(dotted_prefix)
+      end
+    end
+
+    # Return whether a span should be exported when no custom filter is configured.
+    #
+    # @param span [#instrumentation_scope, #attributes] Span or span data to inspect
+    # @return [Boolean]
+    def default_export_span?(span)
+      langfuse_span?(span) || genai_span?(span) || known_llm_instrumentor?(span)
+    end
+
+    # Cross-SDK parity keeps the `is_*` names public for compatibility.
+    alias is_langfuse_span langfuse_span?
+    alias is_genai_span genai_span?
+    alias is_known_llm_instrumentor known_llm_instrumentor?
+    alias is_default_export_span default_export_span?
+
+    private
+
+    def instrumentation_scope_name(span)
+      span.instrumentation_scope&.name
+    end
+  end
+end

data/lib/langfuse/span_processor.rb

@@ -3,22 +3,26 @@
 require "opentelemetry/sdk"
 
 module Langfuse
-  # Span processor that applies default and propagated trace attributes on new spans.
-  #
-  # On span start, this processor first applies configured trace defaults
-  # (environment/release), then overlays attributes propagated in OpenTelemetry
-  # context (user/session/metadata/tags/version). This ensures consistent
-  # trace dimensions while still honoring per-request propagation.
+  # Batch span processor that owns Langfuse's enrichment and export filtering.
   #
   # @api private
-  class SpanProcessor < OpenTelemetry::SDK::Trace::SpanProcessor
-    # @param config [Langfuse::Config, nil] SDK configuration used to build trace defaults
-    def initialize(config: Langfuse.configuration)
+  class SpanProcessor < OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor
+    # @param config [Langfuse::Config] SDK configuration used for defaults and filtering
+    # @param exporter [#export, #force_flush, #shutdown] Span exporter used by the batch processor
+    def initialize(config:, exporter:)
+      @logger = config.logger
       @default_trace_attributes = build_default_trace_attributes(config).freeze
-      super()
+      @should_export_span = config.should_export_span || Langfuse.method(:default_export_span?)
+
+      super(
+        exporter,
+        max_queue_size: config.batch_size * 2,
+        schedule_delay: schedule_delay_for(config),
+        max_export_batch_size: config.batch_size
+      )
     end
 
-    # Called when a span starts
+    # Apply Langfuse trace defaults and propagated attributes before a span records work.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that started
     # @param parent_context [OpenTelemetry::Context] The parent context
@@ -30,41 +34,28 @@ module Langfuse
       apply_attributes(span, propagated_attributes(parent_context))
     end
 
-    # Called when a span ends
+    # Drop spans when the export filter rejects them or raises.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that ended
     # @return [void]
     def on_finish(span)
-      # No-op - we don't need to do anything when spans finish
-    end
+      return unless should_export_span?(span)
 
-    # Shutdown the processor
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def shutdown(timeout: nil)
-      # No-op - nothing to clean up
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
-    end
-
-    # Force flush (no-op for this processor)
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def force_flush(timeout: nil)
-      # No-op - nothing to flush
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
+      super
     end
 
     private
 
-    def build_default_trace_attributes(config)
-      return {} unless config
+    # Sync mode relies on explicit `force_flush` calls, so keep the background flush
+    # interval long enough that it rarely fires on its own.
+    SYNC_SCHEDULE_DELAY_MS = 60_000
+    private_constant :SYNC_SCHEDULE_DELAY_MS
+
+    def schedule_delay_for(config)
+      config.tracing_async ? config.flush_interval * 1000 : SYNC_SCHEDULE_DELAY_MS
+    end
 
+    def build_default_trace_attributes(config)
       OtelAttributes.create_trace_attributes(
         { environment: config.environment, release: config.release }
       )
@@ -79,5 +70,15 @@ module Langfuse
     def apply_attributes(span, attributes)
       attributes.each { |key, value| span.set_attribute(key, value) }
     end
+
+    def should_export_span?(span)
+      @should_export_span.call(span)
+    rescue StandardError => e
+      @logger.error(
+        "Langfuse tracing dropped span '#{span.name}' because should_export_span raised: " \
+        "#{e.class}: #{e.message}"
+      )
+      false
+    end
   end
 end

data/lib/langfuse/trace_id.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Langfuse
+  # Deterministic and random trace/observation ID generation.
+  #
+  # Mirrors the Python and JS SDK helpers so the same seed produces the same
+  # trace ID across all three SDKs. This lets callers correlate Langfuse traces
+  # with external system identifiers (database primary keys, request IDs, etc.)
+  # and score or reference traces later without having to persist the generated
+  # Langfuse ID.
+  #
+  # @example Deterministic from an external ID
+  #   trace_id = Langfuse::TraceId.create(seed: "order-12345")
+  #   Langfuse.observe("process-order", trace_id: trace_id) { |span| ... }
+  #   Langfuse.create_score(name: "quality", value: 0.9, trace_id: trace_id)
+  #
+  # @example Random (no seed)
+  #   trace_id = Langfuse::TraceId.create
+  module TraceId
+    TRACE_ID_PATTERN = /\A[0-9a-f]{32}\z/
+    INVALID_TRACE_ID = ("0" * 32)
+
+    private_constant :TRACE_ID_PATTERN, :INVALID_TRACE_ID
+
+    class << self
+      # Generate a W3C trace ID (32 lowercase hex chars).
+      #
+      # With no seed, delegates to OpenTelemetry's random trace ID generator.
+      # With a seed, takes the first 16 bytes of SHA-256(seed) so the same
+      # input always produces the same trace ID.
+      #
+      # @note Avoid passing PII, secrets, or credentials as seeds — the raw seed
+      #   value appears in application code and may leak through logs/backtraces.
+      #   Use stable external identifiers (database PKs, UUIDs, request IDs).
+      # @param seed [String, nil] Optional seed for deterministic generation.
+      #   Must be a String if provided; non-String values raise ArgumentError
+      #   for cross-SDK parity (Python/JS both reject non-strings).
+      # @return [String] 32-character lowercase hex trace ID
+      # @raise [ArgumentError] if seed is not nil and not a String
+      def create(seed: nil)
+        return OpenTelemetry::Trace.generate_trace_id.unpack1("H*") if seed.nil?
+
+        Digest::SHA256.digest(validate_seed!(seed))[0, 16].unpack1("H*")
+      end
+
+      private
+
+      # @api private
+      def validate_seed!(seed)
+        raise ArgumentError, "seed must be a String, got #{seed.class}" unless seed.is_a?(String)
+
+        # ASCII-8BIT strings (binary) often already hold valid UTF-8 bytes
+        # but can't be transcoded — re-tag them instead.
+        return seed.dup.force_encoding("UTF-8") if seed.encoding == Encoding::ASCII_8BIT
+
+        seed.encode("UTF-8")
+      end
+
+      # @api private
+      def valid?(trace_id)
+        return false unless trace_id.is_a?(String) && TRACE_ID_PATTERN.match?(trace_id)
+
+        trace_id != INVALID_TRACE_ID
+      end
+
+      # Build a sampled OpenTelemetry SpanContext carrying the given hex trace ID.
+      #
+      # A random span_id is generated as a placeholder — only the trace_id is
+      # consumed by the child span that gets created.
+      #
+      # @api private
+      def to_span_context(trace_id)
+        raise ArgumentError, "Invalid trace_id: #{trace_id.inspect}" unless valid?(trace_id)
+
+        OpenTelemetry::Trace::SpanContext.new(
+          trace_id: [trace_id].pack("H*"),
+          span_id: OpenTelemetry::Trace.generate_span_id,
+          trace_flags: OpenTelemetry::Trace::TraceFlags::SAMPLED,
+          # Cross-SDK parity: Python uses is_remote=False (_create_remote_parent_span).
+          # Changing this would alter ParentBased sampler behavior across SDKs.
+          remote: false
+        )
+      end
+    end
+  end
+end

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end