langfuse-rb 0.12.3 → 0.12.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1dc8a77f2444284be3d7ebcec4379a0c21d04731c1e7acc8617d5a2482d0fe4
-  data.tar.gz: 9841995cd57d0cce72158d54bb267af26e59484de4abe52244713746e92d61ef
+  metadata.gz: 48ce9deac30bb5cbbb9df10203bf6a7ea930fc43fa14d29170bdf41f672c9213
+  data.tar.gz: 7fec96c181ce22befedbafefd937ab37114677abe82adf1fc71fa5903b0b5b02
 SHA512:
-  metadata.gz: f881f5df2b41e27f5825d8b71ee05d53680199fa2511b6fa3f2c9abad73a00ebe1dc8e8d5293d073909917980bd116f21d1394e1fdbd1e812303a47c085bcb34
-  data.tar.gz: 81a7274d6d1545a6e759b938a60135542714e42d6b9f5c751bd45f4ad0f3ff22f3259d68352580d08748048380319273f5fce1566682e053248d2f1decb9cb89
+  metadata.gz: 4acb19d60809504ec0e9f037de4633d43758fe8ce894d4924d0fead4f6e5a37a792d77d6c3cc432776713dd2124a9ee33748bf5d811aacf1b5a731f5e92b9445
+  data.tar.gz: f639e18b59bd80cea44f99b0db5458a833f05c42eef252dba7018b7537b752966995656b47b322c7aadcfc5e152e95f20612693c897ac8d0015c17fdfc2feacd

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.4] - 2026-10-12
+
+### Fixed
+- Mark explicit-ID observations as roots for legacy trace input/output (#129).
+- Create parentless roots for explicit `trace_id:` values and apply root sampling (#128).
+
 ## [0.12.3] - 2026-09-15
 
 ### Changed
@@ -188,7 +194,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.3...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.4...HEAD
+[0.12.4]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.3...v0.12.4
 [0.12.3]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.2...v0.12.3
 [0.12.2]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.1...v0.12.2
 [0.12.1]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.0...v0.12.1

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"
+    AS_ROOT = "langfuse.internal.as_root"
     IS_APP_ROOT = "langfuse.internal.is_app_root"
 
     # Experiment attributes

data/lib/langfuse/otel_setup.rb

@@ -6,6 +6,7 @@ require "base64"
 require_relative "masking_exporter"
 require_relative "trace_export_guard"
 require_relative "resilient_metrics_reporter"
+require_relative "root_span_id_generator"
 
 module Langfuse
   # OpenTelemetry initialization and setup for Langfuse tracing.
@@ -122,7 +123,7 @@ module Langfuse
         )
 
         OpenTelemetry::SDK::Trace::TracerProvider
-          .new(sampler: build_sampler(config.sample_rate))
+          .new(sampler: build_sampler(config.sample_rate), id_generator: RootSpanIdGenerator.new)
           .tap { |provider| provider.add_span_processor(processor) }
       end
 

data/lib/langfuse/root_span_id_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Supplies deterministic IDs only during explicit root creation on one provider.
+  #
+  # @api private
+  class RootSpanIdGenerator
+    def initialize
+      @trace_id_key = OpenTelemetry::Context.create_key("langfuse-root-trace-id")
+    end
+
+    def generate_trace_id
+      OpenTelemetry::Context.value(@trace_id_key) || OpenTelemetry::Trace.generate_trace_id
+    end
+
+    def generate_span_id
+      OpenTelemetry::Trace.generate_span_id
+    end
+
+    # A trace ID identifies a trace, not a missing parent. Preserve propagated
+    # attributes while clearing the ambient span and its internal root claim.
+    # The provider-local key and Context scope isolate concurrent fibers/threads
+    # and restore the caller's context even when span creation raises.
+    #
+    # @param trace_id [String] Validated binary W3C trace ID
+    # @yieldparam context [OpenTelemetry::Context] Parentless root context
+    # @return [Object] The block result
+    # @api private
+    def with_trace_id(trace_id)
+      context = OpenTelemetry::Trace.context_with_span(OpenTelemetry::Trace::Span::INVALID)
+      if Propagation.baggage_available?
+        context = OpenTelemetry::Baggage.remove_value(Propagation::LANGFUSE_TRACE_ID_BAGGAGE_KEY, context: context)
+      end
+      context = context.set_value(@trace_id_key, trace_id)
+      OpenTelemetry::Context.with_current(context) { yield context }
+    end
+  end
+end

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -463,14 +463,15 @@ module Langfuse
     # Creates a new observation (root or child)
     #
     # This is the module-level factory method that creates observations of any type.
-    # It can create root observations (when parent_span_context is nil) or child
-    # observations (when parent_span_context is provided).
+    # An explicit trace_id creates a parentless root. Otherwise it inherits the
+    # active span, or the supplied parent_span_context for child observations.
     #
     # @param name [String] Descriptive name for the observation
     # @param attrs [Hash, Types::SpanAttributes, Types::GenerationAttributes, nil] Observation attributes
     # @param as_type [Symbol, String] Observation type (:span, :generation, :event, etc.)
-    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID to attach the observation to.
+    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID for a new parentless root.
     #   Mutually exclusive with `parent_span_context`. Use {Langfuse.create_trace_id} to generate one.
+    #   Also marks the observation as a root for legacy trace summaries.
     # @param parent_span_context [OpenTelemetry::Trace::SpanContext, nil] Parent span context for child observations
     # @param start_time [Time, Integer, nil] Optional start time (Time object or Unix timestamp in nanoseconds)
     # @param skip_validation [Boolean] Skip validation (for internal use). Defaults to false.
@@ -496,13 +497,17 @@ module Langfuse
       type_str = as_type.to_s
       validate_observation_type!(as_type, type_str) unless skip_validation
 
-      otel_tracer = otel_tracer()
+      otel_tracer, id_generator = otel_tracer_and_id_generator
       otel_span = create_otel_span(
         name: name,
         start_time: start_time,
         parent_span_context: parent_span_context,
-        otel_tracer: otel_tracer
+        otel_tracer: otel_tracer,
+        trace_id: trace_id && parent_span_context.trace_id,
+        id_generator: id_generator
       )
+      # Match Python's explicit trace-context root mark for legacy trace input/output.
+      otel_span.set_attribute(OtelAttributes::AS_ROOT, true) if trace_id
       apply_observation_attributes(otel_span, type_str, attrs)
 
       observation = wrap_otel_span(otel_span, type_str, otel_tracer)
@@ -517,7 +522,7 @@ module Langfuse
     # @param name [String] Descriptive name for the observation
     # @param attrs [Hash] Observation attributes (optional positional or keyword)
     # @param as_type [Symbol, String] Observation type (:span, :generation, :event, etc.)
-    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID to attach the observation to.
+    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID for a new parentless root.
     #   Use {Langfuse.create_trace_id} to generate one. Forwarded to {.start_observation}.
     # @param kwargs [Hash] Additional keyword arguments merged into observation attributes (e.g., input:, output:, metadata:)
     # @yield [observation] Optional block that receives the observation object
@@ -605,13 +610,19 @@ module Langfuse
       false
     end
 
-    # Gets the OpenTelemetry tracer for Langfuse
+    # Gets the OpenTelemetry tracer and its root ID generator for Langfuse
     #
-    # @return [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
-    def otel_tracer
-      return tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION) if ensure_tracing_started
+    # Capture the ID generator from the same provider as the returned tracer,
+    # so concurrent shutdown or reconfiguration cannot switch its root context key.
+    # @return [Array] The OTel tracer and optional root ID generator
+    # @api private
+    def otel_tracer_and_id_generator
+      return [noop_tracer, nil] unless ensure_tracing_started
 
