langfuse-rb 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99afbe7d86b8a94bdb08e95477b88bd6ced6a5ca01cbf794eec86d23cf716f0e
-  data.tar.gz: 2098919014cab53a2a2f7b4e22b06c4a87f306cde866ef87e45033e558caf472
+  metadata.gz: 20d0cd9db76be223db4867cbc9f54f59ee5accc0058e29bab14561c457d8fecc
+  data.tar.gz: b43bd144dca940b375ac916feca399f9e10da54db201fff9f4d140acdd301ec5
 SHA512:
-  metadata.gz: 8a5ee8263a21a8bfff3ec9ce2603a85ba2f26522aa757ddbe16e62cb96e46830fdc9c4958ebf28ca228b84a2b46bbe104ad29d2a7761d6bbdda5c67c67145bf3
-  data.tar.gz: f9682ef80e7b52800f8d566c8d5a4132012441a653f4bed74ace178997a9fed5df904119e8b15c5c74aa6c61ca187af87e26bad91c878d86b0afc1579da8606c
+  metadata.gz: 66175d8c844c314ac8f62180e98d3bc95f8fb3934ea71880d7bd7e21fc5bbbd06f472a5b992cb4529929aab27cc153a7641f8f2a0f73ffb2ed869df127056980
+  data.tar.gz: 0e7a1e8e7a34aeaa964d8b1c0295c6448a3fa58e075c1bdda6e6aafe98b00ee9d48a7e904c3724b1b2ab42d166119bf80b6aa7be21eb750b072768d6588363d3

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-09-03
+
+### Fixed
+- Emit Langfuse v4 experiment attributes for local and dataset-backed experiment observations (#118).
+
 ## [0.12.0] - 2026-08-20
 
 ### Changed
@@ -173,7 +178,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.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.1...HEAD
+[0.12.1]: https://github.com/simplepractice/langfuse-rb/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.0...v0.10.1

data/lib/langfuse/dataset_item_client.rb

@@ -103,6 +103,7 @@ module Langfuse
     #
     # Executes the block inside an observed span, flushes the trace, then
     # creates a dataset run item linking this item to the resulting trace.
+    # Use {Client#run_experiment} when Langfuse v4 experiment attribution is required.
     #
     # @param run_name [String] run name for grouping
     # @param run_description [String, nil] optional run description

data/lib/langfuse/experiment_attributes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module Langfuse
+  # Builds the OpenTelemetry attributes that identify v4 experiment observations.
+  #
+  # @api private
+  module ExperimentAttributes
+    ENVIRONMENT = "sdk-experiment"
+
+    def self.generate_experiment_id
+      SecureRandom.hex(8)
+    end
+
+    def self.generate_item_id(input)
+      serialized_input = OtelAttributes.serialize(input, preserve_strings: true) || input.to_s
+      Digest::SHA256.hexdigest(serialized_input)[0, 16]
+    end
+
+    # rubocop:disable Metrics/ParameterLists
+    def self.propagated(experiment_id:, run_name:, item_id:, root_observation_id:,
+                        dataset_id: nil, experiment_metadata: nil, item_metadata: nil, mask: nil)
+      attributes = {
+        OtelAttributes::EXPERIMENT_ID => experiment_id,
+        OtelAttributes::EXPERIMENT_NAME => run_name,
+        OtelAttributes::EXPERIMENT_DATASET_ID => dataset_id,
+        OtelAttributes::EXPERIMENT_ITEM_ID => item_id,
+        OtelAttributes::EXPERIMENT_ITEM_ROOT_OBSERVATION_ID => root_observation_id,
+        OtelAttributes::ENVIRONMENT => ENVIRONMENT
+      }.compact
+      attributes.merge!(masked_metadata(experiment_metadata, OtelAttributes::EXPERIMENT_METADATA, mask))
+      attributes.merge!(masked_metadata(item_metadata, OtelAttributes::EXPERIMENT_ITEM_METADATA, mask))
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def self.root(description:, expected_output:, mask: nil)
+      masked_output = Masking.apply(expected_output, mask: mask)
+      {
+        OtelAttributes::EXPERIMENT_DESCRIPTION => description,
+        OtelAttributes::EXPERIMENT_ITEM_EXPECTED_OUTPUT =>
+          OtelAttributes.serialize(masked_output, preserve_strings: true)
+      }.compact
+    end
+
+    def self.observation_metadata(name:, run_name:, experiment_metadata:, item_metadata:,
+                                  dataset_id: nil, dataset_item_id: nil)
+      metadata = hash_metadata(item_metadata).merge(hash_metadata(experiment_metadata))
+      metadata[:experiment_name] = name
+      metadata[:experiment_run_name] = run_name
+      metadata[:dataset_id] = dataset_id if dataset_id
+      metadata[:dataset_item_id] = dataset_item_id if dataset_item_id
+      metadata
+    end
+
+    def self.masked_metadata(metadata, prefix, mask)
+      OtelAttributes.flatten_metadata(Masking.apply(metadata, mask: mask), prefix)
+    end
+    private_class_method :masked_metadata
+
+    def self.hash_metadata(metadata)
+      metadata.is_a?(Hash) ? metadata : {}
+    end
+    private_class_method :hash_metadata
+  end
+end

data/lib/langfuse/experiment_result.rb

@@ -18,26 +18,29 @@ module Langfuse
     # @return [String, nil] run description
     # @return [Array<ItemResult>] per-item results (all items, including failures)
     # @return [Array<Evaluation>] run-level evaluation results
+    # @return [String, nil] resolved experiment ID shared by the run
     # @return [String, nil] dataset run ID from the server
     # @return [String, nil] URL to the dataset run in Langfuse UI
     attr_reader :name, :run_name, :description, :item_results, :run_evaluations,
-                :dataset_run_id, :dataset_run_url
+                :experiment_id, :dataset_run_id, :dataset_run_url
 
     # @param name [String] experiment/run name
     # @param item_results [Array<ItemResult>] per-item results
     # @param run_evaluations [Array<Evaluation>] run-level evaluations
     # @param run_name [String, nil] auto-generated run name
     # @param description [String, nil] run description
+    # @param experiment_id [String, nil] resolved experiment ID shared by the run
     # @param dataset_run_id [String, nil] dataset run ID from the server
     # @param dataset_run_url [String, nil] URL to the dataset run in Langfuse UI
     # rubocop:disable Metrics/ParameterLists
     def initialize(name:, item_results:, run_evaluations: [], run_name: nil, description: nil,
-                   dataset_run_id: nil, dataset_run_url: nil)
+                   experiment_id: nil, dataset_run_id: nil, dataset_run_url: nil)
       @name = name
       @item_results = item_results
       @run_evaluations = run_evaluations
       @run_name = run_name
       @description = description
