langfuse-ruby 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb8cc1f797c0b240830c5f909665dde61bb8a5540f1db8a04393ae0d741ee44
-  data.tar.gz: bc5b9e1dc24e2861ac66955bec4dccd25bbadaf1a3c5f59ddbacd784a50b2180
+  metadata.gz: af3d00eedfb953a5bdc8f1a99d272debe050ed43cf160329c907cd209b28e042
+  data.tar.gz: 3a4c6ac469fa7874c0e310b059029bcaa879e6f048abfd902097dfde1d7ed3fe
 SHA512:
-  metadata.gz: d5486239447652d3b97eb6200bc2f24ee829bef24da86409747f6a250fcc1126ce68841673b0e67da56a75e08ff4ec1bc9edf4b241c3431b855abdf2befdd7b9
-  data.tar.gz: 88b61075d0a394629dec59bbec509a7f4c80b0269a887dcef866b3a8a250fd75b362fe84fc6247e72b5305935702a7175c1db825461bb05270145912d6e8f79e
+  metadata.gz: 2b74bc9c6d80fe4f09c20f38345bb0244b801acc07b770674b85778c21ad0b66b0fabe07206071c52f8780531dce49799b6db8d67b1cee662432ab8f5ae81258
+  data.tar.gz: 9901d034719eab0f2c082962cf36396591db46b33f54665c3dcb9cfdd9f22c8f96ba1b71b7296d4131e20a43355e57375e70020d734a43f810d05a802e207e3f

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Added support for `event-create` event type in Langfuse ingestion API
+- New `Event` class for creating generic events within traces, spans, and generations
+- Added `event()` method to `Client`, `Trace`, `Span`, and `Generation` classes
+- Enhanced event validation to include all supported Langfuse event types
+- New example file `examples/event_usage.rb` demonstrating event functionality
+
+## [0.1.2] - 2025-01-13
+
+### Added
+- Enhanced event data validation and debugging capabilities
+- More detailed error messages for event structure validation failures
+
 ## [0.1.1] - 2025-01-12
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.2)
+    langfuse-ruby (0.1.3)
       concurrent-ruby (~> 1.0)
       faraday (~> 2.0)
       faraday-net_http (~> 3.0)

data/README.md

@@ -10,6 +10,7 @@ Ruby SDK for [Langfuse](https://langfuse.com) - the open-source LLM engineering
 - 🔍 **Tracing**: Complete observability for LLM applications with traces, spans, and generations
 - 📝 **Prompt Management**: Version control and deployment of prompts with caching
 - 📊 **Evaluation**: Built-in evaluators and custom scoring capabilities
+- 🎯 **Events**: Generic event tracking for custom application events and logging
 - 🚀 **Async Processing**: Background event processing with automatic batching
 - 🔒 **Type Safety**: Comprehensive error handling and validation
 - 🎯 **Framework Integration**: Easy integration with popular Ruby frameworks
@@ -66,7 +67,6 @@ trace = client.trace(
   name: "chat-completion",
   user_id: "user123",
   session_id: "session456",
-  input: { message: "Hello, world!" },
   metadata: { environment: "production" }
 )
 
@@ -75,15 +75,10 @@ generation = trace.generation(
   name: "openai-completion",
   model: "gpt-3.5-turbo",
   input: [{ role: "user", content: "Hello, world!" }],
-  output: { content: "Hello! How can I help you today?" },
-  usage: { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 },
   model_parameters: { temperature: 0.7, max_tokens: 100 }
 )
 
-# Update trace with final output
-trace.update(
-  output: { response: "Hello! How can I help you today?" }
-)
+generation.end(output: 'Hello! How can I help you today?', usage: { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 })
 
 # Flush events (optional - happens automatically)
 client.flush
@@ -130,12 +125,40 @@ llm_gen = answer_span.generation(
   input: [
     { role: "system", content: "Answer based on context" },
     { role: "user", content: "What is machine learning?" }
-  ],
-  output: { content: "Machine learning is a subset of AI..." },
-  usage: { prompt_tokens: 50, completion_tokens: 30, total_tokens: 80 }
+  ]
 )
 
