langfuse-rb 0.1.0

data/lib/langfuse/otel_attributes.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Serialization layer that converts Langfuse domain models to OpenTelemetry span attributes format
+  #
+  # This module provides methods to convert user-friendly Langfuse attribute objects
+  # into the internal OpenTelemetry attribute format required by the span processor.
+  #
+  # @example Converting trace attributes
+  #   attrs = Langfuse::Types::TraceAttributes.new(
+  #     name: "user-checkout-flow",
+  #     user_id: "user-123",
+  #     tags: ["checkout", "payment"],
+  #     metadata: { version: "2.1.0" }
+  #   )
+  #   otel_attrs = Langfuse::OtelAttributes.create_trace_attributes(attrs)
+  #   span.set_attributes(otel_attrs)
+  #
+  # @example Converting observation attributes
+  #   attrs = Langfuse::Types::GenerationAttributes.new(
+  #     model: "gpt-4",
+  #     input: { messages: [...] },
+  #     usage_details: { prompt_tokens: 100 }
+  #   )
+  #   otel_attrs = Langfuse::OtelAttributes.create_observation_attributes("generation", attrs)
+  #   span.set_attributes(otel_attrs)
+  #
+  # rubocop:disable Metrics/ModuleLength
+  module OtelAttributes
+    # Trace attributes
+    TRACE_NAME = "langfuse.trace.name"
+    # TRACE_USER_ID and TRACE_SESSION_ID are without langfuse prefix
+    # because they follow OpenTelemetry semantic conventions
+    TRACE_USER_ID = "user.id"
+    TRACE_SESSION_ID = "session.id"
+    TRACE_INPUT = "langfuse.trace.input"
+    TRACE_OUTPUT = "langfuse.trace.output"
+    TRACE_METADATA = "langfuse.trace.metadata"
+    TRACE_TAGS = "langfuse.trace.tags"
+    TRACE_PUBLIC = "langfuse.trace.public"
+
+    # Observation attributes
+    OBSERVATION_TYPE = "langfuse.observation.type"
+    OBSERVATION_INPUT = "langfuse.observation.input"
+    OBSERVATION_OUTPUT = "langfuse.observation.output"
+    OBSERVATION_METADATA = "langfuse.observation.metadata"
+    OBSERVATION_LEVEL = "langfuse.observation.level"
+    OBSERVATION_STATUS_MESSAGE = "langfuse.observation.status_message"
+    OBSERVATION_MODEL = "langfuse.observation.model.name"
+    OBSERVATION_MODEL_PARAMETERS = "langfuse.observation.model.parameters"
+    OBSERVATION_USAGE_DETAILS = "langfuse.observation.usage_details"
+    OBSERVATION_COST_DETAILS = "langfuse.observation.cost_details"
+    OBSERVATION_PROMPT_NAME = "langfuse.observation.prompt.name"
+    OBSERVATION_PROMPT_VERSION = "langfuse.observation.prompt.version"
+    OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
+
+    # Common attributes
+    VERSION = "langfuse.version"
+    RELEASE = "langfuse.release"
+    ENVIRONMENT = "langfuse.environment"
+
+    # Creates OpenTelemetry attributes from Langfuse trace attributes
+    #
+    # Converts user-friendly trace attributes into the internal OpenTelemetry
+    # attribute format required by the span processor.
+    #
+    # @param attrs [Types::TraceAttributes, Hash] Trace attributes object or hash
+    # @return [Hash] OpenTelemetry attributes hash with non-nil values
+    #
+    # @example
+    #   attrs = Langfuse::Types::TraceAttributes.new(
+    #     name: "user-checkout-flow",
+    #     user_id: "user-123",
+    #     session_id: "session-456",
+    #     tags: ["checkout", "payment"],
+    #     metadata: { version: "2.1.0" }
+    #   )
+    #   otel_attrs = Langfuse::OtelAttributes.create_trace_attributes(attrs)
+    #
+    def self.create_trace_attributes(attrs)
+      # Convert to hash if it's a TraceAttributes object
+      attrs = attrs.to_h
+      get_value = ->(key) { get_hash_value(attrs, key) }
+
+      attributes = {
+        TRACE_NAME => get_value.call(:name),
+        TRACE_USER_ID => get_value.call(:user_id),
+        TRACE_SESSION_ID => get_value.call(:session_id),
+        VERSION => get_value.call(:version),
+        RELEASE => get_value.call(:release),
+        TRACE_INPUT => serialize(get_value.call(:input)),
+        TRACE_OUTPUT => serialize(get_value.call(:output)),
+        TRACE_TAGS => serialize(get_value.call(:tags)),
+        ENVIRONMENT => get_value.call(:environment),
+        TRACE_PUBLIC => get_value.call(:public),
+        **flatten_metadata(get_value.call(:metadata), TRACE_METADATA)
+      }
+
+      # Remove nil values
+      attributes.compact
+    end
+
+    # Creates OpenTelemetry attributes from Langfuse observation attributes
+    #
+    # Converts user-friendly observation attributes into the internal OpenTelemetry
+    # attribute format required by the span processor.
+    #
+    # @param type [String] Observation type (e.g., "generation", "span", "event")
+    # @param attrs [Types::SpanAttributes, Types::GenerationAttributes, Hash] Observation attributes
+    # @return [Hash] OpenTelemetry attributes hash with non-nil values
+    #
+    # @example
+    #   attrs = Langfuse::Types::GenerationAttributes.new(
+    #     model: "gpt-4",
+    #     input: { messages: [...] },
+    #     usage_details: { prompt_tokens: 100 }
+    #   )
+    #   otel_attrs = Langfuse::OtelAttributes.create_observation_attributes("generation", attrs)
+    #
+    def self.create_observation_attributes(type, attrs)
+      attrs = attrs.to_h
+      get_value = ->(key) { get_hash_value(attrs, key) }
+
+      otel_attributes = build_observation_base_attributes(type, get_value)
+      add_prompt_attributes(otel_attributes, get_value.call(:prompt))
+
+      # Remove nil values
+      otel_attributes.compact
+    end
+
+    # Safely serializes an object to JSON string
+    #
+    # @param obj [Object, nil] Object to serialize
+    # @param preserve_strings [Boolean] If true, preserves strings as-is; if false, JSON-serializes everything including strings
+    # @return [String, nil] JSON string, original string (if preserve_strings is true), or nil if nil/undefined
+    #
+    # @example Always JSON-serialize (default)
+    #   serialize({ key: "value" }) # => '{"key":"value"}'
+    #   serialize("string") # => '"string"'
+    #   serialize(nil) # => nil
+    #
+    # @example Preserve strings
+    #   serialize("already a string", preserve_strings: true) # => "already a string"
+    #   serialize([1, 2, 3], preserve_strings: true) # => "[1,2,3]"
+    #
+    # @api private
+    def self.serialize(obj, preserve_strings: false)
+      return nil if obj.nil?
+      return obj if preserve_strings && obj.is_a?(String)
+
+      begin
+        obj.to_json
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Flattens and serializes metadata into OpenTelemetry attribute format
+    #
+    # Converts nested metadata objects into dot-notation attribute keys.
+    # For example, `{ database: { host: 'localhost' } }` becomes
+    # `{ 'langfuse.trace.metadata.database.host': 'localhost' }`.
+    #
+    # @param metadata [Hash, Array, Object, nil] Metadata to flatten
+    # @param prefix [String] Prefix for attribute keys (e.g., "langfuse.trace.metadata")
+    # @return [Hash] Flattened metadata attributes
+    #
+    # @example
+    #   flatten_metadata({ user: { id: 123 } }, "langfuse.trace.metadata")
+    #   # => { "langfuse.trace.metadata.user.id" => "123" }
+    #
+    def self.flatten_metadata(metadata, prefix)
+      return {} if metadata.nil?
+
+      # Handle non-hash metadata (arrays, primitives, etc.)
+      unless metadata.is_a?(Hash)
+        serialized = serialize(metadata, preserve_strings: true)
+        return serialized ? { prefix => serialized } : {}
+      end
+
+      # Recursively flatten hash metadata
+      result = {}
+      metadata.each do |key, value|
+        next if value.nil?
+
+        new_key = "#{prefix}.#{key}"
+        result.merge!(flatten_hash_value(value, new_key))
+      end
+
+      result
+    end
+
+    # Flattens a single hash value (recursively if it's a hash, serializes otherwise)
+    #
+    # @param value [Object] Value to flatten
+    # @param key [String] Attribute key prefix
+    # @return [Hash] Flattened attributes hash
+    # @api private
+    def self.flatten_hash_value(value, key)
+      if value.is_a?(Hash)
+        # Recursively flatten nested hashes
+        flatten_metadata(value, key)
+      elsif value.is_a?(Array)
+        # Serialize arrays to JSON
+        serialized = serialize(value, preserve_strings: true)
+        serialized ? { key => serialized } : {}
+      else
+        # Convert simple values (strings, numbers, booleans) to strings
+        { key => value.to_s }
+      end
+    end
+
+    # Gets a value from a hash supporting both symbol and string keys
+    # Handles false values correctly (doesn't treat false as nil)
+    #
+    # @param hash [Hash] Hash to get value from
+    # @param key [Symbol, String] Key to look up
+    # @return [Object, nil] Value from hash or nil
+    # @api private
+    def self.get_hash_value(hash, key)
+      return hash[key] if hash.key?(key)
+      return hash[key.to_s] if hash.key?(key.to_s)
+
+      nil
+    end
+
+    # Builds base observation attributes (without prompt)
+    #
+    # @param type [String] Observation type
+    # @param get_value [Proc] Lambda to get values from attributes hash
+    # @return [Hash] Base observation attributes
+    # @api private
+    def self.build_observation_base_attributes(type, get_value)
+      {
+        OBSERVATION_TYPE => type,
+        OBSERVATION_LEVEL => get_value.call(:level),
+        OBSERVATION_STATUS_MESSAGE => get_value.call(:status_message),
+        VERSION => get_value.call(:version),
+        OBSERVATION_INPUT => serialize(get_value.call(:input)),
+        OBSERVATION_OUTPUT => serialize(get_value.call(:output)),
+        OBSERVATION_MODEL => get_value.call(:model),
+        OBSERVATION_USAGE_DETAILS => serialize(get_value.call(:usage_details)),
+        OBSERVATION_COST_DETAILS => serialize(get_value.call(:cost_details)),
+        OBSERVATION_COMPLETION_START_TIME => serialize(get_value.call(:completion_start_time)),
+        OBSERVATION_MODEL_PARAMETERS => serialize(get_value.call(:model_parameters)),
+        ENVIRONMENT => get_value.call(:environment),
+        **flatten_metadata(get_value.call(:metadata), OBSERVATION_METADATA)
+      }
+    end
+
+    # Adds prompt attributes if prompt is present and not a fallback
+    #
+    # @param otel_attributes [Hash] Attributes hash to modify
+    # @param prompt [Hash, Object, nil] Prompt hash or object
+    # @return [void]
+    # @api private
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def self.add_prompt_attributes(otel_attributes, prompt)
+      return unless prompt
+
+      # Handle hash-like prompts
+      if prompt.is_a?(Hash) || prompt.respond_to?(:[])
+        return if prompt[:is_fallback] || prompt["is_fallback"]
+
+        otel_attributes[OBSERVATION_PROMPT_NAME] = prompt[:name] || prompt["name"]
+        otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt[:version] || prompt["version"]
+      # Handle objects with name/version methods (already converted in Trace#generation)
+      elsif prompt.respond_to?(:name) && prompt.respond_to?(:version)
+        otel_attributes[OBSERVATION_PROMPT_NAME] = prompt.name
+        otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt.version
+      end
+    end
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ModuleLength
+end