+      @experiment_id = experiment_id
       @dataset_run_id = dataset_run_id
       @dataset_run_url = dataset_run_url
     end

data/lib/langfuse/experiment_runner.rb

@@ -33,6 +33,8 @@ module Langfuse
       @description = description
       @run_name = run_name || "#{name} - #{Time.now.utc.iso8601}"
       @logger = Langfuse.configuration.logger
+      @fallback_experiment_id = ExperimentAttributes.generate_experiment_id
+      @resolved_experiment_id = nil
       @dataset_run_id = nil
       @dataset_id = nil
     end
@@ -53,6 +55,7 @@ module Langfuse
         run_evaluations: run_evals,
         run_name: @run_name,
         description: @description,
+        experiment_id: resolved_experiment_id,
         dataset_run_id: @dataset_run_id,
         dataset_run_url: build_dataset_run_url
       )
@@ -68,7 +71,7 @@ module Langfuse
         return ItemResult.new(item: item, trace_id: trace_id, observation_id: observation_id, error: task_error)
       end
 
-      evaluations = execute_evaluators(item, output, trace_id)
+      evaluations = execute_evaluators(item, output, trace_id, observation_id)
       ItemResult.new(item: item, output: output, trace_id: trace_id,
                      observation_id: observation_id, evaluations: evaluations)
     end
@@ -77,21 +80,19 @@ module Langfuse
       TracedExecution.call(
         trace_name: "experiment-#{@name}",
         input: item.input,
-        metadata: @metadata,
-        task: ->(_span) { @task.call(item) }
-      ) do |span, trace_id|
-        # Link before running task — server accepts forward-referenced trace IDs
-        link_to_dataset_run(item, trace_id, span.id) if item.is_a?(DatasetItemClient)
-      end
+        metadata: observation_metadata(item),
+        task: ->(_span) { @task.call(item) },
+        prepare_context: ->(span, trace_id) { prepare_experiment_context(item, span, trace_id) }
+      )
     end
 
-    def execute_evaluators(item, output, trace_id)
+    def execute_evaluators(item, output, trace_id, observation_id)
       evaluations = @evaluators.flat_map do |evaluator|
         raw_result = call_evaluator(evaluator, item, output)
         normalize_evaluator_result(raw_result, source: "Evaluator")
       end
 
