langfuse-ruby 0.1.1 → 0.1.3

data/examples/auto_flush_control.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langfuse'
+
+puts '🚀 Langfuse Ruby SDK 自动刷新控制演示'
+puts '=' * 50
+
+# 示例 1: 启用自动刷新（默认行为）
+puts "\n📝 示例 1: 启用自动刷新（默认行为）"
+puts '代码示例：'
+puts 'client = Langfuse.new('
+puts "  public_key: 'pk-lf-your-public-key',"
+puts "  secret_key: 'sk-lf-your-secret-key',"
+puts '  auto_flush: true  # 默认为 true，可以省略'
+puts ')'
+
+client_auto = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key',
+  auto_flush: true,
+  flush_interval: 2 # 2秒刷新一次用于演示
+)
+
+puts '✅ 自动刷新客户端创建成功'
+puts "   自动刷新: #{client_auto.auto_flush}"
+puts "   刷新间隔: #{client_auto.flush_interval}秒"
+
+# 创建一些事件
+trace_auto = client_auto.trace(
+  name: 'auto-flush-demo',
+  input: { message: '这是自动刷新演示' },
+  metadata: { demo: true }
+)
+
+puts '✅ 创建了 trace，将在后台自动刷新'
+
+# 示例 2: 禁用自动刷新
+puts "\n📝 示例 2: 禁用自动刷新"
+puts '代码示例：'
+puts 'client = Langfuse.new('
+puts "  public_key: 'pk-lf-your-public-key',"
+puts "  secret_key: 'sk-lf-your-secret-key',"
+puts '  auto_flush: false  # 禁用自动刷新'
+puts ')'
+
+client_manual = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key',
+  auto_flush: false
+)
+
+puts '✅ 手动刷新客户端创建成功'
+puts "   自动刷新: #{client_manual.auto_flush}"
+puts "   刷新间隔: #{client_manual.flush_interval}秒（不会自动刷新）"
+
+# 创建一些事件
+trace_manual = client_manual.trace(
+  name: 'manual-flush-demo',
+  input: { message: '这是手动刷新演示' },
+  metadata: { demo: true }
+)
+
+generation_manual = trace_manual.generation(
+  name: 'manual-generation',
+  model: 'gpt-3.5-turbo',
+  input: [{ role: 'user', content: 'Hello!' }],
+  output: { content: '你好！' },
+  usage: { prompt_tokens: 5, completion_tokens: 3, total_tokens: 8 }
+)
+
+puts '✅ 创建了 trace 和 generation，需要手动刷新'
+puts "   事件队列长度: #{client_manual.instance_variable_get(:@event_queue).length}"
+
+# 手动刷新（离线模式，不实际发送）
+puts "\n🔄 手动刷新事件（离线模式）..."
+puts '   注意：在实际应用中，这里会发送事件到 Langfuse 服务器'
+puts '   当前为演示模式，不会实际发送请求'
+# client_manual.flush  # 注释掉以避免网络请求
+puts "   事件队列长度: #{client_manual.instance_variable_get(:@event_queue).length}"
+
+# 示例 3: 通过全局配置控制
+puts "\n📝 示例 3: 通过全局配置控制"
+puts '代码示例：'
+puts 'Langfuse.configure do |config|'
+puts "  config.public_key = 'pk-lf-your-public-key'"
+puts "  config.secret_key = 'sk-lf-your-secret-key'"
+puts '  config.auto_flush = false  # 全局禁用自动刷新'
+puts '  config.flush_interval = 10'
+puts 'end'
+
+Langfuse.configure do |config|
+  config.public_key = 'test-public-key'
+  config.secret_key = 'test-secret-key'
+  config.auto_flush = false
+  config.flush_interval = 10
+end
+
+client_global = Langfuse.new
+puts '✅ 全局配置客户端创建成功'
+puts "   自动刷新: #{client_global.auto_flush}"
+puts "   刷新间隔: #{client_global.flush_interval}秒"
+
+# 示例 4: 通过环境变量控制
+puts "\n📝 示例 4: 通过环境变量控制"
+puts '设置环境变量：'
+puts "export LANGFUSE_PUBLIC_KEY='pk-lf-your-public-key'"
+puts "export LANGFUSE_SECRET_KEY='sk-lf-your-secret-key'"
+puts 'export LANGFUSE_AUTO_FLUSH=false'
+puts 'export LANGFUSE_FLUSH_INTERVAL=15'
+puts ''
+puts '然后使用：'
+puts 'client = Langfuse.new'
+
+# 模拟环境变量
+ENV['LANGFUSE_AUTO_FLUSH'] = 'false'
+ENV['LANGFUSE_FLUSH_INTERVAL'] = '15'
+
+client_env = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key'
+)
+
+puts '✅ 环境变量配置客户端创建成功'
+puts "   自动刷新: #{client_env.auto_flush}"
+puts "   刷新间隔: #{client_env.flush_interval}秒"
+
+# 清理环境变量
+ENV.delete('LANGFUSE_AUTO_FLUSH')
+ENV.delete('LANGFUSE_FLUSH_INTERVAL')
+
+# 示例 5: 混合使用场景
+puts "\n📝 示例 5: 混合使用场景"
+puts '在某些情况下，您可能希望：'
+puts '1. 大部分时间使用自动刷新'
+puts '2. 在批量操作时临时禁用自动刷新'
+puts '3. 在操作完成后手动刷新'
+
+# 批量操作示例
+puts "\n🔄 批量操作演示..."
+batch_client = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key',
+  auto_flush: false # 禁用自动刷新以提高批量操作性能
+)
+
+# 批量创建多个 traces
+traces = []
+10.times do |i|
+  trace = batch_client.trace(
+    name: "batch-trace-#{i}",
+    input: { batch_id: i },
+    metadata: { batch_operation: true }
+  )
+  traces << trace
+end
+
+puts "✅ 批量创建了 #{traces.length} 个 traces"
+puts "   事件队列长度: #{batch_client.instance_variable_get(:@event_queue).length}"
+
+# 批量操作完成后手动刷新（离线模式）
+puts "\n🔄 批量操作完成，执行手动刷新（离线模式）..."
+puts '   注意：在实际应用中，这里会发送所有事件到 Langfuse 服务器'
+# batch_client.flush  # 注释掉以避免网络请求
+puts "   事件队列长度: #{batch_client.instance_variable_get(:@event_queue).length}（未发送）"
+
+# 使用建议
+puts "\n💡 使用建议:"
+puts '1. 默认情况下保持 auto_flush=true，适合大多数应用场景'
+puts '2. 在批量操作或高频操作时，考虑设置 auto_flush=false'
+puts '3. 禁用自动刷新时，记得在适当的时机调用 client.flush'
+puts '4. 应用关闭前，务必调用 client.shutdown 确保所有事件都被发送'
+puts '5. 可以通过环境变量在不同环境中控制刷新行为'
+
+# 性能对比
+puts "\n⚡ 性能对比:"
+puts '自动刷新模式：'
+puts '  - 优点：无需手动管理，事件及时发送'
+puts '  - 缺点：后台线程消耗资源，可能影响高频操作性能'
+puts ''
+puts '手动刷新模式：'
+puts '  - 优点：更好的性能控制，适合批量操作'
+puts '  - 缺点：需要手动管理刷新时机，容易遗漏'
+
+# 等待一下让自动刷新客户端工作
+puts "\n⏳ 等待自动刷新客户端工作..."
+sleep(3)
+
+# 关闭所有客户端（离线模式）
+puts "\n🔒 关闭所有客户端（离线模式）..."
+puts '   注意：在实际应用中，shutdown 会确保所有事件都被发送'
+# 在演示模式下，我们只终止后台线程而不发送请求
+client_auto.instance_variable_get(:@flush_thread)&.kill
+client_manual.instance_variable_get(:@flush_thread)&.kill
+client_global.instance_variable_get(:@flush_thread)&.kill
+client_env.instance_variable_get(:@flush_thread)&.kill
+batch_client.instance_variable_get(:@flush_thread)&.kill
+
+puts "\n🎉 自动刷新控制演示完成！"
+puts ''
+puts '📚 总结：'
+puts '现在您可以在应用层面灵活控制 Langfuse 的自动刷新行为：'
+puts '- 通过构造函数参数 auto_flush 控制'
+puts '- 通过全局配置 Langfuse.configure 控制'
+puts '- 通过环境变量 LANGFUSE_AUTO_FLUSH 控制'
+puts '- 根据不同场景选择合适的刷新策略'

