langfuse-ruby 0.1.6 → 0.2.0

data/lib/langfuse/generation.rb

@@ -3,12 +3,14 @@
 module Langfuse
   class Generation
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :completion_start_time,
-                :model, :model_parameters, :input, :output, :usage, :metadata, :level,
+                :model, :model_parameters, :input, :output, :usage, :usage_details, :cost_details,
+                :prompt_name, :prompt_version, :metadata, :level,
                 :status_message, :parent_observation_id, :version, :as_type, :client
 
     def initialize(client:, trace_id:, id: nil, name: nil, start_time: nil, end_time: nil,
                    completion_start_time: nil, model: nil, model_parameters: nil, input: nil,
-                   output: nil, usage: nil, metadata: nil, level: nil, status_message: nil,
+                   output: nil, usage: nil, usage_details: nil, cost_details: nil, prompt: nil,
+                   metadata: nil, level: nil, status_message: nil,
                    parent_observation_id: nil, version: nil, as_type: nil, **kwargs)
       @client = client
       @id = id || Utils.generate_id
@@ -22,6 +24,9 @@ module Langfuse
       @input = input
       @output = output
       @usage = usage || {}
+      @usage_details = usage_details || {}
+      @cost_details = cost_details || {}
+      @prompt_name, @prompt_version = extract_prompt_info(prompt)
       @metadata = metadata || {}
       @level = level
       @status_message = status_message
@@ -35,7 +40,8 @@ module Langfuse
     end
 
     def update(name: nil, end_time: nil, completion_start_time: nil, model: nil,
-               model_parameters: nil, input: nil, output: nil, usage: nil, metadata: nil,
+               model_parameters: nil, input: nil, output: nil, usage: nil,
+               usage_details: nil, cost_details: nil, prompt: nil, metadata: nil,
                level: nil, status_message: nil, version: nil, **kwargs)
       @name = name if name
       @end_time = end_time if end_time
@@ -45,6 +51,9 @@ module Langfuse
       @input = input if input
       @output = output if output
       @usage.merge!(usage) if usage
+      @usage_details.merge!(usage_details) if usage_details
+      @cost_details.merge!(cost_details) if cost_details
+      @prompt_name, @prompt_version = extract_prompt_info(prompt) if prompt
       @metadata.merge!(metadata) if metadata
       @level = level if level
       @status_message = status_message if status_message
@@ -55,10 +64,12 @@ module Langfuse
       self
     end
 
-    def end(output: nil, end_time: nil, usage: nil, **kwargs)
+    def end(output: nil, end_time: nil, usage: nil, usage_details: nil, cost_details: nil, **kwargs)
       @end_time = end_time || Utils.current_timestamp
       @output = output if output
       @usage.merge!(usage) if usage
+      @usage_details.merge!(usage_details) if usage_details
+      @cost_details.merge!(cost_details) if cost_details
       @kwargs.merge!(kwargs)
 
       update_generation
@@ -261,6 +272,7 @@ module Langfuse
 
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
+        trace_id: @trace_id,
         observation_id: @id,
         name: name,
         value: value,
@@ -293,12 +305,32 @@ module Langfuse
         parent_observation_id: @parent_observation_id,
         version: @version
       }
+      data[:usage_details] = @usage_details unless @usage_details.nil? || @usage_details.empty?
+      data[:cost_details] = @cost_details unless @cost_details.nil? || @cost_details.empty?
+      data[:prompt_name] = @prompt_name if @prompt_name
+      data[:prompt_version] = @prompt_version if @prompt_version
       data[:type] = @as_type if @as_type
       data.merge(@kwargs).compact
     end
 
     private
 
+    # Accepts a Langfuse::Prompt, a Hash with :name/:version, or nil.
+    # Returns [prompt_name, prompt_version] used to link the generation to a prompt version.
+    def extract_prompt_info(prompt)
+      return [nil, nil] if prompt.nil?
+
+      if prompt.respond_to?(:name) && prompt.respond_to?(:version)
+        [prompt.name, prompt.version]
+      elsif prompt.is_a?(Hash)
+        name = prompt[:name] || prompt['name']
+        version = prompt[:version] || prompt['version']
+        [name, version]
+      else
+        [nil, nil]
+      end
+    end
+
     def validate_as_type(type)
       return nil if type.nil?
 