-      evaluations.each { |evaluation| persist_score(evaluation, trace_id) }
+      evaluations.each { |evaluation| persist_score(evaluation, trace_id, observation_id) }
       evaluations
     end
 
@@ -104,10 +105,11 @@ module Langfuse
       nil
     end
 
-    def persist_score(evaluation, trace_id)
+    def persist_score(evaluation, trace_id, observation_id)
       @client.create_score(
         name: evaluation.name, value: evaluation.value,
-        trace_id: trace_id, comment: evaluation.comment, data_type: evaluation.data_type,
+        trace_id: trace_id, observation_id: observation_id,
+        comment: evaluation.comment, data_type: evaluation.data_type,
         config_id: evaluation.config_id, metadata: evaluation.metadata
       )
     rescue StandardError => e
@@ -145,13 +147,74 @@ module Langfuse
         trace_id: trace_id, observation_id: observation_id,
         metadata: @metadata, run_description: @description
       )
-      unless @dataset_run_id
-        @dataset_run_id = response&.dig("datasetRunId")
-        @dataset_id = item.dataset_id if @dataset_run_id
-      end
+      capture_dataset_run_identity(item, response)
       response
     rescue StandardError => e
       @logger.warn("Dataset run item linking failed: #{e.message}")
+      nil
+    end
+
+    # Do not expose a server run ID that differs from the identity already attached to observations.
+    def capture_dataset_run_identity(item, response)
+      candidate_id = response&.dig("datasetRunId")
+      return unless candidate_id
+      return if @resolved_experiment_id && @resolved_experiment_id != candidate_id
+
+      @dataset_run_id = candidate_id if @dataset_run_id.nil?
+      @dataset_id = item.dataset_id if @dataset_id.nil?
+    end
+
+    def prepare_experiment_context(item, span, trace_id)
+      response = link_to_dataset_run(item, trace_id, span.id) if item.is_a?(DatasetItemClient)
+      root_experiment_attributes(item).each do |key, value|
+        span.otel_span.set_attribute(key, value)
+      end
+      propagated_experiment_attributes(item, span.id, response)
+    end
+
+    def root_experiment_attributes(item)
+      ExperimentAttributes.root(
+        description: @description,
+        expected_output: item.expected_output,
+        mask: Langfuse.configuration.mask
+      )
+    end
+
+    def propagated_experiment_attributes(item, observation_id, response)
+      ExperimentAttributes.propagated(
+        experiment_id: resolved_experiment_id(response),
+        run_name: @run_name,
+        dataset_id: item_dataset_id(item),
+        item_id: item_id(item),
+        root_observation_id: observation_id,
+        experiment_metadata: @metadata,
+        item_metadata: item_metadata(item),
+        mask: Langfuse.configuration.mask
+      )
+    end
+
+    # A run keeps its first resolved identity even if later dataset links have a different result.
+    def resolved_experiment_id(response = nil)
+      @resolved_experiment_id ||= response&.dig("datasetRunId") || @fallback_experiment_id
+    end
+
+    def observation_metadata(item)
+      ExperimentAttributes.observation_metadata(
+        name: @name,
+        run_name: @run_name,
+        experiment_metadata: @metadata,
+        item_metadata: item_metadata(item),
+        dataset_id: item_dataset_id(item),
+        dataset_item_id: item.is_a?(DatasetItemClient) ? item.id : nil
+      )
+    end
+
+    def item_id(item)
+      item.is_a?(DatasetItemClient) ? item.id : ExperimentAttributes.generate_item_id(item.input)
+    end
+
+    def item_dataset_id(item)
+      item.dataset_id if item.is_a?(DatasetItemClient)
     end
 
     def flush_all

data/lib/langfuse/otel_attributes.rb

@@ -55,6 +55,17 @@ module Langfuse
     OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
     IS_APP_ROOT = "langfuse.internal.is_app_root"
 
+    # Experiment attributes
+    EXPERIMENT_ID = "langfuse.experiment.id"
+    EXPERIMENT_NAME = "langfuse.experiment.name"
+    EXPERIMENT_DESCRIPTION = "langfuse.experiment.description"
+    EXPERIMENT_METADATA = "langfuse.experiment.metadata"
+    EXPERIMENT_DATASET_ID = "langfuse.experiment.dataset.id"
+    EXPERIMENT_ITEM_ID = "langfuse.experiment.item.id"
+    EXPERIMENT_ITEM_EXPECTED_OUTPUT = "langfuse.experiment.item.expected_output"
+    EXPERIMENT_ITEM_METADATA = "langfuse.experiment.item.metadata"
+    EXPERIMENT_ITEM_ROOT_OBSERVATION_ID = "langfuse.experiment.item.root_observation_id"
+
     # Common attributes
     VERSION = "langfuse.version"
     RELEASE = "langfuse.release"

