langfuse-ruby 0.1.2 → 0.1.3

data/examples/connection_config_demo.rb

@@ -10,6 +10,8 @@ puts "\n📋 默认配置信息:"
 puts "   默认主机: #{Langfuse.configuration.host}"
 puts "   默认超时: #{Langfuse.configuration.timeout}秒"
 puts "   默认重试: #{Langfuse.configuration.retries}次"
+puts "   默认刷新间隔: #{Langfuse.configuration.flush_interval}秒"
+puts "   默认自动刷新: #{Langfuse.configuration.auto_flush}"
 
 # 方法 1: 使用测试密钥创建客户端（仅用于演示）
 puts "\n📝 方法 1: 直接参数配置"
@@ -17,7 +19,9 @@ puts '代码示例：'
 puts 'client = Langfuse.new('
 puts "  public_key: 'pk-lf-your-public-key',"
 puts "  secret_key: 'sk-lf-your-secret-key',"
-puts "  host: 'https://us.cloud.langfuse.com'"
+puts "  host: 'https://us.cloud.langfuse.com',"
+puts '  flush_interval: 10,  # 每10秒刷新一次'
+puts '  auto_flush: true     # 启用自动刷新（默认）'
 puts ')'
 
 # 使用测试密钥创建客户端
@@ -31,6 +35,8 @@ puts '✅ 客户端配置成功'
 puts "   主机: #{test_client.host}"
 puts "   超时: #{test_client.timeout}秒"
 puts "   重试: #{test_client.retries}次"
+puts "   刷新间隔: #{test_client.flush_interval}秒"
+puts "   自动刷新: #{test_client.auto_flush}"
 
 # 方法 2: 全局配置
 puts "\n📝 方法 2: 全局配置"
@@ -40,6 +46,8 @@ puts "  config.public_key = 'pk-lf-your-public-key'"
 puts "  config.secret_key = 'sk-lf-your-secret-key'"
 puts "  config.host = 'https://us.cloud.langfuse.com'"
 puts '  config.debug = true'
+puts '  config.flush_interval = 10  # 每10秒刷新一次'
+puts '  config.auto_flush = true    # 启用自动刷新'
 puts 'end'
 
 Langfuse.configure do |config|
@@ -49,6 +57,8 @@ Langfuse.configure do |config|
   config.debug = true
   config.timeout = 60
   config.retries = 5
+  config.flush_interval = 10
+  config.auto_flush = true
 end
 
 global_client = Langfuse.new
@@ -57,6 +67,8 @@ puts "   主机: #{global_client.host}"
 puts "   调试模式: #{global_client.debug}"
 puts "   超时: #{global_client.timeout}秒"
 puts "   重试: #{global_client.retries}次"
+puts "   刷新间隔: #{global_client.flush_interval}秒"
+puts "   自动刷新: #{global_client.auto_flush}"
 
 # 方法 3: 环境变量配置
 puts "\n📝 方法 3: 环境变量配置"
@@ -64,6 +76,8 @@ puts '设置环境变量：'
 puts "export LANGFUSE_PUBLIC_KEY='pk-lf-your-public-key'"
 puts "export LANGFUSE_SECRET_KEY='sk-lf-your-secret-key'"
 puts "export LANGFUSE_HOST='https://us.cloud.langfuse.com'"
+puts 'export LANGFUSE_FLUSH_INTERVAL=10'
+puts 'export LANGFUSE_AUTO_FLUSH=true'
 puts ''
 puts '然后使用：'
 puts 'client = Langfuse.new'