data/lib/langfuse/otel_exporter.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+module Langfuse
+  # Converts batched Langfuse events into OTLP/HTTP JSON (ExportTraceServiceRequest)
+  # and sends them to the Langfuse OTEL endpoint for v4-compatible ingestion.
+  class OtelExporter
+    OTEL_ENDPOINT = '/api/public/otel/v1/traces'
+
+    class << self
+      # Convert an ID (UUID or hex string) to an OTEL 32-char hex trace ID.
+      # OTEL trace IDs are 16 bytes (32 hex chars). Native hex IDs pass through unchanged.
+      def to_otel_trace_id(id_str)
+        return '0' * 32 unless id_str
+
+        hex = id_str.to_s.delete('-')
+        hex.ljust(32, '0')[0, 32]
+      end
+
+      # Convert an ID (UUID or hex string) to an OTEL 16-char hex span ID.
+      # OTEL span IDs are 8 bytes (16 hex chars). Native hex IDs pass through unchanged.
+      def to_otel_span_id(id_str)
+        return '0' * 16 unless id_str
+
+        hex = id_str.to_s.delete('-')
+        hex[0, 16]
+      end
+    end
+
+    # @param connection [Faraday::Connection] HTTP connection to Langfuse host
+    # @param debug [Boolean] whether to print debug output
+    # @param logger [Logger, nil] logger for debug output
+    def initialize(connection:, debug: false, logger: nil)
+      @connection = connection
+      @debug = debug
+      @logger = logger
+    end
+
+    # Export a batch of Langfuse events as OTLP spans.
+    # Note: score-create events are not part of the OTLP mapping and are
+    # handled separately by the client via the ingestion API.
+    # @param events [Array<Hash>] array of event hashes from the event queue
+    # @return [Faraday::Response]
+    def export(events)
+      resource_spans = build_resource_spans(events)
+      payload = { resourceSpans: resource_spans }
+
+      log_debug { "OTEL export payload: #{JSON.pretty_generate(payload)}" }
+
+      @connection.post(OTEL_ENDPOINT) do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.body = JSON.generate(payload)
+      end
+    end
+
+    private
+
+    def log_debug(&block)
+      return unless @debug
+
+      if @logger
+        @logger.debug(block.call)
+      else
+        puts block.call
+      end
+    end
+
+    # Build the top-level resourceSpans array from events.
+    # Groups events by trace_id, producing one scopeSpan per trace.
+    def build_resource_spans(events)
+      grouped = group_events_by_trace(events)
+
+      scope_spans = grouped.map do |_trace_id, trace_events|
+        spans = trace_events.filter_map { |event| convert_event_to_span(event) }
+        next if spans.empty?
+
+        { scope: { name: 'langfuse-ruby', version: Langfuse::VERSION }, spans: spans }
+      end.compact
+
+      return [] if scope_spans.empty?
+
+      [{
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'langfuse-ruby' } },
+            { key: 'telemetry.sdk.name', value: { stringValue: 'langfuse-ruby' } },
+            { key: 'telemetry.sdk.version', value: { stringValue: Langfuse::VERSION } }
+          ]
+        },
+        scopeSpans: scope_spans
+      }]
+    end
+
+    # Group events by their trace ID for proper OTEL span hierarchy.
+    def group_events_by_trace(events)
+      groups = Hash.new { |h, k| h[k] = [] }
+
+      events.each do |event|
+        body = event[:body] || {}
+        trace_id = body['traceId'] || body['trace_id'] || body['id'] || 'unknown'
+        groups[trace_id] << event
+      end
+
+      groups
+    end
+
+    # Convert a single Langfuse event to an OTLP span hash, or nil if not convertible.
+    def convert_event_to_span(event)
+      type = event[:type]
+      body = event[:body] || {}
+
+      case type
+      when 'trace-create'
+        build_trace_span(body)
+      when 'span-create', 'span-update'
+        build_observation_span(body, 'span')
+      when 'generation-create', 'generation-update'
+        build_observation_span(body, 'generation')
+      when 'event-create'
+        build_event_span(body)
+      end
+    end
+
+    # Build a root OTEL span for a Langfuse trace.
+    def build_trace_span(body)
+      trace_id = to_otel_trace_id(body['id'])
+      span_id = to_otel_span_id(body['id'])
+
+      attributes = []
+      add_attr(attributes, 'langfuse.trace.name', body['name'])
+      add_attr(attributes, 'langfuse.user.id', body['userId'])
+      add_attr(attributes, 'langfuse.session.id', body['sessionId'])
+      add_attr(attributes, 'langfuse.release', body['release'])
+      add_attr(attributes, 'langfuse.version', body['version'])
+      add_attr(attributes, 'langfuse.environment', body['environment'])
+      add_attr(attributes, 'langfuse.trace.public', body['public']) unless body['public'].nil?
+      add_attr(attributes, 'langfuse.internal.as_root', true)
+      add_json_attr(attributes, 'langfuse.trace.input', body['input'])
+      add_json_attr(attributes, 'langfuse.trace.output', body['output'])
+      add_json_attr(attributes, 'langfuse.trace.metadata', body['metadata'])
+
+      tags = body['tags']
+      if tags.is_a?(Array) && !tags.empty?
+        add_array_attr(attributes, 'langfuse.trace.tags', tags)
+      end
+
+      {
+        traceId: trace_id,
+        spanId: span_id,
+        name: body['name'] || 'trace',
+        kind: 1, # SPAN_KIND_INTERNAL
+        startTimeUnixNano: to_unix_nano(body['timestamp']),
+        endTimeUnixNano: to_unix_nano(body['timestamp']),
+        attributes: attributes,
+        status: { code: 1 } # STATUS_CODE_OK
+      }
+    end
+
+    # Build an OTEL span for a Langfuse span or generation observation.
+    def build_observation_span(body, obs_type)
+      trace_id = to_otel_trace_id(body['traceId'])
+      span_id = to_otel_span_id(body['id'])
+
+      span = {
+        traceId: trace_id,
+        spanId: span_id,
+        name: body['name'] || obs_type,
+        kind: 1, # SPAN_KIND_INTERNAL
+        startTimeUnixNano: to_unix_nano(body['startTime']),
+        endTimeUnixNano: to_unix_nano(body['endTime'] || body['startTime']),
+        attributes: build_observation_attributes(body, obs_type),
+        status: { code: 1 }
+      }
+
+      # Set parent span ID
+      parent_id = body['parentObservationId']
+      if parent_id
+        span[:parentSpanId] = to_otel_span_id(parent_id)
+      else
+        # Parent is the trace root span
+        span[:parentSpanId] = to_otel_span_id(body['traceId'])
+      end
+
+      span
+    end
+
+    # Build an OTEL span for a Langfuse event (zero-duration span).
+    def build_event_span(body)
+      trace_id = to_otel_trace_id(body['traceId'])
+      span_id = to_otel_span_id(body['id'])
+      timestamp = to_unix_nano(body['startTime'])
+
+      attributes = []
+      add_attr(attributes, 'langfuse.observation.type', 'event')
+      add_json_attr(attributes, 'langfuse.observation.input', body['input'])
+      add_json_attr(attributes, 'langfuse.observation.output', body['output'])
+      add_json_attr(attributes, 'langfuse.observation.metadata', body['metadata'])
+      add_attr(attributes, 'langfuse.observation.level', body['level'])
+      add_attr(attributes, 'langfuse.observation.status_message', body['statusMessage'])
+
+      span = {
+        traceId: trace_id,
+        spanId: span_id,
+        name: body['name'] || 'event',
+        kind: 1,
+        startTimeUnixNano: timestamp,
+        endTimeUnixNano: timestamp,
+        attributes: attributes,
+        status: { code: 1 }
+      }
+
+      parent_id = body['parentObservationId']
+      if parent_id
+        span[:parentSpanId] = to_otel_span_id(parent_id)
+      elsif body['traceId']
+        span[:parentSpanId] = to_otel_span_id(body['traceId'])
+      end
+
+      span
+    end
+
+    # Build OTEL attributes for a span/generation observation.
+    def build_observation_attributes(body, obs_type)
+      attributes = []
+      effective_type = body['type'] || obs_type
+      add_attr(attributes, 'langfuse.observation.type', effective_type)
+      add_json_attr(attributes, 'langfuse.observation.input', body['input'])
+      add_json_attr(attributes, 'langfuse.observation.output', body['output'])
+      add_json_attr(attributes, 'langfuse.observation.metadata', body['metadata'])
+      add_attr(attributes, 'langfuse.observation.level', body['level'])
+      add_attr(attributes, 'langfuse.observation.status_message', body['statusMessage'])
+      add_attr(attributes, 'langfuse.environment', body['environment'])
+
+      if obs_type == 'generation'
+        add_generation_attributes(attributes, body)
+      end
+
+      attributes
+    end
+
+    # Add generation-specific gen_ai.* attributes.
+    def add_generation_attributes(attributes, body)
+      add_attr(attributes, 'gen_ai.request.model', body['model'])
+
+      model_params = body['modelParameters']
+      if model_params.is_a?(Hash)
+        model_params.each do |key, value|
+          add_attr(attributes, "gen_ai.request.#{key}", value) unless value.nil?
+        end
+      end
+
+      usage = body['usage']
+      if usage.is_a?(Hash)
+        add_attr(attributes, 'gen_ai.usage.prompt_tokens', usage['promptTokens'] || usage['prompt_tokens'])
+        add_attr(attributes, 'gen_ai.usage.completion_tokens', usage['completionTokens'] || usage['completion_tokens'])
+        total = usage['totalTokens'] || usage['total_tokens']
+        add_attr(attributes, 'gen_ai.usage.total_tokens', total) if total
+      end
+
+      add_json_attr(attributes, 'langfuse.observation.usage_details', body['usageDetails'])
+      add_json_attr(attributes, 'langfuse.observation.cost_details', body['costDetails'])
+      add_attr(attributes, 'langfuse.observation.prompt.name', body['promptName'])
+      add_attr(attributes, 'langfuse.observation.prompt.version', body['promptVersion'])
+      add_attr(attributes, 'langfuse.observation.completion_start_time', body['completionStartTime'])
+    end
+
+    def to_otel_trace_id(id_str)
+      self.class.to_otel_trace_id(id_str)
+    end
+
+    def to_otel_span_id(id_str)
+      self.class.to_otel_span_id(id_str)
+    end
+
+    # Convert an ISO8601 timestamp string to nanoseconds since epoch.
+    def to_unix_nano(timestamp_str)
+      return '0' unless timestamp_str
+
+      time = Time.parse(timestamp_str.to_s)
+      (time.to_f * 1_000_000_000).to_i.to_s
+    rescue ArgumentError
+      '0'
+    end
+
+    # Add a string/numeric attribute to the attributes array.
+    def add_attr(attributes, key, value)
+      return if value.nil?
+
+      otel_value = case value
+                   when String
+                     { stringValue: value }
+                   when Integer
+                     { intValue: value.to_s }
+                   when Float
+                     { doubleValue: value }
+                   when TrueClass, FalseClass
+                     { boolValue: value }
+                   else
+                     { stringValue: value.to_s }
+                   end
+
+      attributes << { key: key, value: otel_value }
+    end
+
+    # Add a JSON-serialized attribute (for complex objects like input/output).
+    def add_json_attr(attributes, key, value)
+      return if value.nil?
+      return if value.is_a?(Hash) && value.empty?
+      return if value.is_a?(Array) && value.empty?
+
+      json_str = value.is_a?(String) ? value : JSON.generate(value)
+      attributes << { key: key, value: { stringValue: json_str } }
+    end
+
+    # Add an array attribute for tags.
+    def add_array_attr(attributes, key, values)
+      return if values.nil? || values.empty?
+
+      array_values = values.map { |v| { stringValue: v.to_s } }
+      attributes << { key: key, value: { arrayValue: { values: array_values } } }
+    end
+  end
+end

