langfuse-rb 0.10.1 → 0.11.0

data/lib/langfuse/traced_execution.rb

@@ -12,32 +12,38 @@ module Langfuse
     # Execute a task proc within a traced observe block.
     #
     # @param trace_name [String] name for the observe span
-    # @param input [Object] input set on the trace
-    # @param metadata [Hash] metadata set on the trace
+    # @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)
     # @return [Array<(Object, String, String, StandardError | nil)>] output, trace_id, observation_id, error
     def self.call(trace_name:, input:, task:, metadata: {})
-      output = nil
       trace_id = nil
       observation_id = nil
+      output = nil
       task_error = nil
 
-      Langfuse.observe(trace_name) do |span|
+      Langfuse.observe(trace_name, input: input, metadata: metadata) do |span|
         trace_id = span.trace_id
         observation_id = span.id
-        span.update_trace(input: input, metadata: metadata)
-        yield(span, trace_id) if block_given?
-        begin
-          output = task.call(span)
-          span.update(output: output)
-        rescue StandardError => e
-          span.update(output: "Error: #{e.message}", level: "ERROR")
-          task_error = e
+        Langfuse.propagate_attributes(trace_name: trace_name, metadata: metadata) do
+          yield(span, trace_id) if block_given?
+          output, task_error = execute_task(span, task)
         end
       end
 
       [output, trace_id, observation_id, task_error]
     end
+
+    # @api private
+    def self.execute_task(span, task)
+      output = task.call(span)
+      span.update(output: output)
+      [output, nil]
+    rescue StandardError => e
+      span.update(output: "Error: #{e.message}", level: "ERROR")
+      [nil, e]
+    end
+    private_class_method :execute_task
   end
 end

data/lib/langfuse/types.rb

@@ -56,12 +56,17 @@ module Langfuse
     # - `numeric`: Numeric values (Integer, Float, BigDecimal)
     # - `boolean`: Boolean values (true/false or 0/1)
     # - `categorical`: String values for categorical scores
+    # - `text`: Free-form String values (1 to 500 characters)
+    # - `correction`: Corrected output String attached to a trace or observation
+    #   (conventionally named "output")
     #
     # @return [Hash<Symbol, String>] Hash mapping symbol keys to API string values
     SCORE_DATA_TYPES = {
       numeric: "NUMERIC",
       boolean: "BOOLEAN",
-      categorical: "CATEGORICAL"
+      categorical: "CATEGORICAL",
+      text: "TEXT",
+      correction: "CORRECTION"
     }.freeze
 
     # Valid score data type symbols
@@ -69,6 +74,15 @@ module Langfuse
     # @return [Array<Symbol>] Array of valid data type symbols
     VALID_SCORE_DATA_TYPES = SCORE_DATA_TYPES.keys.freeze
 
+    # Score data types accepted by experiment evaluations
+    #
+    # Experiment evaluations represent metrics, so this set is intentionally
+    # narrower than {SCORE_DATA_TYPES}: text notes and corrected outputs are
+    # general scores, not experiment metrics (matching langfuse-python).
+    #
+    # @return [Array<Symbol>] Array of experiment-safe data type symbols
+    EXPERIMENT_SCORE_DATA_TYPES = %i[numeric boolean categorical].freeze
+
     # Attributes for Langfuse span observations
     #
     # Spans are used to track operations, functions, or logical units of work.

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -29,6 +29,23 @@ module Langfuse
   # Raised when a Langfuse API request fails
   class ApiError < Error; end
 
+  # Describes whether a failed ingestion batch is safe to retry.
+  #
+  # @api private
+  class BatchDeliveryError < ApiError
+    # @param message [String] Delivery failure description
+    # @param retryable [Boolean] Whether the complete batch can be retried
+    def initialize(message, retryable:)
+      @retryable = retryable
+      super(message)
+    end
+
+    # @return [Boolean] whether the complete batch can be retried
+    def retryable?
+      @retryable
+    end
+  end
+
   # Raised when a requested resource is not found (HTTP 404)
   class NotFoundError < ApiError; end
 
@@ -40,6 +57,8 @@ module Langfuse
 end
 
 require_relative "langfuse/config"
+require_relative "langfuse/fork_safety"
+require_relative "langfuse/exit_hook"
 require_relative "langfuse/cache_constants"
 require_relative "langfuse/prompt_cache"
 require_relative "langfuse/prompt_fetch_result"
@@ -50,15 +69,20 @@ require_relative "langfuse/prompt_cache_events"
 require_relative "langfuse/api_client"
 require_relative "langfuse/span_filter"
 require_relative "langfuse/sampling"
+require_relative "langfuse/otel_span_masking"
 require_relative "langfuse/otel_setup"
 require_relative "langfuse/masking"
