langfuse-rb 0.10.1 → 0.12.0

data/lib/langfuse/prompt_variables.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "mustache"
+
+module Langfuse
+  # Extracts referenced variables from parsed Mustache templates.
+  #
+  # @api private
+  class PromptVariables
+    TAG_TYPES = %i[etag utag].freeze
+    SECTION_TYPES = %i[section inverted_section].freeze
+
+    class << self
+      # @api private
+      def extract(template)
+        tokens = Mustache::Template.new(template).tokens
+        collect(tokens, []).reject(&:empty?).uniq
+      end
+
+      private
+
+      def collect(tokens, scope)
+        tokens.each_with_object([]) do |token, variables|
+          next unless token.is_a?(Array)
+
+          variables.concat(token.first == :mustache ? from_tag(token, scope) : collect(token, scope))
+        end
+      end
+
+      def from_tag(token, scope)
+        return variable_path(token, scope) if TAG_TYPES.include?(token[1])
+        return section_paths(token, scope) if SECTION_TYPES.include?(token[1])
+
+        []
+      end
+
+      def variable_path(token, scope)
+        path = scoped_path(token, scope)
+        path.empty? ? [] : [path.join(".")]
+      end
+
+      def section_paths(token, scope)
+        section_path = scoped_path(token, scope)
+        body_scope = token[1] == :section ? section_path : scope
+        [section_path.join("."), *collect(token[4], body_scope)]
+      end
+
+      def scoped_path(token, scope)
+        segments = token.dig(2, 2)
+        segments == ["."] ? scope : scope + segments
+      end
+    end
+  end
+end

data/lib/langfuse/propagation.rb

@@ -6,7 +6,7 @@ module Langfuse
   # Attribute propagation utilities for Langfuse OpenTelemetry integration.
   #
   # This module provides the `propagate_attributes` method for setting trace-level
-  # attributes (user_id, session_id, metadata) that automatically propagate to all child spans
+  # attributes that automatically propagate to all child spans
   # within the context.
   #
   # @example Basic usage
@@ -21,29 +21,31 @@ module Langfuse
   #
   # rubocop:disable Metrics/ModuleLength
   module Propagation
+    # Baggage key prefix for cross-service propagation
+    BAGGAGE_PREFIX = "langfuse_"
+
+    # Baggage key that records which Langfuse trace already owns the application root
+    LANGFUSE_TRACE_ID_BAGGAGE_KEY = "#{BAGGAGE_PREFIX}trace_id".freeze
+
+    ENVIRONMENT_VALUE_PATTERN = /\A(?!langfuse)[a-z0-9_-]+\z/
+    private_constant :ENVIRONMENT_VALUE_PATTERN
+
     # Map of propagated attribute keys to span attribute keys
     SPAN_KEY_MAP = {
       "user_id" => OtelAttributes::TRACE_USER_ID,
       "session_id" => OtelAttributes::TRACE_SESSION_ID,
       "version" => OtelAttributes::VERSION,
       "tags" => OtelAttributes::TRACE_TAGS,
-      "metadata" => OtelAttributes::TRACE_METADATA
+      "metadata" => OtelAttributes::TRACE_METADATA,
+      "trace_name" => OtelAttributes::TRACE_NAME,
+      "release" => OtelAttributes::RELEASE,
+      "environment" => OtelAttributes::ENVIRONMENT
     }.freeze
 
     # OpenTelemetry context keys for propagated attributes
-    CONTEXT_KEYS = {
-      "user_id" => OpenTelemetry::Context.create_key("langfuse_user_id"),
-      "session_id" => OpenTelemetry::Context.create_key("langfuse_session_id"),
-      "metadata" => OpenTelemetry::Context.create_key("langfuse_metadata"),
-      "version" => OpenTelemetry::Context.create_key("langfuse_version"),
-      "tags" => OpenTelemetry::Context.create_key("langfuse_tags")
-    }.freeze
-
-    # List of propagated attribute keys (derived from CONTEXT_KEYS)
-    PROPAGATED_ATTRIBUTES = CONTEXT_KEYS.keys.freeze
-
-    # Baggage key prefix for cross-service propagation
-    BAGGAGE_PREFIX = "langfuse_"
+    CONTEXT_KEYS = SPAN_KEY_MAP.keys.to_h do |key|
+      [key, OpenTelemetry::Context.create_key("#{BAGGAGE_PREFIX}#{key}")]
+    end.freeze
 
     # Propagate trace-level attributes to all spans created within this context.
     #