data/lib/langfuse/span.rb

@@ -250,6 +250,7 @@ module Langfuse
 
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
+        trace_id: @trace_id,
         observation_id: @id,
         name: name,
         value: value,

data/lib/langfuse/trace.rb

@@ -3,11 +3,11 @@
 module Langfuse
   class Trace
     attr_reader :id, :name, :user_id, :session_id, :version, :release, :input, :output,
-                :metadata, :tags, :timestamp, :client
+                :metadata, :tags, :timestamp, :public, :client
 
     def initialize(client:, id:, name: nil, user_id: nil, session_id: nil, version: nil,
                    release: nil, input: nil, output: nil, metadata: nil, tags: nil,
-                   timestamp: nil, **kwargs)
+                   timestamp: nil, public: nil, **kwargs)
       @client = client
       @id = id
       @name = name
@@ -20,6 +20,7 @@ module Langfuse
       @metadata = metadata || {}
       @tags = tags || []
       @timestamp = timestamp
+      @public = public
       @kwargs = kwargs
 
       # Create the trace
@@ -50,6 +51,7 @@ module Langfuse
     # Create a child generation
     def generation(name: nil, start_time: nil, end_time: nil, completion_start_time: nil,
                    model: nil, model_parameters: nil, input: nil, output: nil, usage: nil,
+                   usage_details: nil, cost_details: nil, prompt: nil,
                    metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
                    version: nil, **kwargs)
       @client.generation(
@@ -63,6 +65,9 @@ module Langfuse
         input: input,
         output: output,
         usage: usage,
+        usage_details: usage_details,
+        cost_details: cost_details,
+        prompt: prompt,
         metadata: metadata,
         level: level,
         status_message: status_message,
@@ -247,7 +252,8 @@ module Langfuse
     end
 
     def update(name: nil, user_id: nil, session_id: nil, version: nil,
-               release: nil, input: nil, output: nil, metadata: nil, tags: nil, **kwargs)
+               release: nil, input: nil, output: nil, metadata: nil, tags: nil,
+               public: nil, **kwargs)
       # 更新实例变量
       @name = name if name
       @user_id = user_id if user_id