data/lib/langfuse/otel_setup.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+require "opentelemetry/trace/propagation/trace_context"
+require "base64"
+
+module Langfuse
+  # OpenTelemetry initialization and setup
+  #
+  # Handles configuration of the OTel SDK with Langfuse OTLP exporter
+  # when tracing is enabled.
+  #
+  module OtelSetup
+    class << self
+      attr_reader :tracer_provider
+
+      # Initialize OpenTelemetry with Langfuse OTLP exporter
+      #
+      # @param config [Langfuse::Config] The Langfuse configuration
+      # @return [void]
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def setup(config)
+        # Create OTLP exporter configured for Langfuse
+        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+          endpoint: "#{config.base_url}/api/public/otel/v1/traces",
+          headers: build_headers(config.public_key, config.secret_key),
+          compression: "gzip"
+        )
+
+        # Create processor based on async configuration
+        # IMPORTANT: Always use BatchSpanProcessor (even in sync mode) to ensure spans
+        # are exported together, which allows proper parent-child relationship detection
+        processor = if config.tracing_async
+                      # Async: BatchSpanProcessor batches and sends in background
+                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+                        exporter,
+                        max_queue_size: config.batch_size * 2, # Buffer more than batch_size
+                        schedule_delay: config.flush_interval * 1000, # Convert seconds to milliseconds
+                        max_export_batch_size: config.batch_size
+                      )
+                    else
+                      # Sync: BatchSpanProcessor with minimal delay (flushes on force_flush)
+                      # This collects spans from the same trace and exports them together,
+                      # which is critical for correct parent_observation_id calculation
+                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+                        exporter,
+                        max_queue_size: config.batch_size * 2,
+                        schedule_delay: 60_000, # 60 seconds (relies on explicit force_flush)
+                        max_export_batch_size: config.batch_size
+                      )
+                    end
+
+        # Create TracerProvider with processor
+        @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+        @tracer_provider.add_span_processor(processor)
+
+        # Add span processor for propagated attributes
+        # This must be added AFTER the BatchSpanProcessor to ensure attributes are set before export
+        span_processor = SpanProcessor.new
+        @tracer_provider.add_span_processor(span_processor)
+
+        # Set as global tracer provider
+        OpenTelemetry.tracer_provider = @tracer_provider
+
+        # Configure W3C TraceContext propagator if not already set
+        if OpenTelemetry.propagation.is_a?(OpenTelemetry::Context::Propagation::NoopTextMapPropagator)
+          OpenTelemetry.propagation = OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new
+          config.logger.debug("Langfuse: Configured W3C TraceContext propagator")
+        else
+          config.logger.debug("Langfuse: Using existing propagator: #{OpenTelemetry.propagation.class}")
+        end
+
+        mode = config.tracing_async ? "async" : "sync"
+        config.logger.info("Langfuse tracing initialized with OpenTelemetry (#{mode} mode)")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      # Shutdown the tracer provider and flush any pending spans
+      #
+      # @param timeout [Integer] Timeout in seconds
+      # @return [void]
+      def shutdown(timeout: 30)
+        return unless @tracer_provider
+
+        @tracer_provider.shutdown(timeout: timeout)
+        @tracer_provider = nil
+      end
+
+      # Force flush all pending spans
+      #
+      # @param timeout [Integer] Timeout in seconds
+      # @return [void]
+      def force_flush(timeout: 30)
+        return unless @tracer_provider
+
+        @tracer_provider.force_flush(timeout: timeout)
+      end
+
+      # Check if OTel is initialized
+      #
+      # @return [Boolean]
+      def initialized?
+        !@tracer_provider.nil?
+      end
+
+      private
+
+      # Build HTTP headers for Langfuse OTLP endpoint
+      #
+      # @param public_key [String] Langfuse public API key
+      # @param secret_key [String] Langfuse secret API key
+      # @return [Hash] HTTP headers with Basic Auth
+      def build_headers(public_key, secret_key)
+        credentials = "#{public_key}:#{secret_key}"
+        encoded = Base64.strict_encode64(credentials)
+        {
+          "Authorization" => "Basic #{encoded}"
+        }
+      end
+    end
+  end
+end

