langfuse-ruby 0.1.7 → 0.2.1

data/lib/langfuse/event.rb

@@ -57,23 +57,7 @@ module Langfuse
     end
 
     def create_event
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }
-      data[:type] = @as_type if @as_type
-      data = data.merge(@kwargs).compact
-
-      @client.enqueue_event('event-create', data)
+      @client.enqueue_event('event-create', to_dict)
     end
   end
 end

data/lib/langfuse/generation.rb

@@ -2,13 +2,17 @@
 
 module Langfuse
   class Generation
+    include PartialUpdates
+
     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 +26,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,32 +42,51 @@ 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
-      @completion_start_time = completion_start_time if completion_start_time
-      @model = model if model
+      @name = name unless name.nil?
+      @end_time = end_time unless end_time.nil?
+      @completion_start_time = completion_start_time unless completion_start_time.nil?
+      @model = model unless model.nil?
       @model_parameters.merge!(model_parameters) if model_parameters
-      @input = input if input
-      @output = output if output
+      @input = input unless input.nil?
+      @output = output unless output.nil?
       @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
-      @version = version if version
+      @level = level unless level.nil?
+      @status_message = status_message unless status_message.nil?
+      @version = version unless version.nil?
       @kwargs.merge!(kwargs)
 
+      changes = { name: name, end_time: end_time, completion_start_time: completion_start_time,
+                  model: model, model_parameters: model_parameters, input: input, output: output,
+                  usage: usage, usage_details: usage_details, cost_details: cost_details,
+                  metadata: metadata, level: level, status_message: status_message,
+                  version: version }
+      changes.merge!(prompt_name: @prompt_name, prompt_version: @prompt_version) if prompt
+
+      track_changes(changes, kwargs.keys)
       update_generation
       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
+      @output = output unless output.nil?
       @usage.merge!(usage) if usage
+      @usage_details.merge!(usage_details) if usage_details
+      @cost_details.merge!(cost_details) if cost_details
       @kwargs.merge!(kwargs)
 
+      track_changes(
+        { end_time: @end_time, output: output, usage: usage,
+          usage_details: usage_details, cost_details: cost_details },
+        kwargs.keys
+      )
       update_generation
       self
     end
@@ -88,6 +114,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, version: nil, **kwargs)
       @client.generation(
         trace_id: @trace_id,
@@ -100,6 +127,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,
@@ -127,79 +157,11 @@ module Langfuse
       )
     end
 
-    # Convenience methods for enhanced observation types
-
-    # Create a child agent observation
-    def agent(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-              metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::AGENT,
-        **kwargs
-      )
-    end
-
-    # Create a child tool observation
-    def tool(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-             metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::TOOL,
-        **kwargs
-      )
-    end
-
-    # Create a child chain observation
-    def chain(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-              metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::CHAIN,
-        **kwargs
-      )
-    end
-
-    # Create a child retriever observation
-    def retriever(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::RETRIEVER,
-        **kwargs
-      )
-    end
+    # Convenience methods for enhanced observation types: each is a child span
+    # with a fixed as_type. (embedding keeps its own definition because it folds
+    # model/usage into metadata first.)
+    extend SpanWrappers
+    define_span_wrappers
 
     # Create a child embedding observation
     def embedding(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
@@ -223,44 +185,9 @@ module Langfuse
       )
     end
 
-    # Create a child evaluator observation
-    def evaluator(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::EVALUATOR,
-        **kwargs
-      )
-    end
-
-    # Create a child guardrail observation
-    def guardrail(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        version: version,
-        as_type: ObservationType::GUARDRAIL,
-        **kwargs
-      )
-    end
-
     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 +220,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?
 
@@ -313,7 +260,7 @@ module Langfuse
     end
 
     def update_generation
-      @client.enqueue_event('generation-update', to_dict)
+      @client.enqueue_event('generation-update', update_body)
     end
   end
 end

data/lib/langfuse/null_objects.rb

@@ -15,6 +15,7 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
@@ -36,6 +37,7 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
@@ -65,10 +67,12 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
     def to_dict = {}
     def id = nil
+    def trace_id = nil
   end
 end

data/lib/langfuse/otel_exporter.rb

@@ -9,21 +9,54 @@ module Langfuse
   class OtelExporter
     OTEL_ENDPOINT = '/api/public/otel/v1/traces'
 
+    # Event types that carry the full state of an observation on every emit, so a
+    # later event supersedes the earlier one for the same observation id.
+    OBSERVATION_EVENT_TYPES = %w[span-create span-update generation-create generation-update].freeze
+
+    # Token keys accepted on the legacy `usage` object, in priority order.
+    USAGE_INPUT_KEYS = %w[promptTokens prompt_tokens inputTokens input_tokens input].freeze
+    USAGE_OUTPUT_KEYS = %w[completionTokens completion_tokens outputTokens output_tokens output].freeze
+    USAGE_TOTAL_KEYS = %w[totalTokens total_tokens total].freeze
+
+    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,10 +66,20 @@ 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)
-      grouped = group_events_by_trace(events)
+      grouped = group_events_by_trace(collapse_observation_events(events))
 
       scope_spans = grouped.map do |_trace_id, trace_events|
         spans = trace_events.filter_map { |event| convert_event_to_span(event) }
