langfuse-ruby 0.1.7 → 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

@@ -9,21 +9,45 @@ module Langfuse
   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
-    def initialize(connection:, debug: false)
+    # @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 }
 
-      puts "OTEL export payload: #{JSON.pretty_generate(payload)}" if @debug
+      log_debug { "OTEL export payload: #{JSON.pretty_generate(payload)}" }
 
       @connection.post(OTEL_ENDPOINT) do |req|
         req.headers['Content-Type'] = 'application/json'
@@ -33,6 +57,16 @@ module Langfuse
 
     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)
@@ -86,8 +120,6 @@ module Langfuse
         build_observation_span(body, 'generation')
       when 'event-create'
         build_event_span(body)
-      when 'score-create'
-        build_score_span(body)
       end
     end
 
@@ -102,6 +134,9 @@ module Langfuse
       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'])
@@ -186,44 +221,6 @@ module Langfuse
       span
     end
 
-    # Build a minimal OTEL span for a score event.
-    def build_score_span(body)
-      trace_id_raw = body['traceId']
-      return nil unless trace_id_raw
-
-      trace_id = to_otel_trace_id(trace_id_raw)
-      span_id = to_otel_span_id(body['id'] || SecureRandom.uuid)
-      timestamp = to_unix_nano(body['timestamp'] || Time.now.utc.iso8601(3))
-
-      attributes = []
-      add_attr(attributes, 'langfuse.score.name', body['name'])
-      add_attr(attributes, 'langfuse.score.value', body['value'])
-      add_attr(attributes, 'langfuse.score.data_type', body['dataType'])
-      add_attr(attributes, 'langfuse.score.comment', body['comment'])
-      add_attr(attributes, 'langfuse.observation.type', 'score')
-
-      if body['observationId']
-        add_attr(attributes, 'langfuse.score.observation_id', body['observationId'])
-      end
-
-      span = {
-        traceId: trace_id,
-        spanId: span_id,
-        name: "score-#{body['name']}",
-        kind: 1,
-        startTimeUnixNano: timestamp,
-        endTimeUnixNano: timestamp,
-        attributes: attributes,
-        status: { code: 1 }
-      }
-
-      # Parent is either the observation or the trace
-      parent_raw = body['observationId'] || trace_id_raw
-      span[:parentSpanId] = to_otel_span_id(parent_raw) if parent_raw
-
-      span
-    end
-
     # Build OTEL attributes for a span/generation observation.
     def build_observation_attributes(body, obs_type)
       attributes = []
@@ -234,6 +231,7 @@ module Langfuse
       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)
@@ -261,25 +259,19 @@ module Langfuse
         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
 
-    # Convert a UUID string to OTEL 32-char hex trace ID.
-    # OTEL trace IDs are 16 bytes (32 hex chars).
-    def to_otel_trace_id(uuid_str)
-      return '0' * 32 unless uuid_str
-
-      hex = uuid_str.to_s.delete('-')
-      hex.ljust(32, '0')[0, 32]
+    def to_otel_trace_id(id_str)
+      self.class.to_otel_trace_id(id_str)
     end
 
-    # Convert a UUID string to OTEL 16-char hex span ID.
-    # OTEL span IDs are 8 bytes (16 hex chars).
-    def to_otel_span_id(uuid_str)
-      return '0' * 16 unless uuid_str
-
-      hex = uuid_str.to_s.delete('-')
-      hex[0, 16]
+    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.
@@ -287,7 +279,7 @@ module Langfuse
       return '0' unless timestamp_str
 
       time = Time.parse(timestamp_str.to_s)
-      ((time.to_f * 1_000_000_000).to_i).to_s
+      (time.to_f * 1_000_000_000).to_i.to_s
     rescue ArgumentError
       '0'
     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.7'
+  VERSION = '0.2.0'
 end

data/lib/langfuse.rb

@@ -16,6 +16,8 @@ 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
@@ -31,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
@@ -59,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
@@ -100,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,
@@ -152,14 +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,
-                  :ingestion_mode
+                  :ingestion_mode, :environment, :sample_rate, :mask, :flush_at, :logger, :shutdown_on_exit
 
     def initialize
       @public_key = nil
@@ -171,6 +173,12 @@ module Langfuse
       @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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Richard Sun
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -147,6 +161,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -200,6 +228,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
+- ".mise.toml"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CLAUDE.md
@@ -263,7 +292,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby SDK for Langfuse - Open source LLM engineering platform
 test_files: []