+require_relative "langfuse/masking_exporter"
 require_relative "langfuse/otel_attributes"
 require_relative "langfuse/propagation"
+require_relative "langfuse/app_root_tracking"
 require_relative "langfuse/span_processor"
 require_relative "langfuse/observations"
 require_relative "langfuse/trace_id"
+require_relative "langfuse/score_value"
 require_relative "langfuse/score_client"
 require_relative "langfuse/prompt_renderer"
+require_relative "langfuse/prompt_variables"
 require_relative "langfuse/text_prompt_client"
 require_relative "langfuse/chat_prompt_client"
 require_relative "langfuse/timestamp_parser"
@@ -76,14 +100,21 @@ require_relative "langfuse/client"
 module Langfuse
   # rubocop:disable Metrics/ClassLength
   class << self
+    # Set the global configuration object and start its process-exit lifecycle.
+    #
     # @param configuration [Config] the global configuration object
-    attr_writer :configuration
+    # @return [Config] the assigned configuration
+    def configuration=(configuration)
+      reset!
+      ExitHook.enable
+      @configuration = configuration
+    end
 
     # Returns the global configuration object
     #
     # @return [Config] the global configuration
     def configuration
-      @configuration ||= Config.new
+      @configuration ||= Config.new.tap { ExitHook.enable }
     end
 
     # Configure Langfuse globally
@@ -108,10 +139,27 @@ module Langfuse
       @client ||= Client.new(configuration)
     end
 
+    # Check whether the local configuration can construct a client.
+    #
+    # This method does not access the network or validate credentials.
+    #
+    # @return [Boolean] true when the local configuration is valid
+    def configured?
+      config = configuration
+      return config.valid? if config.telemetry_enabled?
+
+      config.validate_telemetry_disabled!
+      true
+    rescue ConfigurationError
+      # Reading `configuration` builds it from the environment, which can fail
+      # on its own before there is anything to validate.
+      false
+    end
+
     # Return Langfuse's internal tracer provider for explicit global OpenTelemetry installation.
     #
-    # @return [OpenTelemetry::SDK::Trace::TracerProvider]
-    # @raise [ConfigurationError] if tracing is not fully configured
+    # @return [OpenTelemetry::SDK::Trace::TracerProvider, OpenTelemetry::Trace::TracerProvider]
+    # @raise [ConfigurationError] if tracing configuration is invalid
     #
     # @example
     #   Langfuse.configure do |config|
@@ -121,27 +169,27 @@ module Langfuse
     #
     #   OpenTelemetry.tracer_provider = Langfuse.tracer_provider
     def tracer_provider
-      unless tracing_config_ready?
-        raise ConfigurationError,
-              "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
-      end
+      return noop_tracer_provider unless configuration.trace_export_enabled?
 
       OtelSetup.setup(configuration) unless OtelSetup.initialized?
       OtelSetup.tracer_provider
+    rescue ConfigurationError => e
+      raise ConfigurationError, tracing_disabled_message(e.message)
     end
 
     # Shutdown Langfuse and flush any pending traces and scores
     #
-    # Call this when shutting down your application to ensure
-    # all traces and scores are sent to Langfuse.
+    # Normal process exit calls this automatically. Use it directly when the
+    # application needs an earlier, explicit shutdown boundary.
     #
     # @param timeout [Integer] Timeout in seconds
     # @return [void]
     #
-    # @example In a Rails initializer or shutdown hook
-    #   at_exit { Langfuse.shutdown }
+    # @example Explicit early shutdown
+    #   Langfuse.shutdown
     #
     def shutdown(timeout: 30)
+      ExitHook.disable
       client.shutdown if @client
       OtelSetup.shutdown(timeout: timeout)
     end
@@ -170,9 +218,13 @@ module Langfuse
     # @param metadata [Hash<String, String>, nil] Additional metadata (all values ≤200 characters)
     # @param version [String, nil] Version identifier (≤200 characters)
     # @param tags [Array<String>, nil] List of tags (each ≤200 characters)
+    # @param trace_name [String, nil] Trace name (≤200 characters)
+    # @param release [String, nil] Release identifier (≤200 characters)
+    # @param environment [String, nil] Lowercase environment identifier (≤40 characters)
     # @param as_baggage [Boolean] If true, propagates via OpenTelemetry baggage for cross-service propagation
     # @yield Block within which attributes are propagated
     # @return [Object] The result of the block
+    # @raise [ArgumentError] if no block is given
     #
     # @example Basic usage
     #   Langfuse.propagate_attributes(user_id: "user_123", session_id: "session_abc") do
@@ -200,31 +252,36 @@ module Langfuse
     #   ) do
     #     # Attributes propagate via HTTP headers
     #   end