@@ -59,6 +102,40 @@ module Langfuse
       }]
     end
 
+    # Collapse the create/update events of one observation into a single event.
+    # The v4 data model is append-only, so exporting both would produce two
+    # observations sharing a span id. Bodies are merged into new hashes, leaving
+    # the queued events untouched for re-queueing when the export fails.
+    def collapse_observation_events(events)
+      position_by_id = {}
+
+      events.each_with_object([]) do |event, collapsed|
+        id = observation_event_id(event)
+
+        if id.nil?
+          collapsed << event
+        elsif (position = position_by_id[id])
+          previous = collapsed[position]
+          collapsed[position] = previous.merge(
+            type: event[:type],
+            body: previous[:body].merge(event[:body])
+          )
+        else
+          position_by_id[id] = collapsed.length
+          collapsed << event
+        end
+      end
+    end
+
+    def observation_event_id(event)
+      return nil unless OBSERVATION_EVENT_TYPES.include?(event[:type])
+
+      body = event[:body]
+      return nil unless body.is_a?(Hash)
+
+      body['id'] || body[:id]
+    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] = [] }
@@ -86,8 +163,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 +177,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 +264,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 +274,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)
@@ -253,33 +294,71 @@ module Langfuse
         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
+      add_usage_attributes(attributes, body)
+      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
+
+    # Emit token usage both as gen_ai.* semantic conventions and as the Langfuse
+    # v4 usage_details model. usage_details is what v4 uses for cost, so a legacy
+    # `usage` object is normalized into it when no explicit usage_details exists.
+    def add_usage_attributes(attributes, body)
+      usage = normalize_legacy_usage(body['usage'])
+
+      if usage
+        add_attr(attributes, 'gen_ai.usage.prompt_tokens', usage[:input])
+        add_attr(attributes, 'gen_ai.usage.completion_tokens', usage[:output])
+        add_attr(attributes, 'gen_ai.usage.total_tokens', usage[:total])
+      end
+
+      usage_details = body['usageDetails']
+      usage_details = usage if blank_value?(usage_details)
+      add_json_attr(attributes, 'langfuse.observation.usage_details', usage_details)
+    end
+
+    # Accept every shape the legacy ingestion API allowed
+    # (promptTokens / inputTokens / input) and return {input:, output:, total:}.
+    # Non-token units are skipped: usage_details is token-based, so mapping them
+    # would produce wrong cost numbers.
+    def normalize_legacy_usage(usage)
+      return nil unless usage.is_a?(Hash) && !usage.empty?
+
+      unit = usage['unit'] || usage[:unit]
+      if unit && unit.to_s.upcase != 'TOKENS'
+        log_debug { "Skipping usage with unit #{unit}; use usage_details for non-token usage" }
+        return nil
       end
 
-      add_attr(attributes, 'langfuse.observation.completion_start_time', body['completionStartTime'])
+      normalized = {
+        input: fetch_usage_value(usage, USAGE_INPUT_KEYS),
+        output: fetch_usage_value(usage, USAGE_OUTPUT_KEYS),
+        total: fetch_usage_value(usage, USAGE_TOTAL_KEYS)
+      }.compact
+
+      normalized.empty? ? nil : normalized
     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
+    def fetch_usage_value(usage, keys)
+      keys.each do |key|
+        value = usage[key]
+        return value unless value.nil?
+      end
+
+      nil
+    end
 
-      hex = uuid_str.to_s.delete('-')
-      hex.ljust(32, '0')[0, 32]
+    def blank_value?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
     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
+    def to_otel_trace_id(id_str)
+      self.class.to_otel_trace_id(id_str)
+    end
 
-      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,14 +366,17 @@ 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_i * 1_000_000_000) + time.nsec).to_s
     rescue ArgumentError
       '0'
     end
 
     # Add a string/numeric attribute to the attributes array.
+    # Structured values are JSON-encoded instead of falling back to Ruby's
+    # inspect format (which is not machine-readable on the Langfuse side).
     def add_attr(attributes, key, value)
       return if value.nil?
+      return add_json_attr(attributes, key, value) if value.is_a?(Hash) || value.is_a?(Array)
 
       otel_value = case value
                    when String

data/lib/langfuse/partial_updates.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Update events carry only the fields that changed. The ingestion API merges an
+  # update into the existing trace/observation, so re-sending a generation's
+  # input on every `end` call would double the payload of every LLM call.
+  module PartialUpdates
+    # Always sent so the server can resolve (and if needed upsert) the entity.
+    # `to_dict#slice` ignores the keys a given class does not have.
+    UPDATE_IDENTITY_FIELDS = %i[id trace_id type].freeze
+
+    private
+
+    # `changes` maps a body field to the value passed to update/end; nil means
+    # "not provided" and is left out of the update body. `extra_keys` carries the
+    # caller's **kwargs, which are merged into the body by to_dict.
+    def track_changes(changes, extra_keys = nil)
+      keys = changes.compact.keys
+      keys.concat(extra_keys.to_a)
+      @changed_fields = keys
+    end
+
+    def update_body
+      # Never tracked → this is a create path; use the full body.
+      return to_dict if @changed_fields.nil?
+
+      to_dict.slice(*UPDATE_IDENTITY_FIELDS, *@changed_fields)
+    end
+  end
+end