langfuse-ruby 0.1.5 → 0.1.7

data/lib/langfuse/otel_exporter.rb

@@ -0,0 +1,333 @@
+# 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'
+
+    # @param connection [Faraday::Connection] HTTP connection to Langfuse host
+    # @param debug [Boolean] whether to print debug output
+    def initialize(connection:, debug: false)
+      @connection = connection
+      @debug = debug
+    end
+
+    # Export a batch of Langfuse events as OTLP spans.
+    # @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
+
+      @connection.post(OTEL_ENDPOINT) do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.body = JSON.generate(payload)
+      end
+    end
+
+    private
+
+    # 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)
+      when 'score-create'
+        build_score_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_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 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 = []
+      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'])
+
+      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_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]
+    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]
+    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/prompt.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Prompt
     attr_reader :id, :name, :version, :prompt, :config, :labels, :tags, :type, :created_at, :updated_at
@@ -148,8 +150,6 @@ module Langfuse
       new(template: template, input_variables: variables)
     end
 
-    private
-
     def self.extract_variables(text)
       variables = []
 

data/lib/langfuse/span.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Span
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :input, :output,
@@ -286,9 +288,7 @@ module Langfuse
       return nil if type.nil?
 
       type_str = type.to_s
-      unless ObservationType.valid?(type_str)
-        raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}"
-      end
+      raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}" unless ObservationType.valid?(type_str)
 
       type_str
     end

data/lib/langfuse/trace.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Trace
     attr_reader :id, :name, :user_id, :session_id, :version, :release, :input, :output,

data/lib/langfuse/utils.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'securerandom'
 require 'time'
 require 'erb'

data/lib/langfuse/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
-  VERSION = "0.1.5"
+  VERSION = '0.1.7'
 end

data/lib/langfuse.rb

@@ -11,6 +11,8 @@ require_relative 'langfuse/prompt'
 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
@@ -25,14 +27,139 @@ module Langfuse
     end
 
     # Create a new Langfuse client instance