@@ -258,6 +264,7 @@ module Langfuse
       @output = output if output
       @metadata = metadata if metadata
       @tags = tags if tags
+      @public = public unless public.nil?
       @kwargs.merge!(kwargs) if kwargs.any?
       # 触发 trace-update 事件
       update_trace
@@ -279,7 +286,8 @@ module Langfuse
         output: @output,
         metadata: @metadata,
         tags: @tags,
-        timestamp: @timestamp
+        timestamp: @timestamp,
+        public: @public
       }.merge(@kwargs).compact
     end
 
@@ -297,7 +305,8 @@ module Langfuse
         output: @output,
         metadata: @metadata,
         tags: @tags,
-        timestamp: @timestamp
+        timestamp: @timestamp,
+        public: @public
       }.merge(@kwargs).compact
 
       @client.enqueue_event('trace-create', data)
@@ -315,7 +324,8 @@ module Langfuse
         output: @output,
         metadata: @metadata,
         tags: @tags,
-        timestamp: @timestamp
+        timestamp: @timestamp,
+        public: @public
       }.merge(@kwargs).compact
 
       @client.enqueue_event('trace-update', data)

data/lib/langfuse/utils.rb

@@ -6,11 +6,25 @@ require 'erb'
 
 module Langfuse
   module Utils