data/examples/event_usage.rb

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+
+require 'langfuse'
+
+# Initialize the Langfuse client
+client = Langfuse.new(
+  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
+  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+)
+
+puts '🎯 Starting event usage example...'
+
+# Example 1: Create a trace and add events
+puts "\n📝 Example 1: Creating events within a trace"
+
+trace = client.trace(
+  name: 'user-workflow',
+  user_id: 'user-123',
+  session_id: 'session-456',
+  input: { action: 'start_workflow' }
+)
+
+puts "Created trace: #{trace.id}"
+
+# Create a generic event
+event1 = trace.event(
+  name: 'user_login',
+  input: { username: 'john_doe', login_method: 'oauth' },
+  output: { success: true, user_id: 'user-123' },
+  metadata: {
+    ip_address: '192.168.1.1',
+    user_agent: 'Mozilla/5.0...'
+  }
+)
+
+puts "Created event: #{event1.id}"
+
+# Create another event with custom level
+event2 = trace.event(
+  name: 'data_processing',
+  input: { data_size: 1024, format: 'json' },
+  output: { processed_records: 100, errors: 0 },
+  level: 'INFO',
+  metadata: {
+    processing_time_ms: 250,
+    memory_usage: '45MB'
+  }
+)
+
+puts "Created event: #{event2.id}"
+
+# Example 2: Creating events from spans
+puts "\n🔗 Example 2: Creating events from spans"
+
+span = trace.span(
+  name: 'data-validation',
+  input: { data: 'raw_data' }
+)
+
+# Create an event within the span
+validation_event = span.event(
+  name: 'validation_check',
+  input: { rules: %w[required format length] },
+  output: { valid: true, warnings: [] },
+  metadata: { validation_time_ms: 15 }
+)
+
+puts "Created span event: #{validation_event.id}"
+
+# End the span
+span.end(output: { validation_result: 'passed' })
+
+# Example 3: Creating events from generations
+puts "\n🤖 Example 3: Creating events from generations"
+
+generation = trace.generation(
+  name: 'text-generation',
+  model: 'gpt-3.5-turbo',
+  input: [{ role: 'user', content: 'Hello, how are you?' }],
+  output: { content: 'I am doing well, thank you!' },
+  usage: { prompt_tokens: 12, completion_tokens: 8, total_tokens: 20 }
+)
+
+# Create an event for content filtering
+filter_event = generation.event(
+  name: 'content_filter',
+  input: { text: 'I am doing well, thank you!' },
+  output: {
+    filtered: false,
+    flags: [],
+    confidence: 0.95
+  },
+  metadata: {
+    filter_model: 'content-filter-v1',
+    processing_time_ms: 5
+  }
+)
+
+puts "Created generation event: #{filter_event.id}"
+
+# Example 4: Error event
+puts "\n❌ Example 4: Error event"
+
+error_event = trace.event(
+  name: 'error_occurred',
+  input: { operation: 'database_query' },
+  output: {
+    error: true,
+    message: 'Connection timeout',
+    code: 'DB_TIMEOUT'
+  },
+  level: 'ERROR',
+  status_message: 'Database connection failed',
+  metadata: {
+    retry_count: 3,
+    last_attempt: Time.now.iso8601
+  }
+)
+
+puts "Created error event: #{error_event.id}"
+
+puts "Trace URL: #{trace.get_url}"
+
+# Example 5: Direct event creation via client
+puts "\n🎯 Example 5: Direct event creation via client"
+
+direct_event = client.event(
+  trace_id: trace.id,
+  name: 'audit_log',
+  input: { action: 'workflow_completed', user_id: 'user-123' },
+  output: { logged: true, log_id: 'audit-789' },
+  metadata: {
+    timestamp: Time.now.iso8601,
+    source: 'audit_system'
+  }
+)
+
+puts "Created direct event: #{direct_event.id}"
+
+puts "\n✅ Event usage example completed!"
+puts 'Check the Langfuse dashboard to see all events in the trace.'
+
+# Flush events to ensure they're sent
+client.flush

data/lib/langfuse/client.rb

@@ -6,22 +6,29 @@ require 'concurrent'
 
 module Langfuse
   class Client
-    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries
+    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush
 
-    def initialize(public_key: nil, secret_key: nil, host: nil, debug: false, timeout: 30, retries: 3)
+    def initialize(public_key: nil, secret_key: nil, host: nil, debug: false, timeout: 30, retries: 3,
+                   flush_interval: nil, auto_flush: nil)
       @public_key = public_key || ENV['LANGFUSE_PUBLIC_KEY'] || Langfuse.configuration.public_key
       @secret_key = secret_key || ENV['LANGFUSE_SECRET_KEY'] || Langfuse.configuration.secret_key
       @host = host || ENV['LANGFUSE_HOST'] || Langfuse.configuration.host
       @debug = debug || Langfuse.configuration.debug
       @timeout = timeout || Langfuse.configuration.timeout
       @retries = retries || Langfuse.configuration.retries
+      @flush_interval = flush_interval || ENV['LANGFUSE_FLUSH_INTERVAL']&.to_i || Langfuse.configuration.flush_interval
+      @auto_flush = if auto_flush.nil?
+                      ENV['LANGFUSE_AUTO_FLUSH'] == 'false' ? false : Langfuse.configuration.auto_flush
+                    else
+                      auto_flush
+                    end
 
       raise AuthenticationError, 'Public key is required' unless @public_key
       raise AuthenticationError, 'Secret key is required' unless @secret_key
 
       @connection = build_connection
       @event_queue = Concurrent::Array.new