data/lib/langfuse/prompt_cache.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Langfuse
+  # Simple in-memory cache for prompt data with TTL
+  #
+  # Thread-safe cache implementation for storing prompt responses
+  # with time-to-live expiration.
+  #
+  # @example
+  #   cache = Langfuse::PromptCache.new(ttl: 60)
+  #   cache.set("greeting:1", prompt_data)
+  #   cache.get("greeting:1") # => prompt_data
+  #
+  class PromptCache
+    # Cache entry with data and expiration time
+    CacheEntry = Struct.new(:data, :expires_at) do
+      def expired?
+        Time.now > expires_at
+      end
+    end
+
+    attr_reader :ttl, :max_size
+
+    # Initialize a new cache
+    #
+    # @param ttl [Integer] Time-to-live in seconds (default: 60)
+    # @param max_size [Integer] Maximum cache size (default: 1000)
+    def initialize(ttl: 60, max_size: 1000)
+      @ttl = ttl
+      @max_size = max_size
+      @cache = {}
+      @monitor = Monitor.new
+    end
+
+    # Get a value from the cache
+    #
+    # @param key [String] Cache key
+    # @return [Object, nil] Cached value or nil if not found/expired
+    def get(key)
+      @monitor.synchronize do
+        entry = @cache[key]
+        return nil unless entry
+        return nil if entry.expired?
+
+        entry.data
+      end
+    end
+
+    # Set a value in the cache
+    #
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache
+    # @return [Object] The cached value
+    def set(key, value)
+      @monitor.synchronize do
+        # Evict oldest entry if at max size
+        evict_oldest if @cache.size >= max_size
+
+        expires_at = Time.now + ttl
+        @cache[key] = CacheEntry.new(value, expires_at)
+        value
+      end
+    end
+
+    # Clear the entire cache
+    #
+    # @return [void]
+    def clear
+      @monitor.synchronize do
+        @cache.clear
+      end
+    end
+
+    # Remove expired entries from cache
+    #
+    # @return [Integer] Number of entries removed
+    def cleanup_expired
+      @monitor.synchronize do
+        initial_size = @cache.size
+        @cache.delete_if { |_key, entry| entry.expired? }
+        initial_size - @cache.size
+      end
+    end
+
+    # Get current cache size
+    #
+    # @return [Integer] Number of entries in cache
+    def size
+      @monitor.synchronize do
+        @cache.size
+      end
+    end
+
+    # Check if cache is empty
+    #
+    # @return [Boolean]
+    def empty?
+      @monitor.synchronize do
+        @cache.empty?
+      end
+    end
+
+    # Build a cache key from prompt name and options
+    #
+    # @param name [String] Prompt name
+    # @param version [Integer, nil] Optional version
+    # @param label [String, nil] Optional label
+    # @return [String] Cache key
+    def self.build_key(name, version: nil, label: nil)
+      key = name.to_s
+      key += ":v#{version}" if version
+      key += ":#{label}" if label
+      key
+    end
+
+    private
+
+    # Evict the oldest entry from cache
+    #
+    # @return [void]
+    def evict_oldest
+      return if @cache.empty?
+
+      # Find entry with earliest expiration
+      oldest_key = @cache.min_by { |_key, entry| entry.expires_at }&.first
+      @cache.delete(oldest_key) if oldest_key
+    end
+  end
+end