data/lib/langfuse/propagation.rb

@@ -30,6 +30,11 @@ module Langfuse
     ENVIRONMENT_VALUE_PATTERN = /\A(?!langfuse)[a-z0-9_-]+\z/
     private_constant :ENVIRONMENT_VALUE_PATTERN
 
+    EXPERIMENT_ATTRIBUTES_CONTEXT_KEY = OpenTelemetry::Context.create_key(
+      "#{BAGGAGE_PREFIX}experiment_attributes"
+    )
+    private_constant :EXPERIMENT_ATTRIBUTES_CONTEXT_KEY
+
     # Map of propagated attribute keys to span attribute keys
     SPAN_KEY_MAP = {
       "user_id" => OtelAttributes::TRACE_USER_ID,
@@ -186,7 +191,25 @@ module Langfuse
       end
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-      propagated_attributes
+      experiment_attributes = context.value(EXPERIMENT_ATTRIBUTES_CONTEXT_KEY) || {}
+      propagated_attributes.merge(experiment_attributes)
+    end
+
+    # Apply SDK-owned experiment attributes to the current span and future children.
+    #
+    # @param attributes [Hash<String, Object>] serialized OpenTelemetry experiment attributes
+    # @yield Block within which experiment attributes propagate
+    # @return [Object] the block result
+    # @api private
+    def self._with_experiment_attributes(attributes, &)
+      return yield if attributes.nil? || attributes.empty?
+
+      frozen_attributes = attributes.dup.freeze
+      current_span = OpenTelemetry::Trace.current_span
+      frozen_attributes.each { |key, value| current_span.set_attribute(key, value) } if current_span.recording?
+
+      context = OpenTelemetry::Context.current.set_value(EXPERIMENT_ATTRIBUTES_CONTEXT_KEY, frozen_attributes)
+      OpenTelemetry::Context.with_current(context, &)
     end
 
     # Merge metadata with existing context value

data/lib/langfuse/traced_execution.rb

@@ -15,9 +15,9 @@ module Langfuse
     # @param input [Object] input set on the root observation
     # @param metadata [Hash] metadata set on the root observation and trace
     # @param task [Proc] the callable to execute — receives the span
-    # @yield [span, trace_id] optional pre-task hook (e.g., dataset run linking)
+    # @param prepare_context [#call, nil] optional callable returning SDK-owned propagated attributes
     # @return [Array<(Object, String, String, StandardError | nil)>] output, trace_id, observation_id, error
-    def self.call(trace_name:, input:, task:, metadata: {})
+    def self.call(trace_name:, input:, task:, metadata: {}, prepare_context: nil)
       trace_id = nil
       observation_id = nil
       output = nil
@@ -26,9 +26,11 @@ module Langfuse
       Langfuse.observe(trace_name, input: input, metadata: metadata) do |span|
         trace_id = span.trace_id
         observation_id = span.id
-        Langfuse.propagate_attributes(trace_name: trace_name, metadata: metadata) do
-          yield(span, trace_id) if block_given?
-          output, task_error = execute_task(span, task)
+        experiment_attributes = prepare_context&.call(span, trace_id) || {}
+        Propagation._with_experiment_attributes(experiment_attributes) do
+          Langfuse.propagate_attributes(trace_name: trace_name, metadata: metadata) do
+            output, task_error = execute_task(span, task)
+          end
         end
       end
 

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -74,6 +74,7 @@ require_relative "langfuse/otel_setup"
 require_relative "langfuse/masking"
 require_relative "langfuse/masking_exporter"
 require_relative "langfuse/otel_attributes"
+require_relative "langfuse/experiment_attributes"
 require_relative "langfuse/propagation"
 require_relative "langfuse/app_root_tracking"
 require_relative "langfuse/span_processor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - SimplePractice
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -197,6 +197,7 @@ files:
 - lib/langfuse/dataset_item_client.rb
 - lib/langfuse/evaluation.rb
 - lib/langfuse/exit_hook.rb
+- lib/langfuse/experiment_attributes.rb
 - lib/langfuse/experiment_item.rb
 - lib/langfuse/experiment_result.rb
 - lib/langfuse/experiment_runner.rb