-      @flush_thread = start_flush_thread
+      @flush_thread = start_flush_thread if @auto_flush
     end
 
     # Trace operations
@@ -91,6 +98,25 @@ module Langfuse
       )
     end
 
+    # Event operations
+    def event(trace_id:, name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, parent_observation_id: nil, version: nil, **kwargs)
+      Event.new(
+        client: self,
+        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,
+        **kwargs
+      )
+    end
+
     # Prompt operations
     def get_prompt(name, version: nil, label: nil, cache_ttl_seconds: 60)
       cache_key = "prompt:#{name}:#{version}:#{label}"
@@ -158,29 +184,22 @@ module Langfuse
       enqueue_event('score-create', data)
     end
 
-    # HTTP methods
-    def get(path, params = {})
-      request(:get, path, params: params)
-    end
-
-    def post(path, data = {})
-      request(:post, path, json: data)
-    end
-
-    def put(path, data = {})
-      request(:put, path, json: data)
-    end
-
-    def delete(path, params = {})
-      request(:delete, path, params: params)
-    end
-
-    def patch(path, data = {})
-      request(:patch, path, json: data)
-    end
-
     # Event queue management
     def enqueue_event(type, body)
+      # 验证事件类型是否有效
+      valid_types = %w[
+        trace-create
+        generation-create generation-update
+        span-create span-update
+        event-create
+        score-create
+      ]
+
+      unless valid_types.include?(type)
+        puts "Warning: Invalid event type '#{type}'. Skipping event." if @debug
+        return
+      end
+
       event = {
         id: Utils.generate_id,
         type: type,
@@ -198,32 +217,99 @@ module Langfuse
       events = @event_queue.shift(@event_queue.length)
       return if events.empty?
 
-      batch_data = {
-        batch: events,
-        metadata: {
-          batch_size: events.length,
-          sdk_name: 'langfuse-ruby',
-          sdk_version: Langfuse::VERSION
-        }
-      }
+      send_batch(events)
+    end
+
+    def shutdown
+      @flush_thread&.kill if @auto_flush
+      flush unless @event_queue.empty?
+    end
+
+    private
+
+    def debug_event_data(events)
+      return unless @debug
+
+      puts "\n=== Event Data Debug Information ==="
+      events.each_with_index do |event, index|
+        puts "Event #{index + 1}:"
+        puts "  ID: #{event[:id]}"
+        puts "  Type: #{event[:type]}"
+        puts "  Timestamp: #{event[:timestamp]}"
+        puts "  Body keys: #{event[:body]&.keys || 'nil'}"
+
+        # 检查常见的问题
+        puts '  ⚠️  WARNING: Empty or nil type!' if event[:type].nil? || event[:type].to_s.empty?
+
+        puts '  ⚠️  WARNING: Empty body!' if event[:body].nil?
+
+        puts '  ---'
+      end
+      puts "=== End Debug Information ===\n"
+    end
+
+    def send_batch(events)
+      # 调试事件数据
+      debug_event_data(events)
+
+      # 验证事件数据
+      valid_events = events.select do |event|
+        if event[:type].nil? || event[:type].to_s.empty?
+          puts "Warning: Event with empty type detected, skipping: #{event[:id]}" if @debug
+          false
+        elsif event[:body].nil?
+          puts "Warning: Event with empty body detected, skipping: #{event[:id]}" if @debug
+          false
+        else
+          true
+        end
+      end
+
+      if valid_events.empty?
+        puts 'No valid events to send' if @debug
+        return
+      end
+
+      batch_data = build_batch_data(valid_events)
+      puts "Sending batch data: #{batch_data}" if @debug
 
       begin
         response = post('/api/public/ingestion', batch_data)
-        puts "Flushed #{events.length} events" if @debug
+        puts "Flushed #{valid_events.length} events" if @debug
+        response
       rescue StandardError => e
         puts "Failed to flush events: #{e.message}" if @debug
         # Re-queue events on failure
-        events.each { |event| @event_queue << event }
+        valid_events.each { |event| @event_queue << event }
         raise
       end
     end
 
-    def shutdown
-      @flush_thread&.kill
-      flush unless @event_queue.empty?
+    def build_batch_data(events)
+      {
+        batch: events,
+        metadata: Utils.deep_camelize_keys({
+                                             batch_size: events.length,
+                                             sdk_name: 'langfuse-ruby',
+                                             sdk_version: Langfuse::VERSION
+                                           })
+      }
     end
 
-    private
+    def start_flush_thread
+      return unless @auto_flush
+
+      Thread.new do
+        loop do
+          sleep(@flush_interval) # Configurable flush interval
+          begin
+            flush unless @event_queue.empty?
+          rescue StandardError => e
+            puts "Error in flush thread: #{e.message}" if @debug
+          end
+        end
+      end
+    end
 
     def build_connection
       Faraday.new(url: @host) do |conn|
@@ -248,6 +334,27 @@ module Langfuse
       end
     end
 
+    # HTTP methods
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, json: data)
+    end
+
+    def put(path, data = {})
+      request(:put, path, json: data)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, params: params)
+    end
+
+    def patch(path, data = {})
+      request(:patch, path, json: data)
+    end
+
     def request(method, path, params: {}, json: nil)
       retries_left = @retries
 