-    def new(**options)
-      Client.new(**options)
+    def new(**kwargs)
+      Client.new(**kwargs)
+    end
+
+    # Get a thread-safe singleton client instance
+    # @return [Client] Langfuse client
+    def client
+      Thread.current[:langfuse_client] ||= Client.new
+    end
+
+    # Get a prompt and optionally compile it with variables
+    # @param prompt_name [String] prompt name
+    # @param variables [Hash] optional variables for compilation
+    # @param label [String] optional prompt label (defaults to 'production' or 'latest')
+    # @param version [Integer] optional prompt version
+    # @param cache_ttl_seconds [Integer] cache TTL in seconds (default: 60)
+    # @param retries [Integer] number of retries on failure (default: 2)
+    # @return [String, Prompt, nil] compiled prompt string if variables provided, Prompt object otherwise, nil on failure
+    def get_prompt(prompt_name, variables: nil, label: nil, version: nil, cache_ttl_seconds: 60, retries: 2)
+      attempts = 0
+
+      begin
+        attempts += 1
+        prompt = client.get_prompt(prompt_name, label: label, version: version, cache_ttl_seconds: cache_ttl_seconds)
+
+        if variables
+          prompt.compile(variables)
+        else
+          prompt
+        end
+      rescue StandardError => e
+        if attempts <= retries
+          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
+        end
+
+        warn "Langfuse prompt fetch failed (#{prompt_name}): #{e.message}" if configuration.debug
+        nil
+      end
+    end
+
+    # Create a trace and optionally execute a block with it
+    # When a block is given, the trace is yielded and flush is called automatically after the block
+    # If trace creation fails, a NullTrace is yielded to ensure the block still executes
+    #
+    # @param name [String] trace name
+    # @param user_id [String] optional user identifier
+    # @param session_id [String] optional session identifier
+    # @param input [Object] optional input data
+    # @param output [Object] optional output data
+    # @param metadata [Hash] optional metadata
+    # @param tags [Array] optional tags
+    # @param version [String] optional version
+    # @param release [String] optional release
+    # @yield [Trace, NullTrace] trace object for recording observations
+    # @return [Object] block return value if block given, trace otherwise
+    #
+    # @example Block-based usage with automatic flush
+    #   Langfuse.trace("my-trace", user_id: "user-1") do |trace|
+    #     generation = trace.generation(name: "openai", model: "gpt-4", input: messages)
+    #     response = call_openai(...)
+    #     generation.end(output: response, usage: response.usage)
+    #     trace.update(output: response)
+    #   end
+    #
+    # @example Direct usage without block
+    #   trace = Langfuse.trace("my-trace")
+    #   # ... work with trace
+    #   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)
+      trace = client.trace(
+        name: name,
+        user_id: user_id,
+        session_id: session_id,
+        input: input,
+        output: output,
+        metadata: metadata,
+        tags: tags,
+        version: version,
+        release: release,
+        **kwargs
+      )
+
+      if block_given?
+        begin
+          result = yield(trace)
+          result
+        ensure
+          flush
+        end
+      else
+        trace
+      end
+    rescue StandardError => e
+      warn "Langfuse trace creation failed: #{e.message}" if configuration.debug
+
+      # If block given, execute with NullTrace to ensure code continues
+      if block_given?
+        null_trace = NullTrace.new
+        yield(null_trace)
+      else
+        NullTrace.new
+      end
+    end
+
+    # Flush all pending events to Langfuse
+    def flush
+      client.flush
+    rescue StandardError => e
+      warn "Langfuse flush failed: #{e.message}" if configuration.debug
+    end
+
+    # Shutdown the singleton client
+    def shutdown
+      client.shutdown
+    rescue StandardError => e
+      warn "Langfuse shutdown failed: #{e.message}" if configuration.debug
+    end
+
+    # Reset the singleton client (mainly for testing)
+    def reset!
+      Thread.current[:langfuse_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
 
     def initialize
       @public_key = nil
@@ -43,6 +170,7 @@ module Langfuse
       @retries = 3
       @flush_interval = 5
       @auto_flush = true
+      @ingestion_mode = :legacy # :legacy or :otel
     end
   end
 end

data/scripts/release.sh

@@ -49,7 +49,7 @@ if ! bundle exec rspec; then
 fi
 
 print_status "Running offline tests..."
-if ! ruby test_offline.rb; then
+if ! ruby scripts/test_offline.rb; then
     print_error "Offline tests failed. Please fix them before releasing."
     exit 1
 fi

data/{test_offline.rb → scripts/test_offline.rb}

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require_relative 'lib/langfuse'
+require_relative '../lib/langfuse'
 
 puts '🚀 Testing Langfuse Ruby SDK (Offline Mode)...'
 
@@ -223,7 +224,7 @@ begin
   )
 
   # Embedding generation
-  embedding_gen = retrieval_span.generation(
+  retrieval_span.generation(
     name: 'embedding-generation',
     model: 'text-embedding-ada-002',
     input: 'quantum computing basics',
@@ -250,7 +251,7 @@ begin
   )
 
   # LLM generation
-  llm_gen = answer_span.generation(
+  answer_span.generation(
     name: 'openai-completion',
     model: 'gpt-4',
     input: [

data/scripts/verify_release.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 # Langfuse Ruby SDK Release Verification Script
 require 'net/http'
@@ -78,10 +79,10 @@ end
 
 # Run checks
 puts "\n🔍 Checking RubyGems availability..."
-gem_available = check_rubygems('langfuse', current_version)
+gem_available = check_rubygems('langfuse-ruby', current_version)
 
 puts "\n🔍 Checking version availability..."
-version_available = check_version_availability('langfuse', current_version)
+version_available = check_version_availability('langfuse-ruby', current_version)
 
 # Test local installation
 puts "\n🔍 Testing local gem functionality..."
@@ -94,7 +95,7 @@ begin
 
   # Test client creation (without real credentials)
   begin
-    client = Langfuse.new(public_key: 'test', secret_key: 'test')
+    Langfuse.new(public_key: 'test', secret_key: 'test')
     puts '✅ Client creation successful'
   rescue Langfuse::AuthenticationError
     puts '✅ Authentication error expected (no real credentials)'
@@ -134,6 +135,6 @@ else
 end
 
 puts "\n🔗 Useful links:"
-puts '   - RubyGems page: https://rubygems.org/gems/langfuse'
+puts '   - RubyGems page: https://rubygems.org/gems/langfuse-ruby'
 puts '   - Documentation: https://github.com/ai-firstly/langfuse-ruby'
 puts '   - Issues: https://github.com/ai-firstly/langfuse-ruby/issues'