langfuse-ruby 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb8cc1f797c0b240830c5f909665dde61bb8a5540f1db8a04393ae0d741ee44
-  data.tar.gz: bc5b9e1dc24e2861ac66955bec4dccd25bbadaf1a3c5f59ddbacd784a50b2180
+  metadata.gz: 0bb59924d3a9dcb1cb99841c6d07dd1277838ffee389d13ada1c8b03cafeb524
+  data.tar.gz: c5ba1846cd51fc3dc82fb43dd335d88394549652531a5243101ccd43ef71b3fa
 SHA512:
-  metadata.gz: d5486239447652d3b97eb6200bc2f24ee829bef24da86409747f6a250fcc1126ce68841673b0e67da56a75e08ff4ec1bc9edf4b241c3431b855abdf2befdd7b9
-  data.tar.gz: 88b61075d0a394629dec59bbec509a7f4c80b0269a887dcef866b3a8a250fd75b362fe84fc6247e72b5305935702a7175c1db825461bb05270145912d6e8f79e
+  metadata.gz: 9e448848c65cb8cd6f7ab7e4e566787bcab4aa8c43f20da7cc7a7a39e24e888c734c23644682f080635a0288b40fc4e3e169d8576445fdd07dde8d676faaccca
+  data.tar.gz: 9d9d1e88bf2e1161bd1d7f316e17600904169344b679839992a227eb35ac48e7edbe188ce782e3757f9f03a8a39104eac8c171a23f7bdc0c54b707754dfd87e8

data/.github/workflows/ci.yml

@@ -2,17 +2,18 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, master ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, master ]
 
 jobs:
   test:
     runs-on: ubuntu-latest
+    
     strategy:
       matrix:
-        ruby-version: ['2.7', '3.0', '3.1', '3.2']
-
+        ruby-version: ['2.7', '3.0', '3.1', '3.2', '3.3']
+    
     steps:
     - uses: actions/checkout@v4
     
@@ -28,11 +29,14 @@ jobs:
     - name: Run offline tests
       run: ruby test_offline.rb
     
-    - name: Check gem build
-      run: gem build langfuse.gemspec
-
-  lint:
+    - name: Run RuboCop
+      run: bundle exec rubocop
+      continue-on-error: true
+  
+  build:
     runs-on: ubuntu-latest
+    needs: test
+    
     steps:
     - uses: actions/checkout@v4
     
@@ -42,6 +46,8 @@ jobs:
         ruby-version: '3.2'
         bundler-cache: true
     
-    - name: Run RuboCop
-      run: bundle exec rubocop
-      continue-on-error: true 
+    - name: Build gem
+      run: gem build langfuse-ruby.gemspec
+    
+    - name: Verify gem can be installed
+      run: gem install langfuse-ruby-*.gem 

data/CHANGELOG.md

@@ -5,7 +5,42 @@ 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).
 
-## [0.1.1] - 2025-01-12
+## [Unreleased]
+
+## [0.1.4] - 2025-07-29
+
+### Added
+- Added support for `trace-update` event type in Langfuse ingestion API
+- 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
+
+### Fixed
+- Improved offline test error handling and authentication validation
+- Enhanced error handling tests with proper configuration management
+- Fixed prompt template validation tests in offline mode
+- Better error message handling for authentication failures
+
+### Improved
+- More comprehensive error handling test coverage
+- Better test isolation and cleanup procedures
+- Enhanced debugging capabilities for offline testing
+
+## [0.1.3] - 2025-07-13
+
+### Fixed
+- Enhanced event data validation and debugging capabilities
+- More detailed error messages for event structure validation failures
+
+## [0.1.2] - 2025-07-12
+
+### Fixed
+- Enhanced event data validation and debugging capabilities
+- More detailed error messages for event structure validation failures
+
+## [0.1.1] - 2025-07-12
 
 ### Fixed
 - Improved error handling for `get_prompt` method when prompt doesn't exist
@@ -21,7 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated gemspec metadata to avoid RubyGems warnings
 - Improved documentation with clearer error handling examples
 
-## [0.1.0] - 2025-01-12
+## [0.1.0] - 2025-07-12
 
 ### Added
 - Initial release of Langfuse Ruby SDK

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.2)
+    langfuse-ruby (0.1.4)
       concurrent-ruby (~> 1.0)
-      faraday (~> 2.0)
-      faraday-net_http (~> 3.0)
+      faraday (>= 1.8, < 3.0)
+      faraday-net_http (>= 1.0, < 4.0)
       json (~> 2.0)
 
 GEM

data/README.md

@@ -1,7 +1,9 @@
 # Langfuse Ruby SDK
 
 [![Gem Version](https://badge.fury.io/rb/langfuse-ruby.svg)](https://badge.fury.io/rb/langfuse-ruby)
-[![Build Status](https://github.com/ai-firstly/langfuse-ruby/workflows/CI/badge.svg)](https://github.com/ai-firstly/langfuse-ruby/actions)
+[![CI](https://github.com/ai-firstly/langfuse-ruby/workflows/CI/badge.svg)](https://github.com/ai-firstly/langfuse-ruby/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Ruby SDK for [Langfuse](https://langfuse.com) - the open-source LLM engineering platform. This SDK provides comprehensive tracing, prompt management, and evaluation capabilities for LLM applications.
 
@@ -10,6 +12,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 +69,6 @@ trace = client.trace(
   name: "chat-completion",
   user_id: "user123",
   session_id: "session456",
-  input: { message: "Hello, world!" },
   metadata: { environment: "production" }
 )
 
@@ -75,15 +77,12 @@ 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 })
+
+trace.update(output: 'Hello! How can I help you today?')
 
 # Flush events (optional - happens automatically)
 client.flush
@@ -130,12 +129,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 +331,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 +345,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 +455,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 +467,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: 初始版本