-answer_span.end(output: { answer: "Machine learning is a subset of AI..." })
+answer_span.end(output: { answer: "Machine learning is a subset of AI..." }, usage: { prompt_tokens: 50, completion_tokens: 30, total_tokens: 80 })
+```
+
+## Events
+
+Create generic events for custom application events and logging:
+
+```ruby
+# Create events from trace
+event = trace.event(
+  name: "user_action",
+  input: { action: "login", user_id: "123" },
+  output: { success: true },
+  metadata: { ip: "192.168.1.1" }
+)
+
+# Create events from spans or generations
+validation_event = span.event(
+  name: "validation_check",
+  input: { rules: ["required", "format"] },
+  output: { valid: true, warnings: [] }
+)
+
+# Direct event creation
+event = client.event(
+  trace_id: trace.id,
+  name: "audit_log",
+  input: { operation: "data_export" },
+  output: { status: "completed" },
+  level: "INFO"
+)
 ```
 
 ## Prompt Management
@@ -304,7 +327,9 @@ client = Langfuse.new(
   host: "https://your-instance.langfuse.com",
   debug: true,        # Enable debug logging
   timeout: 30,        # Request timeout in seconds
-  retries: 3          # Number of retry attempts
+  retries: 3,         # Number of retry attempts
+  flush_interval: 30, # Event flush interval in seconds (default: 5)
+  auto_flush: true    # Enable automatic flushing (default: true)
 )
 ```
 
@@ -316,6 +341,76 @@ You can also configure the client using environment variables:
 export LANGFUSE_PUBLIC_KEY="pk-lf-..."
 export LANGFUSE_SECRET_KEY="sk-lf-..."
 export LANGFUSE_HOST="https://cloud.langfuse.com"