@@ -57,6 +59,9 @@ 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
@@ -76,32 +81,29 @@ module Langfuse
     #     # All spans inherit these attributes
     #   end
     #
+    # rubocop:disable Metrics/ParameterLists
     def self.propagate_attributes(user_id: nil, session_id: nil, metadata: nil, version: nil, tags: nil,
-                                  as_baggage: false, &block)
+                                  trace_name: nil, release: nil, environment: nil, as_baggage: false, &block)
       raise ArgumentError, "Block required" unless block
 
-      _propagate_attributes(
-        user_id: user_id,
-        session_id: session_id,
-        metadata: metadata,
-        version: version,
-        tags: tags,
-        as_baggage: as_baggage,
-        &block
-      )
+      attributes = {
+        "user_id" => user_id, "session_id" => session_id, "metadata" => metadata,
+        "version" => version, "tags" => tags, "trace_name" => trace_name,
+        "release" => release, "environment" => environment
+      }
+      _propagate_attributes(attributes, as_baggage: as_baggage, &block)
     end
 
     # Internal implementation of propagate_attributes
     #
+    # @param attributes [Hash<String, Object>] Propagated attribute values
+    # @param as_baggage [Boolean] Whether to add the values to OpenTelemetry baggage
     # @api private
-    def self._propagate_attributes(user_id: nil, session_id: nil, metadata: nil, version: nil, tags: nil,
-                                   as_baggage: false, &)
+    def self._propagate_attributes(attributes, as_baggage:, &)
       current_context = OpenTelemetry::Context.current
       current_span = OpenTelemetry::Trace.current_span
 
-      # Process each propagated attribute using PROPAGATED_ATTRIBUTES constant
-      PROPAGATED_ATTRIBUTES.each do |key|
-        value = binding.local_variable_get(key.to_sym)
+      attributes.each do |key, value|
         next if value.nil?
         next if key == "tags" && value.empty?
 
@@ -120,6 +122,7 @@ module Langfuse
       # Execute block in new context
       OpenTelemetry::Context.with_current(current_context, &)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Validate an attribute value based on its type
     #
@@ -140,6 +143,8 @@ module Langfuse
           validated_metadata[k.to_s] = v.to_s if _validate_string_value(v, "metadata.#{k}")
         end
         validated_metadata.any? ? validated_metadata : nil
+      when "environment"
+        _validate_environment_value(value)
       else
         _validate_propagated_value(value, key)
       end
@@ -157,7 +162,7 @@ module Langfuse
       propagated_attributes = _extract_baggage_attributes(context)
 
       # Handle OTEL context values
-      PROPAGATED_ATTRIBUTES.each do |key|
+      SPAN_KEY_MAP.each_key do |key|
         context_key = _get_propagated_context_key(key)
         value = context.value(context_key)
 
@@ -165,7 +170,10 @@ module Langfuse
 
         span_key = _get_propagated_span_key(key)
 
-        if key == "metadata" && value.is_a?(Hash)
+        if key == "environment"
+          validated_environment = _validate_environment_value(value)
+          propagated_attributes[span_key] = validated_environment if validated_environment
+        elsif key == "metadata" && value.is_a?(Hash)
           value.each do |k, v|
             metadata_key = "#{OtelAttributes::TRACE_METADATA}.#{k}"
             propagated_attributes[metadata_key] = v.to_s
@@ -318,6 +326,29 @@ module Langfuse
     end
     # rubocop:enable Naming/PredicateMethod
 
+    # Validate a propagated environment value against the cross-SDK contract.
+    #
+    # @param value [Object] Environment value to validate
+    # @return [String, nil] Validated environment or nil
+    # @api private
+    def self._validate_environment_value(value)
+      return _drop_environment("value is not a string") unless value.is_a?(String)
+      return _drop_environment("value is over 40 characters (#{value.length} chars)") if value.length > 40
+
+      return value if ENVIRONMENT_VALUE_PATTERN.match?(value)
+
+      _drop_environment(
+        "must use lowercase letters, numbers, hyphens, or underscores and must not start with 'langfuse'"
+      )
+    end
+
+    def self._drop_environment(reason)
+      Langfuse.configuration.logger.warn(
+        "Langfuse: Propagated attribute 'environment' #{reason}. Dropping value."
+      )
+      nil
+    end
+
     # Get context key for a propagated attribute
     #
     # @param key [String] Attribute key (user_id, session_id, etc.)
