langfuse-ruby 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d97c16de061cdf52403a05086a90aaac149b9fe9dc6d771e36709e763abcb3eb
-  data.tar.gz: c254257501aff83671377cc50ea8f25c143d8dca6fa0f40d157fcfa6eb3d75b9
+  metadata.gz: af3d00eedfb953a5bdc8f1a99d272debe050ed43cf160329c907cd209b28e042
+  data.tar.gz: 3a4c6ac469fa7874c0e310b059029bcaa879e6f048abfd902097dfde1d7ed3fe
 SHA512:
-  metadata.gz: f2cf7c8a6d72bb5a81b73ba6a5a110e9e6312b09e9a790a14d566a41b1e7d4a8ce40c53fb8d0d74b4c12c9cd06bd20e03680b6829505f69aa7b80dee3ecf6750
-  data.tar.gz: c880f859cf2f0d6fc9586ceada7c7488ff25a8be4c3fbf4740443477e592b8eee20895e24c69c371a8f0a96c60fd40d1a66de2126b762378ea41115665de3666
+  metadata.gz: 2b74bc9c6d80fe4f09c20f38345bb0244b801acc07b770674b85778c21ad0b66b0fabe07206071c52f8780531dce49799b6db8d67b1cee662432ab8f5ae81258
+  data.tar.gz: 9901d034719eab0f2c082962cf36396591db46b33f54665c3dcb9cfdd9f22c8f96ba1b71b7296d4131e20a43355e57375e70020d734a43f810d05a802e207e3f

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+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
+- Improved error handling for `get_prompt` method when prompt doesn't exist
+- Better error messages for 404 responses that return HTML instead of JSON
+- Enhanced debugging capabilities with detailed request/response logging
+
+### Added
+- Comprehensive troubleshooting guide for prompt management issues
+- Better detection of HTML responses vs JSON responses
+- More specific error types for different failure scenarios
+
+### Changed
+- Updated gemspec metadata to avoid RubyGems warnings
+- Improved documentation with clearer error handling examples
+
+## [0.1.0] - 2025-01-12
+
+### Added
+- Initial release of Langfuse Ruby SDK
+- Complete tracing capabilities with traces, spans, and generations
+- Prompt management with versioning and caching
+- Built-in evaluators (exact match, similarity, length, contains, regex)
+- Custom scoring and evaluation pipeline support
+- Async event processing with automatic batching
+- Comprehensive error handling and validation
+- Framework integration examples (Rails, Sidekiq)
+- Full test suite with RSpec
+- Documentation and examples
+
+### Features
+- **Tracing**: Full observability for LLM applications
+- **Prompt Management**: Version control and deployment of prompts
+- **Evaluation**: Multiple built-in evaluators and custom scoring
+- **Async Processing**: Background event processing with batching
+- **Type Safety**: Comprehensive error handling
+- **Integration**: Easy integration with Ruby frameworks 

data/Gemfile

@@ -1,9 +1,9 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in langfuse.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "rubocop", "~> 1.21"
-gem "yard", "~> 0.9"
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.21'
+gem 'yard', '~> 0.9'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.1)
+    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/PUBLISH_GUIDE.md

@@ -108,10 +108,10 @@ chmod 0600 ~/.gem/credentials
 
 ```bash
 # 构建最新版本
-gem build langfuse.gemspec
+gem build langfuse-ruby.gemspec
 
 # 发布到 RubyGems
-gem push langfuse-ruby-0.1.0.gem
+gem push langfuse-ruby-0.1.x.gem
 ```
 
 ## 📊 发布后验证

data/docs/README.md

@@ -7,10 +7,6 @@
 ### 开发和发布
 - [📋 发布指南](PUBLISH_GUIDE.md) - 详细的 gem 发布流程
 - [✅ 发布检查清单](RELEASE_CHECKLIST.md) - 发布前的检查项目
-- [📝 变更日志](CHANGELOG.md) - 版本更新记录
-
-### 项目概览
-- [📊 项目总结](PROJECT_SUMMARY.md) - 项目整体介绍
 - [🎯 最终总结](FINAL_SUMMARY.md) - 项目完成情况总结
 
 ## 🔗 相关链接

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: 初始版本