data/examples/basic_tracing.rb

@@ -47,11 +47,6 @@ generation = trace.generation(
 
 puts "Created generation: #{generation.id}"
 
-# Update trace with final output
-trace.update(
-  output: { response: "I'm doing well, thank you! How can I help you today?" }
-)
-
 puts "Trace URL: #{trace.get_url}"
 
 # Example 2: Nested spans for complex workflow
@@ -130,13 +125,6 @@ answer_span.end(
   }
 )
 
-# Update workflow trace
-workflow_trace.update(
-  output: {
-    answer: 'Machine learning is a subset of artificial intelligence that enables computers to learn and improve from experience without being explicitly programmed. ML algorithms identify patterns in data and use these patterns to make predictions or decisions.'
-  }
-)
-
 puts "Workflow trace URL: #{workflow_trace.get_url}"
 
 # Example 3: Adding scores and evaluations

data/examples/connection_config_demo.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langfuse'
+
+puts '🚀 Langfuse Ruby SDK 连接配置演示'
+puts '=' * 50
+
+# 显示默认配置
+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: 直接参数配置"
+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 '  flush_interval: 10,  # 每10秒刷新一次'
+puts '  auto_flush: true     # 启用自动刷新（默认）'
+puts ')'
+
+# 使用测试密钥创建客户端
+test_client = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key',
+  host: 'https://us.cloud.langfuse.com'
+)
+
+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: 全局配置"
+puts '代码示例：'
+puts 'Langfuse.configure do |config|'
+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|
+  config.public_key = 'test-public-key'
+  config.secret_key = 'test-secret-key'
+  config.host = 'https://us.cloud.langfuse.com'
+  config.debug = true
+  config.timeout = 60
+  config.retries = 5
+  config.flush_interval = 10
+  config.auto_flush = true
+end
+
+global_client = Langfuse.new
+puts '✅ 全局配置成功'
+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: 环境变量配置"
+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'
+
+if ENV['LANGFUSE_PUBLIC_KEY'] && ENV['LANGFUSE_SECRET_KEY']
+  env_client = Langfuse.new
+  puts '✅ 环境变量配置成功'
+  puts "   主机: #{env_client.host}"
+else
+  puts '⚠️  环境变量未设置，跳过此示例'
+end
+
+# 连接配置详情
+puts "\n🔧 连接配置详情:"
+puts '根据 Langfuse 官方文档:'
+puts '1. 认证方式: HTTP Basic Auth'
+puts '2. 用户名: Langfuse Public Key (pk-lf-...)'
+puts '3. 密码: Langfuse Secret Key (sk-lf-...)'
+puts '4. 默认服务器: https://us.cloud.langfuse.com'
+puts '5. 内容类型: application/json'
+puts "6. User-Agent: langfuse-ruby/#{Langfuse::VERSION}"
+
+# 创建测试 trace（不发送到服务器）
+puts "\n🧪 创建测试 Trace（离线）:"
+begin
+  trace = test_client.trace(
+    name: 'connection-test',
+    user_id: 'demo-user',
+    input: { message: '测试连接配置' },
+    metadata: { demo: true }
+  )
+
+  puts '✅ Trace 创建成功'
+  puts "   ID: #{trace.id}"
+  puts "   名称: #{trace.name}"
+  puts "   用户ID: #{trace.user_id}"
+
+  # 添加 generation
+  generation = trace.generation(
+    name: 'demo-generation',
+    model: 'gpt-3.5-turbo',
+    input: [{ role: 'user', content: 'Hello!' }],
+    output: { content: '你好！' },
+    usage: { prompt_tokens: 5, completion_tokens: 3, total_tokens: 8 }
+  )
+
+  puts '✅ Generation 创建成功'
+  puts "   ID: #{generation.id}"
+  puts "   模型: #{generation.model}"
+rescue StandardError => e
+  puts "❌ 测试失败: #{e.message}"
+end
+
+puts "\n📚 使用提示:"
+puts "1. 替换示例中的 'test-public-key' 和 'test-secret-key' 为您的真实 API 密钥"
+puts '2. 确保网络连接正常'
+puts '3. 启用 debug 模式可以查看详细的请求日志'
+puts '4. 调用 client.flush 来发送事件到服务器'
+puts '5. 使用 client.shutdown 来优雅地关闭客户端'
+
+puts "\n🎉 连接配置演示完成！"

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