+    # Body keys whose values must be passed through verbatim (user data),
+    # everything else nested under them keeps its original key format.
+    VERBATIM_BODY_KEYS = %w[input output metadata usageDetails costDetails modelParameters].freeze
+
     class << self
       def generate_id
         SecureRandom.uuid
       end
 
+      # W3C-compatible 32-char hex trace ID (16 bytes), used for OTel ingestion
+      def generate_hex_trace_id
+        SecureRandom.hex(16)
+      end
+
+      # W3C-compatible 16-char hex span/observation ID (8 bytes), used for OTel ingestion
+      def generate_hex_span_id
+        SecureRandom.hex(8)
+      end
+
       def current_timestamp
         Time.now.utc.iso8601(3)
       end
@@ -39,6 +53,24 @@ module Langfuse
         end
       end
 
+      # Prepare an event body for the ingestion API:
+      # - top-level keys are camelized (snake_case -> camelCase)
+      # - user data values (input/output/metadata/usageDetails/costDetails/modelParameters)
+      #   are passed through verbatim so user-provided keys are not mangled
+      # - the legacy `usage` object keys are camelized (prompt_tokens -> promptTokens)
+      def prepare_event_body(body)
+        return body unless body.is_a?(Hash)
+
+        body.each_with_object({}) do |(key, value), result|
+          new_key = camelize_key(key.to_s)
+          result[new_key] = if !VERBATIM_BODY_KEYS.include?(new_key) && value.is_a?(Hash)
+                              deep_stringify_keys(value)
+                            else
+                              value
+                            end
+        end
+      end
+
       # 将哈希的键名转换为小驼峰格式
       def deep_camelize_keys(hash)
         return hash unless hash.is_a?(Hash)

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = '0.1.6'
+  VERSION = '0.2.0'
 end