@@ -378,6 +409,40 @@ module Langfuse
       defined?(OpenTelemetry::Baggage)
     end
 
+    # Get the Langfuse trace claim from OpenTelemetry baggage.
+    #
+    # @param context [OpenTelemetry::Context] Context to inspect
+    # @return [String, nil] Lowercase trace ID or nil
+    # @api private
+    def self._get_langfuse_trace_id_from_baggage(context)
+      return nil unless baggage_available?
+
+      OpenTelemetry::Baggage.values(context: context)[LANGFUSE_TRACE_ID_BAGGAGE_KEY]&.to_s&.downcase
+    rescue StandardError => e
+      Langfuse.configuration.logger.debug("Langfuse: Trace baggage read failed: #{e.message}")
+      nil
+    end
+
+    # Set the Langfuse trace claim in OpenTelemetry baggage.
+    #
+    # @param trace_id [String] Lowercase hexadecimal trace ID
+    # @param context [OpenTelemetry::Context] Context to extend
+    # @return [OpenTelemetry::Context] Context with the trace claim
+    # @api private
+    def self._set_langfuse_trace_id_in_baggage(trace_id, context:)
+      return context unless baggage_available?
+
+      normalized_trace_id = trace_id.downcase
+      return context if _get_langfuse_trace_id_from_baggage(context) == normalized_trace_id
+
+      OpenTelemetry::Baggage.set_value(
+        LANGFUSE_TRACE_ID_BAGGAGE_KEY, normalized_trace_id, context: context
+      )
+    rescue StandardError => e
+      Langfuse.configuration.logger.debug("Langfuse: Trace baggage write failed: #{e.message}")
+      context
+    end
+
     # Extract propagated attributes from baggage
     #
     # @param context [OpenTelemetry::Context] The context to read baggage from
@@ -399,7 +464,7 @@ module Langfuse
 
         attributes[span_key] = _parse_baggage_value(span_key, baggage_value)
       end
-      attributes
+      attributes.compact
     rescue StandardError => e
       Langfuse.configuration.logger.debug("Langfuse: Baggage extraction failed: #{e.message}")
       {}
@@ -413,7 +478,9 @@ module Langfuse
     #
     # @api private
     def self._parse_baggage_value(span_key, baggage_value)
-      if span_key == OtelAttributes::TRACE_TAGS && baggage_value.is_a?(String)
+      if span_key == OtelAttributes::ENVIRONMENT
+        _validate_environment_value(baggage_value)
+      elsif span_key == OtelAttributes::TRACE_TAGS && baggage_value.is_a?(String)
         baggage_value.split(",")
       else
         baggage_value.to_s

data/lib/langfuse/rails_cache_adapter.rb

@@ -2,6 +2,7 @@
 
 require_relative "prompt_cache"
 require_relative "stale_while_revalidate"
+require_relative "fork_safety"
 
 module Langfuse
   # Rails.cache adapter for distributed caching with Redis
@@ -20,6 +21,14 @@ module Langfuse
 
     GENERATION_MEMO_TTL_SECONDS = 1.0
 
+    # Check whether Rails has a configured cache store.
+    #
+    # @api private
+    # @return [Boolean]
+    def self.available?
+      !!(defined?(Rails) && Rails.respond_to?(:cache) && !Rails.cache.nil?)
+    end
+
     # @return [Integer] Time-to-live in seconds
     attr_reader :ttl
 
@@ -61,6 +70,7 @@ module Langfuse
       @generation_memo = {}
       @generation_memo_mutex = Mutex.new
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
+      ForkSafety.register(self)
     end
 
     # Get a value from the cache
@@ -249,6 +259,12 @@ module Langfuse
 
     private
 
+    # Replace inherited synchronization and worker state in the child process.
+    def reset_after_fork
+      @generation_memo = {}
+      @generation_memo_mutex = Mutex.new
+    end
+
     # Implementation of StaleWhileRevalidate abstract methods
 
     # Get value from cache (SWR interface)
@@ -416,7 +432,7 @@ module Langfuse
     # @raise [ConfigurationError] if Rails.cache is not available
     # @return [void]
     def validate_rails_cache!
-      return if defined?(Rails) && Rails.respond_to?(:cache)
+      return if self.class.available?
 
       raise ConfigurationError,
             "Rails.cache is not available. Rails cache backend requires Rails with a configured cache store."