@@ -293,25 +400,27 @@ module Langfuse
       when 429
         raise RateLimitError, "Rate limit exceeded: #{response.body}"
       when 400..499
-        raise ValidationError, "Client error (#{response.status}): #{response.body}"
+        # 为 400 错误提供更详细的错误信息
+        error_details = ''
+        if response.body.is_a?(Hash) && response.body['error']
+          error_details = "\nError details: #{response.body['error']}"
+        elsif response.body.is_a?(String)
+          error_details = "\nError details: #{response.body}"
+        end
+
+        # 特别处理类型验证错误
+        unless response.body.to_s.include?('invalid_union') || response.body.to_s.include?('discriminator')
+          raise ValidationError, "Client error (#{response.status}): #{response.body}#{error_details}"
+        end
+
+        raise ValidationError,
+              "Event type validation failed (#{response.status}): The event type or structure is invalid. Please check the event format.#{error_details}"
+
       when 500..599
         raise APIError, "Server error (#{response.status}): #{response.body}"
       else
         raise APIError, "Unexpected response (#{response.status}): #{response.body}"
       end
     end
-
-    def start_flush_thread
-      Thread.new do
-        loop do
-          sleep(5) # Flush every 5 seconds
-          begin
-            flush unless @event_queue.empty?
-          rescue StandardError => e
-            puts "Error in flush thread: #{e.message}" if @debug
-          end
-        end
-      end
-    end
   end
 end

data/lib/langfuse/event.rb

@@ -0,0 +1,63 @@
+module Langfuse
+  class Event
+    attr_reader :id, :trace_id, :name, :start_time, :input, :output, :metadata,
+                :level, :status_message, :parent_observation_id, :version, :client
+
+    def initialize(client:, trace_id:, name:, id: nil, start_time: nil, input: nil,
+                   output: nil, metadata: nil, level: nil, status_message: nil,
+                   parent_observation_id: nil, version: nil, **kwargs)
+      @client = client
+      @id = id || Utils.generate_id
+      @trace_id = trace_id
+      @name = name
+      @start_time = start_time || Utils.current_timestamp
+      @input = input
+      @output = output
+      @metadata = metadata || {}
+      @level = level
+      @status_message = status_message
+      @parent_observation_id = parent_observation_id
+      @version = version
+      @kwargs = kwargs
+
+      # Create the event
+      create_event
+    end
+
+    def to_dict
+      {
+        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
+      }.merge(@kwargs).compact
+    end
+
+    private
+
+    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
+      }.merge(@kwargs).compact
+
+      @client.enqueue_event('event-create', data)
+    end
+  end
+end

data/lib/langfuse/generation.rb

@@ -103,6 +103,23 @@ module Langfuse
       )
     end
 
+    def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, version: nil, **kwargs)
+      @client.event(
+        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: @id,
+        version: version,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         observation_id: @id,
@@ -142,49 +159,11 @@ module Langfuse
     private
 
     def create_generation
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        end_time: @end_time,
-        completion_start_time: @completion_start_time,
-        model: @model,
-        model_parameters: @model_parameters,
-        input: @input,
-        output: @output,
-        usage: @usage,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('generation-create', data)
+      @client.enqueue_event('generation-create', to_dict)
     end
 
     def update_generation
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        end_time: @end_time,
-        completion_start_time: @completion_start_time,
-        model: @model,
-        model_parameters: @model_parameters,
-        input: @input,
-        output: @output,
-        usage: @usage,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('generation-update', data)
+      @client.enqueue_event('generation-update', to_dict)
     end
   end
 end

data/lib/langfuse/span.rb

@@ -91,6 +91,23 @@ module Langfuse
       )
     end
 
+    def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, version: nil, **kwargs)
+      @client.event(
+        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: @id,
+        version: version,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         observation_id: @id,