+export LANGFUSE_FLUSH_INTERVAL=5
+export LANGFUSE_AUTO_FLUSH=true
+```
+
+### Automatic Flush Control
+
+By default, the Langfuse client automatically flushes events to the server at regular intervals using a background thread. You can control this behavior:
+
+#### Enable/Disable Auto Flush
+
+```ruby
+# Enable automatic flushing (default)
+client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  auto_flush: true,
+  flush_interval: 5  # Flush every 5 seconds
+)
+
+# Disable automatic flushing for manual control
+client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  auto_flush: false
+)
+
+# Manual flush when auto_flush is disabled
+client.flush
+```
+
+#### Global Configuration
+
+```ruby
+Langfuse.configure do |config|
+  config.auto_flush = false  # Disable auto flush globally
+  config.flush_interval = 10
+end
+```
+
+#### Environment Variable
+
+```bash
+export LANGFUSE_AUTO_FLUSH=false
+```
+
+#### Use Cases
+
+**Auto Flush Enabled (Default)**
+- Best for most applications
+- Events are sent automatically
+- No manual management required
+
+**Auto Flush Disabled**
+- Better performance for batch operations
+- More control over when events are sent
+- Requires manual flush calls
+- Useful for high-frequency operations
+
+```ruby
+# Example: Batch processing with manual flush
+client = Langfuse.new(auto_flush: false)
+
+# Process many items
+1000.times do |i|
+  trace = client.trace(name: "batch-item-#{i}")
+  # ... process item
+end
+
+# Flush all events at once
+client.flush
 ```
 
 ### Shutdown
@@ -356,9 +451,7 @@ class ChatController < ApplicationController
     
     # Your LLM logic here
     response = generate_response(params[:message])
-    
-    trace.update(output: { response: response })
-    
+
     render json: { response: response }
   end
 end
@@ -370,19 +463,17 @@ end
 class LLMProcessingJob < ApplicationJob
   def perform(user_id, message)
     client = Langfuse.new
-    
+
     trace = client.trace(
       name: "background-llm-processing",
       user_id: user_id,
       input: { message: message },
       metadata: { job_class: self.class.name }
     )
-    
+
     # Process with LLM
     result = process_with_llm(message)
-    
-    trace.update(output: result)
-    
+
     # Ensure events are flushed
     client.flush
   end

data/docs/TYPE_VALIDATION_TROUBLESHOOTING.md

@@ -0,0 +1,202 @@
+# 类型验证错误故障排除指南
+
+## 问题描述
+
+当您遇到以下错误时：
+
+```json
+{
+  "id": "xxx",
+  "status": 400,
+  "message": "Invalid request data",
+  "error": [
+    {
+      "code": "invalid_union",
+      "errors": [],
+      "note": "No matching discriminator", 
+      "path": ["type"],
+      "message": "Invalid input"
+    }
+  ]
+}
+```
+
+这表示 Langfuse 服务器端的 API 验证发现事件的 `type` 字段不符合预期的格式。
+
+## 根本原因
+
+1. **事件类型无效**: 发送的事件类型不在服务器端支持的列表中
+2. **事件数据结构错误**: 事件的数据结构不符合对应类型的要求
+3. **数据序列化问题**: 事件数据在序列化过程中出现问题
+
+## 常见修复案例
+
+### 1. 事件类型无效
+
+```ruby
+client.trace(name: "my-trace", user_id: "user-123", input: { query: "Hello" })
+```
+
+## 解决方案
+
+### 1. 启用调试模式
+
+```ruby
+client = Langfuse.new(
+  public_key: "your-key",
+  secret_key: "your-secret",
+  debug: true  # 启用调试模式
+)
+```
+
+调试模式会显示：
+- 发送的事件类型
+- 事件数据结构
+- 详细的错误信息
+
+### 2. 检查支持的事件类型
+
+当前支持的事件类型：
+- `trace-create`
+- `generation-create`
+- `generation-update`
+- `span-create`
+- `span-update`
+- `event-create`
+- `score-create`
+
+### 3. 验证事件数据
+
+确保事件数据包含必要的字段：
+
+#### Trace 事件
+```ruby
+{
+  id: "uuid",
+  name: "trace-name",
+  user_id: "user-id",
+  input: { ... },
+  metadata: { ... },
+  tags: [...],
+  timestamp: "2025-01-01T00:00:00.000Z"
+}
+```
+
+#### Generation 事件
+```ruby
+{
+  id: "uuid",
+  trace_id: "trace-uuid",
+  name: "generation-name",
+  model: "gpt-3.5-turbo",
+  input: [...],
+  output: { ... },
+  usage: { ... },
+  metadata: { ... }
+}
+```
+
+#### Span 事件
+```ruby
+{
+  id: "uuid",
+  trace_id: "trace-uuid",
+  name: "span-name",
+  start_time: "2025-01-01T00:00:00.000Z",
+  end_time: "2025-01-01T00:00:01.000Z",
+  input: { ... },
+  output: { ... },
+  metadata: { ... }
+}
+```
+
+#### Event 事件
+```ruby
+
+```ruby
+
+```
+
+#### Score 事件
+```ruby
+
+```
+
+### 4. 检查网络和认证
+
+确保：
+- API 密钥正确
+- 网络连接正常
+- 服务器端点可访问
+
+### 5. 使用错误处理
+
+```ruby
+begin
+  client.flush
+rescue Langfuse::ValidationError => e
+  if e.message.include?('Event type validation failed')
+    puts "类型验证错误: #{e.message}"
+    # 检查事件数据格式
+  else
+    puts "其他验证错误: #{e.message}"
+  end
+rescue Langfuse::APIError => e
+  puts "API 错误: #{e.message}"
+end
+```
+
+## 预防措施
+
+1. **使用官方 SDK 方法**: 避免直接构造事件数据
+2. **数据验证**: 在发送前验证数据完整性
+3. **错误监控**: 实施适当的错误处理和监控
+4. **测试环境**: 在测试环境中验证集成
+5. **保持更新**: 定期更新 SDK 到最新版本
+
+## 示例代码
+
+```ruby
+# 正确的使用方式
+client = Langfuse.new(
+  public_key: "pk-lf-xxx",
+  secret_key: "sk-lf-xxx",
+  debug: true
+)
+
+# 创建 trace
+trace = client.trace(
+  name: "my-trace",
+  user_id: "user-123",
+  input: { query: "Hello" }
+)
+
+# 创建 generation
+generation = trace.generation(
+  name: "my-generation",
+  model: "gpt-3.5-turbo",
+  input: [{ role: "user", content: "Hello" }],
+  output: { content: "Hi there!" }
+)
+
+# 安全地刷新事件
+begin
+  client.flush
+  puts "事件发送成功"
+rescue => e
+  puts "发送失败: #{e.message}"
+end
+```
+
+## 联系支持
+
+如果问题持续存在，请提供：
+1. 完整的错误消息
+2. 调试模式的输出
+3. 相关的代码片段
+4. SDK 版本信息
+
+## 更新日志
+
+- v0.1.1: 改进了错误消息的可读性
+- v0.1.0: 初始版本 

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