data/lib/langfuse.rb

@@ -12,9 +12,12 @@ require_relative 'langfuse/evaluation'
 require_relative 'langfuse/errors'
 require_relative 'langfuse/utils'
 require_relative 'langfuse/null_objects'
+require_relative 'langfuse/otel_exporter'
 
 # Ruby SDK for Langfuse - Open source LLM engineering platform
 module Langfuse
+  CLIENT_MUTEX = Mutex.new
+
   class << self
     # Configure the Langfuse client with default settings
     def configure
@@ -30,10 +33,10 @@ module Langfuse
       Client.new(**kwargs)
     end
 
-    # Get a thread-safe singleton client instance
+    # Get a process-wide, thread-safe singleton client instance
     # @return [Client] Langfuse client
     def client
-      Thread.current[:langfuse_client] ||= Client.new
+      @client || CLIENT_MUTEX.synchronize { @client ||= Client.new }
     end
 
     # Get a prompt and optionally compile it with variables
@@ -58,7 +61,7 @@ module Langfuse
         end
       rescue StandardError => e
         if attempts <= retries
-          sleep_time = 2**(attempts - 1) * 0.1 # Exponential backoff: 0.1s, 0.2s, 0.4s...
+          sleep_time = (2**(attempts - 1)) * 0.1 # Exponential backoff: 0.1s, 0.2s, 0.4s...
           warn "Langfuse prompt fetch failed (#{prompt_name}), retrying in #{sleep_time}s... (attempt #{attempts}/#{retries + 1})" if configuration.debug
           sleep(sleep_time)
           retry
@@ -99,7 +102,7 @@ module Langfuse
     #   Langfuse.flush
     #
     def trace(name = nil, user_id: nil, session_id: nil, input: nil, output: nil,
-              metadata: nil, tags: nil, version: nil, release: nil, **kwargs, &block)
+              metadata: nil, tags: nil, version: nil, release: nil, **kwargs)
       trace = client.trace(
         name: name,
         user_id: user_id,
@@ -151,13 +154,14 @@ module Langfuse
 
     # Reset the singleton client (mainly for testing)
     def reset!
-      Thread.current[:langfuse_client] = nil
+      CLIENT_MUTEX.synchronize { @client = nil }
     end
   end
 
   # Configuration class for Langfuse client settings
   class Configuration
-    attr_accessor :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush
+    attr_accessor :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush,
+                  :ingestion_mode, :environment, :sample_rate, :mask, :flush_at, :logger, :shutdown_on_exit
 
     def initialize
       @public_key = nil
@@ -168,6 +172,13 @@ module Langfuse
       @retries = 3
       @flush_interval = 5
       @auto_flush = true
+      @ingestion_mode = :legacy # :legacy or :otel
+      @environment = nil       # default tracing environment for all events
+      @sample_rate = nil       # 0.0..1.0, nil disables sampling
+      @mask = nil              # callable applied to input/output/metadata before sending
+      @flush_at = 15           # flush as soon as this many events are queued
+      @logger = nil            # custom Logger instance
+      @shutdown_on_exit = true # register an at_exit hook that flushes pending events
     end
   end
 end