+    # rubocop:disable Metrics/ParameterLists
     def propagate_attributes(user_id: nil, session_id: nil, metadata: nil, version: nil, tags: nil,
-                             as_baggage: false, &)
+                             trace_name: nil, release: nil, environment: nil, as_baggage: false, &)
       Propagation.propagate_attributes(
         user_id: user_id,
         session_id: session_id,
         metadata: metadata,
         version: version,
         tags: tags,
+        trace_name: trace_name,
+        release: release,
+        environment: environment,
         as_baggage: as_baggage,
         &
       )
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a score event and queue it for batching
     #
     # @param name [String] Score name (required)
     # @param value [Numeric, Integer, String] Score value (type depends on data_type)
-    # @param id [String, nil] Score ID
+    # @param id [String, nil] Score ID; use a stable value as an idempotency key
     # @param trace_id [String, nil] Trace ID to associate with the score
     # @param session_id [String, nil] Session ID to associate with the score
     # @param observation_id [String, nil] Observation ID to associate with the score
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
-    # @param environment [String, nil] Optional environment
-    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @param environment [String, nil] Optional per-score environment override
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
     # @param config_id [String, nil] Optional score config ID
     # @return [void]
@@ -258,6 +315,47 @@ module Langfuse
     end
     # rubocop:enable Metrics/ParameterLists
 
+    # Create a score immediately through the Scores API. See {ScoreClient#create!}.
+    #
+    # @param name [String] Score name (required)
+    # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param id [String, nil] Score ID; use a stable value as an idempotency key
+    # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param session_id [String, nil] Session ID to associate with the score
+    # @param observation_id [String, nil] Observation ID to associate with the score
+    # @param comment [String, nil] Optional comment
+    # @param metadata [Hash, nil] Optional metadata hash
+    # @param environment [String, nil] Optional per-score environment override
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
+    # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
+    # @param config_id [String, nil] Optional score config ID
+    # @return [String, nil] ID of the created score, or nil when telemetry is disabled
+    # @raise [ArgumentError] if validation fails
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] if the API request fails
+    #
+    # @example Create a score with an idempotency key
+    #   Langfuse.create_score!(id: "feedback-abc123", name: "quality", value: 0.85, trace_id: "abc123")
+    # rubocop:disable Metrics/ParameterLists
+    def create_score!(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)
+      client.create_score!(
+        name: name,
+        value: 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,
+        dataset_run_id: dataset_run_id,
+        config_id: config_id
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
+
     # Create a score for the currently active observation (from OTel span)
     #
     # Extracts observation_id and trace_id from the active OpenTelemetry span.
@@ -266,7 +364,7 @@ module Langfuse
     # @param value [Numeric, Integer, String] Score value
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
-    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @return [void]
     # @raise [ArgumentError] if no active span or validation fails
     #
@@ -292,7 +390,7 @@ module Langfuse
     # @param value [Numeric, Integer, String] Score value
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
-    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @return [void]
     # @raise [ArgumentError] if no active span or validation fails
     #
@@ -344,18 +442,21 @@ module Langfuse
     #
     # @return [void]
     def reset!
+      ExitHook.disable
       client.shutdown if @client
       OtelSetup.shutdown(timeout: 5) if OtelSetup.initialized?
       @configuration = nil
       @client = nil
       @noop_tracer = nil
-      @tracing_disabled_warning_emitted = false
+      @noop_tracer_provider = nil
+      @emitted_warnings = nil
     rescue StandardError
       # Ignore shutdown errors during reset (e.g., in tests)
       @configuration = nil
       @client = nil
       @noop_tracer = nil
-      @tracing_disabled_warning_emitted = false
+      @noop_tracer_provider = nil
+      @emitted_warnings = nil
     end
 
     # Creates a new observation (root or child)
@@ -507,9 +608,8 @@ module Langfuse
     #
     # @return [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
     def otel_tracer
-      return tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION) if setup_tracing_if_ready
+      return tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION) if ensure_tracing_started
 
-      warn_tracing_disabled_once
       noop_tracer
     end
 
@@ -547,45 +647,57 @@ module Langfuse
       observation_class.new(otel_span, otel_tracer, attributes: attributes)
     end
 
-    # rubocop:disable Naming/PredicateMethod
-    def setup_tracing_if_ready
+    def ensure_tracing_started
+      return false unless configuration.trace_export_enabled?
       return true if OtelSetup.initialized?
-      return false unless tracing_config_ready?
 
       OtelSetup.setup(configuration)
       true
+    rescue ConfigurationError => e
+      warn_once(:tracing, tracing_disabled_message(e.message))
+      false
     end