data/lib/langfuse/read_api.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Langfuse
+  # Read endpoints for the current Langfuse query surface.
+  #
+  # Implements v2 observation and metrics reads plus the v3 scores read.
+  # Mixed into {ApiClient}, whose private +request+ helper provides HTTP
+  # transport and error handling.
+  #
+  # @note The v2 observations and metrics endpoints require Langfuse v4. There
+  #   is no fallback to legacy endpoints because their response and pagination
+  #   semantics differ.
+  module ReadApi
+    # Ruby keyword argument -> camelCase query parameter mappings. Start-time
+    # bounds are handled separately because they need ISO 8601 formatting.
+    OBSERVATION_QUERY_PARAMS = {
+      trace_id: :traceId, fields: :fields, cursor: :cursor, limit: :limit,
+      filter: :filter, name: :name, user_id: :userId, type: :type,
+      level: :level, parent_observation_id: :parentObservationId,
+      is_root_observation: :isRootObservation, environment: :environment,
+      session_id: :sessionId, version: :version,
+      expand_metadata: :expandMetadata
+    }.freeze
+    private_constant :OBSERVATION_QUERY_PARAMS
+
+    SCORE_QUERY_PARAMS = {
+      limit: :limit, cursor: :cursor, fields: :fields, id: :id, name: :name,
+      source: :source, data_type: :dataType, environment: :environment,
+      config_id: :configId, queue_id: :queueId, author_user_id: :authorUserId,
+      value: :value, value_min: :valueMin, value_max: :valueMax,
+      trace_id: :traceId, session_id: :sessionId,
+      observation_id: :observationId, experiment_id: :experimentId
+    }.freeze
+    private_constant :SCORE_QUERY_PARAMS
+
+    # List observations with cursor-based pagination and field selection
+    #
+    # Delegates to +GET /api/public/v2/observations+ on Langfuse v4.
+    # Returns observation rows, not reconstructed trace objects. The full
+    # response envelope is preserved: +"data"+ holds the observation rows and
+    # +"meta"+ holds the pagination cursor for the next page.
+    #
+    # Broad reads must be bounded: unless +trace_id+ narrows the query, both
+    # +from_start_time+ and +to_start_time+ are required.
+    #
+    # @param from_start_time [Time, String, nil] Inclusive lower bound on observation start time
+    # @param to_start_time [Time, String, nil] Exclusive upper bound on observation start time
+    # @param trace_id [String, nil] Filter by trace ID
+    # @param fields [String, nil] Comma-separated field groups to include
+    #   (core, basic, time, io, metadata, model, usage, prompt, metrics, trace_context)
+    # @param cursor [String, nil] Cursor from the previous response's meta for the next page
+    # @param limit [Integer, nil] Items per page (max 1000, default 50)
+    # @param filter [String, nil] JSON string with structured filter conditions;
+    #   takes precedence over individual query parameter filters
+    # @param name [String, nil] Filter by observation name
+    # @param user_id [String, nil] Filter by user ID
+    # @param type [String, nil] Filter by observation type (e.g. "GENERATION", "SPAN")
+    # @param level [String, nil] Filter by level (e.g. "DEFAULT", "ERROR")
+    # @param parent_observation_id [String, nil] Filter by parent observation ID
+    # @param is_root_observation [Boolean, nil] Filter by logical root status
+    # @param environment [Array<String>, nil] Filter by one or more environments
+    # @param session_id [String, nil] Filter by session ID
+    # @param version [String, nil] Filter by observation version
+    # @param expand_metadata [String, nil] Comma-separated metadata keys to return non-truncated
+    # @return [Hash] Full response hash with "data" rows and "meta" cursor info
+    # @raise [ArgumentError] if the read is unbounded (no trace_id and missing start-time bounds)
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors (including deployments without Langfuse v4)
+    #
+    # @example Bounded read of recent generations
+    #   page = api_client.list_observations(
+    #     from_start_time: Time.now - 3600,
+    #     to_start_time: Time.now,
+    #     type: "GENERATION",
+    #     fields: "core,basic,usage"
+    #   )
+    #   page["data"].each { |obs| puts obs["id"] }
+    #   next_cursor = page.dig("meta", "cursor")
+    # rubocop:disable Metrics/ParameterLists
+    def list_observations(from_start_time: nil, to_start_time: nil, trace_id: nil,
+                          fields: nil, cursor: nil, limit: nil, filter: nil,
+                          name: nil, user_id: nil, type: nil, level: nil,
+                          parent_observation_id: nil, is_root_observation: nil,
+                          environment: nil, session_id: nil, version: nil,
+                          expand_metadata: nil)
+      validate_bounded_observation_read!(trace_id, from_start_time, to_start_time)
+      params = build_observations_params(
+        from_start_time: from_start_time, to_start_time: to_start_time,
+        trace_id: trace_id, fields: fields, cursor: cursor, limit: limit,
+        filter: filter, name: name, user_id: user_id, type: type, level: level,
+        parent_observation_id: parent_observation_id, environment: environment,
+        is_root_observation: is_root_observation, session_id: session_id,
+        version: version, expand_metadata: expand_metadata
+      )
+      request(
+        :get,
+        "/api/public/v2/observations",
+        params: params,
+        params_encoder: Faraday::FlatParamsEncoder
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Query aggregate metrics on Langfuse v4
+    #
+    # Delegates to +GET /api/public/v2/metrics+. Supports the +observations+,
+    # +scores-numeric+, +scores-categorical+, and +scores-boolean+ views.
+    #
+    # @param query [Hash, String] Metrics query. A Hash is JSON-encoded into
+    #   the endpoint's +query+ parameter; a pre-encoded JSON String is passed
+    #   through unchanged.
+    # @return [Hash] The parsed metrics response
+    # @raise [ArgumentError] if query is neither a Hash nor a String
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors (including deployments without Langfuse v4)
+    #
+    # @example Count observations by name
+    #   api_client.query_metrics(query: {
+    #     view: "observations",
+    #     metrics: [{ measure: "count", aggregation: "count" }],
+    #     dimensions: [{ field: "name" }],
+    #     fromTimestamp: "2026-07-01T00:00:00Z",
+    #     toTimestamp: "2026-07-02T00:00:00Z"
+    #   })
+    def query_metrics(query:)
+      request(:get, "/api/public/v2/metrics", params: { query: encode_metrics_query(query) })
+    end
+
+    # List scores with polymorphic values (v3)
+    #
+    # Delegates to +GET /api/public/v3/scores+. The full response envelope is
+    # preserved: +"data"+ holds score rows and +"meta"+ holds the pagination
+    # cursor. Score values are polymorphic by +dataType+: NUMERIC scores return
+    # numbers, BOOLEAN scores return booleans, and CATEGORICAL, TEXT, and
+    # CORRECTION scores return strings.
+    #
+    # @param limit [Integer, nil] Items per page (max 100, default 50)
+    # @param cursor [String, nil] Cursor from the previous response's meta for the next page
+    # @param fields [String, nil] Comma-separated field groups in addition to core
+    #   (details, subject, annotation)
+    # @param id [String, nil] Comma-separated score IDs to filter by
+    # @param name [String, nil] Comma-separated score names to filter by
+    # @param source [String, nil] Comma-separated score sources (e.g. API, ANNOTATION, EVAL)
+    # @param data_type [String, nil] Comma-separated data types
+    #   (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, CORRECTION)
+    # @param environment [String, nil] Comma-separated environments to filter by
+    # @param config_id [String, nil] Comma-separated score config IDs
+    # @param queue_id [String, nil] Comma-separated annotation queue IDs
+    # @param author_user_id [String, nil] Comma-separated author user IDs
+    # @param value [String, nil] Comma-separated exact values (requires a single
+    #   NUMERIC, BOOLEAN, or CATEGORICAL data_type)
+    # @param value_min [Numeric, nil] Inclusive lower bound (requires data_type: "NUMERIC")
+    # @param value_max [Numeric, nil] Inclusive upper bound (requires data_type: "NUMERIC")
+    # @param trace_id [String, nil] Comma-separated trace IDs (mutually exclusive
+    #   with session_id and experiment_id)
+    # @param session_id [String, nil] Comma-separated session IDs
+    # @param observation_id [String, nil] Comma-separated observation IDs (requires trace_id)
+    # @param experiment_id [String, nil] Comma-separated dataset run (experiment) IDs
+    # @param from_timestamp [Time, String, nil] Inclusive lower bound on score timestamp
+    # @param to_timestamp [Time, String, nil] Exclusive upper bound on score timestamp
+    # @return [Hash] Full response hash with "data" rows and "meta" cursor info
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Read corrections for a trace
+    #   page = api_client.list_scores(trace_id: trace_id, data_type: "CORRECTION", fields: "subject,details")
+    #   page["data"].each { |score| puts score["value"] }
+    # rubocop:disable Metrics/ParameterLists
+    def list_scores(limit: nil, cursor: nil, fields: nil, id: nil, name: nil,
+                    source: nil, data_type: nil, environment: nil, config_id: nil,
+                    queue_id: nil, author_user_id: nil, value: nil, value_min: nil,
+                    value_max: nil, trace_id: nil, session_id: nil,
+                    observation_id: nil, experiment_id: nil,
+                    from_timestamp: nil, to_timestamp: nil)
+      params = build_scores_params(
+        limit: limit, cursor: cursor, fields: fields, id: id, name: name,
+        source: source, data_type: data_type, environment: environment,
+        config_id: config_id, queue_id: queue_id, author_user_id: author_user_id,
+        value: value, value_min: value_min, value_max: value_max,
+        trace_id: trace_id, session_id: session_id, observation_id: observation_id,
+        experiment_id: experiment_id, from_timestamp: from_timestamp, to_timestamp: to_timestamp
+      )
+      request(:get, "/api/public/v3/scores", params: params)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    private
+
+    # v2 observation reads must always be bounded; an unbounded scan over the
+    # events table is rejected here rather than issued silently. Only values
+    # matching the documented query contract can satisfy the bound.
+    def validate_bounded_observation_read!(trace_id, from_start_time, to_start_time)
+      return if non_empty_string?(trace_id)
+      return if valid_query_time?(from_start_time) && valid_query_time?(to_start_time)
+
+      raise ArgumentError,
+            "from_start_time and to_start_time are required unless trace_id is provided"
+    end
+
+    def valid_query_time?(value)
+      non_empty_string?(format_query_time(value))
+    end
+
+    def non_empty_string?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    def build_observations_params(**options)
+      map_query_params(OBSERVATION_QUERY_PARAMS, options).merge(
+        fromStartTime: format_query_time(options[:from_start_time]),
+        toStartTime: format_query_time(options[:to_start_time])
+      ).compact
+    end
+
+    def build_scores_params(**options)
+      map_query_params(SCORE_QUERY_PARAMS, options).merge(
+        fromTimestamp: format_query_time(options[:from_timestamp]),
+        toTimestamp: format_query_time(options[:to_timestamp])
+      ).compact
+    end
+
+    def map_query_params(mapping, options)
+      mapping.to_h { |ruby_key, api_key| [api_key, options[ruby_key]] }
+    end
+
+    def encode_metrics_query(query)
+      case query
+      when Hash then JSON.generate(query)
+      when String then query
+      else raise ArgumentError, "query must be a Hash or JSON String, got #{query.class}"
+      end
+    end
+
+    # Accepts Time-like values or pre-formatted ISO 8601 strings.
+    def format_query_time(value)
+      value.respond_to?(:iso8601) ? value.iso8601 : value
+    end
+  end
+end

data/lib/langfuse/resilient_metrics_reporter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_boolean"
+
+module Langfuse
+  # Protects trace processing from failures in an application-owned metrics reporter.
+  #
+  # @api private
+  class ResilientMetricsReporter
+    def self.wrap(reporter, logger:)
+      return if reporter.nil?
+
+      new(reporter, logger: logger)
+    end
+
+    def initialize(reporter, logger:)
+      @reporter = reporter
+      @logger = logger
+      @warning_emitted = Concurrent::AtomicBoolean.new(false)
+    end
+
+    def add_to_counter(metric, increment: 1, labels: {})
+      safely(:add_to_counter) do
+        @reporter.add_to_counter(metric, increment: increment, labels: labels)
+      end
+    end
+
+    def record_value(metric, value:, labels: {})
+      safely(:record_value) do
+        @reporter.record_value(metric, value: value, labels: labels)
+      end
+    end
+
+    def observe_value(metric, value:, labels: {})
+      safely(:observe_value) do
+        @reporter.observe_value(metric, value: value, labels: labels)
+      end
+    end
+
+    private
+
+    def safely(method_name)
+      yield
+    rescue StandardError => e
+      warn_once(method_name, e.class)
+      nil
+    end
+
+    def warn_once(method_name, error_class)
+      return unless @warning_emitted.make_true
+
+      @logger.warn(
+        "Langfuse metrics_reporter ##{method_name} failed with #{error_class}; " \
+        "future reporter failures will be suppressed"
+      )
+    rescue StandardError
+      nil
+    end
+  end
+end