-      noop_tracer
+      provider = tracer_provider
+      id_generator = provider.id_generator if provider.respond_to?(:id_generator)
+      id_generator = nil unless id_generator.is_a?(RootSpanIdGenerator)
+      [provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION), id_generator]
     end
 
     # Creates an OpenTelemetry span (root or child)
@@ -620,8 +631,20 @@ module Langfuse
     # @param start_time [Time, Integer, nil] Optional start time
     # @param parent_span_context [OpenTelemetry::Trace::SpanContext, nil] Parent span context
     # @param otel_tracer [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
+    # @param trace_id [String, nil] Validated binary trace ID for an explicit root
+    # @param id_generator [RootSpanIdGenerator, nil] ID generator captured with the tracer
     # @return [OpenTelemetry::SDK::Trace::Span] The created span
-    def create_otel_span(name:, otel_tracer:, start_time: nil, parent_span_context: nil)
+    # @api private
+    def create_otel_span(name:, otel_tracer:, start_time: nil, parent_span_context: nil, trace_id: nil,
+                         id_generator: nil)
+      if trace_id && id_generator
+        # Start an actual root through the internal provider's ID generator, so
+        # native root sampling sees an invalid parent rather than a sampled placeholder.
+        return id_generator.with_trace_id(trace_id) do |context|
+          otel_tracer.start_span(name, with_parent: context, start_timestamp: start_time)
+        end
+      end
+
       if parent_span_context
         # Create child span with parent context
         # Create a non-recording span from the parent context to set in context

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.12.3
+  version: 0.12.4
 platform: ruby
 authors:
 - SimplePractice
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -222,6 +222,7 @@ files:
 - lib/langfuse/rails_cache_adapter.rb
 - lib/langfuse/read_api.rb
 - lib/langfuse/resilient_metrics_reporter.rb
+- lib/langfuse/root_span_id_generator.rb
 - lib/langfuse/sampling.rb
 - lib/langfuse/score_client.rb
 - lib/langfuse/score_value.rb