-    # rubocop:enable Naming/PredicateMethod
 
-    def tracing_config_ready?
-      configured?(configuration.public_key) &&
-        configured?(configuration.secret_key) &&
-        configured?(configuration.base_url)
+    # A dropped span is otherwise silent, so warn the first time it happens
+    # without flooding logs on every subsequent call.
+    def warn_once(key, message)
+      warning_mutex.synchronize do
+        return if emitted_warnings[key]
+
+        warning_logger.warn(message)
+        emitted_warnings[key] = true
+      end
     end
 
-    def configured?(value)
-      !value.nil? && !value.empty?
+    def emitted_warnings
+      @emitted_warnings ||= {}
     end
 
-    def warn_tracing_disabled_once
-      return if @tracing_disabled_warning_emitted
+    # The warning fires precisely when configuration is known-bad, which
+    # includes the case where building it raises. Reading `configuration` here
+    # would re-raise and escape the rescue that called us, so use the memoized
+    # object only if it already exists.
+    def warning_logger
+      configured_logger = @configuration&.logger
+      return configured_logger if configured_logger.respond_to?(:warn)
 
-      tracing_warning_mutex.synchronize do
-        return if @tracing_disabled_warning_emitted
+      @warning_logger ||= Logger.new($stdout, level: Logger::WARN)
+    end
 
-        configuration.logger.warn(
-          "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
-        )
-        @tracing_disabled_warning_emitted = true
-      end
+    def tracing_disabled_message(detail)
+      "Langfuse tracing is disabled: #{detail}"
     end
 
-    def tracing_warning_mutex
-      @tracing_warning_mutex ||= Mutex.new
+    def warning_mutex
+      @warning_mutex ||= Mutex.new
     end
 
     def noop_tracer
-      @noop_tracer ||= OpenTelemetry::Trace::TracerProvider.new.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION)
+      @noop_tracer ||= noop_tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION)
+    end
+
+    def noop_tracer_provider
+      @noop_tracer_provider ||= OpenTelemetry::Trace::TracerProvider.new
     end
   end
   # rubocop:enable Metrics/ClassLength

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - SimplePractice
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -160,6 +161,7 @@ files:
 - README.md
 - lib/langfuse.rb
 - lib/langfuse/api_client.rb
+- lib/langfuse/app_root_tracking.rb
 - lib/langfuse/cache_constants.rb
 - lib/langfuse/cache_warmer.rb
 - lib/langfuse/chat_prompt_client.rb
@@ -168,28 +170,40 @@ files:
 - lib/langfuse/dataset_client.rb
 - lib/langfuse/dataset_item_client.rb
 - lib/langfuse/evaluation.rb
+- lib/langfuse/exit_hook.rb
 - lib/langfuse/experiment_item.rb
 - lib/langfuse/experiment_result.rb
 - lib/langfuse/experiment_runner.rb
+- lib/langfuse/fork_safety.rb
 - lib/langfuse/item_result.rb
 - lib/langfuse/masking.rb
+- lib/langfuse/masking_exporter.rb
 - lib/langfuse/observations.rb
 - lib/langfuse/otel_attributes.rb
 - lib/langfuse/otel_setup.rb
+- lib/langfuse/otel_span_batch.rb
+- lib/langfuse/otel_span_masking.rb
+- lib/langfuse/otel_span_patch_applier.rb
+- lib/langfuse/pending_score_queue.rb
 - lib/langfuse/prompt_cache.rb
 - lib/langfuse/prompt_cache_coordinator.rb
 - lib/langfuse/prompt_cache_events.rb
 - lib/langfuse/prompt_fetch_result.rb
 - lib/langfuse/prompt_renderer.rb
+- lib/langfuse/prompt_variables.rb
 - lib/langfuse/propagation.rb
 - lib/langfuse/rails_cache_adapter.rb
+- lib/langfuse/read_api.rb
+- lib/langfuse/resilient_metrics_reporter.rb
 - lib/langfuse/sampling.rb
 - lib/langfuse/score_client.rb
+- lib/langfuse/score_value.rb
 - lib/langfuse/span_filter.rb
 - lib/langfuse/span_processor.rb
 - lib/langfuse/stale_while_revalidate.rb
 - lib/langfuse/text_prompt_client.rb
 - lib/langfuse/timestamp_parser.rb
+- lib/langfuse/trace_export_guard.rb
 - lib/langfuse/trace_id.rb
 - lib/langfuse/traced_execution.rb
 - lib/langfuse/types.rb
@@ -202,6 +216,7 @@ metadata:
   source_code_uri: https://github.com/simplepractice/langfuse-rb
   changelog_uri: https://github.com/simplepractice/langfuse-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -216,7 +231,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []