langfuse-ruby 0.1.7 → 0.2.1

data/docs/RELEASE_CHECKLIST.md

@@ -1,161 +1,36 @@
 # Langfuse Ruby SDK 发布检查清单
 
-## 📋 发布前检查
+## 发布前
 
-### 1. 代码质量检查
-- [ ] 所有测试通过 (`bundle exec rspec`)
-- [ ] 离线测试通过 (`ruby scripts/test_offline.rb`)
-- [ ] 代码风格检查 (`bundle exec rubocop`)
-- [ ] 文档更新完成
+- [ ] `bundle exec rspec`
+- [ ] `bundle exec ruby scripts/test_offline.rb`
+- [ ] `bundle exec rubocop`
+- [ ] README / [V4.md](V4.md) / 示例与代码一致
+- [ ] `lib/langfuse/version.rb`
+- [ ] `CHANGELOG.md`（Unreleased → 新版本）
+- [ ] `bundle install` 更新 `Gemfile.lock`
 
-### 2. 版本管理
-- [ ] 更新版本号 (`lib/langfuse/version.rb`)
-- [ ] 更新变更日志 (`CHANGELOG.md`)
-- [ ] 更新 README 如有必要
+## 发布
 
-### 3. 个人信息更新
-- [ ] 更新 `langfuse.gemspec` 中的作者信息
-- [ ] 更新 GitHub 仓库链接
-- [ ] 更新邮箱地址
+推荐：推送 `vX.Y.Z` tag，由 `.github/workflows/release.yml` 发布。
 
-### 4. Git 仓库设置
-- [ ] 初始化 Git 仓库 (`git init`)
-- [ ] 添加远程仓库
-- [ ] 提交所有更改
-- [ ] 推送到 GitHub
-
-## 🚀 发布步骤
-
-### 方法 1: 使用 GitHub Actions (推荐)
-
-> ⚠️ **重要**: 必须先运行 `bundle install` 更新 `Gemfile.lock`，否则 CI 会失败！
-
-#### 前提条件
-在 GitHub 仓库的 **Settings → Secrets and variables → Actions** 中配置：
-- `RUBYGEMS_API_KEY` - RubyGems API 密钥（在 [rubygems.org](https://rubygems.org) → Settings → API keys 中获取）
-
-> 注意：`GITHUB_TOKEN` 无需手动配置，GitHub Actions 会自动提供。
-
-#### 发布流程
 ```bash
-# 1. 更新版本号
-# 编辑 lib/langfuse/version.rb
-
-# 2. 更新 Gemfile.lock（重要！）
-bundle install
-
-# 3. 提交更改
-git add .
-git commit -m "Bump version to x.x.x"
-
-# 4. 推送代码
-git push origin <branch>
-
-# 5. 创建并推送标签（触发自动发布）
-git tag vx.x.x
-git push origin vx.x.x
+git push origin HEAD
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
-GitHub Actions 会自动：
-- 运行测试 (rspec + offline tests)
-- 构建 gem
-- 发布到 RubyGems
-- 创建 GitHub Release
+需要仓库 secret：`RUBYGEMS_API_KEY`。
 
-### 方法 2: 使用发布脚本
-```bash
-./scripts/release.sh
-```
+本地：
 
-### 方法 3: 手动发布
 ```bash
-# 1. 运行测试
-bundle exec rspec
-ruby scripts/test_offline.rb
-
-# 2. 构建 gem
 gem build langfuse-ruby.gemspec
-
-# 3. 发布到 RubyGems
-gem push langfuse-ruby-x.x.x.gem
-
-# 4. 创建 Git 标签
-git tag vx.x.x
-git push origin main
-git push origin vx.x.x
-```
-
-## 📊 发布后验证
-
-### 1. 检查 RubyGems
-- [ ] 访问 https://rubygems.org/gems/langfuse
-- [ ] 确认版本号正确
-- [ ] 检查下载链接
-
-### 2. 测试安装
-```bash
-# 从 RubyGems 安装
-gem install langfuse-ruby
-
-# 测试基本功能
-ruby -e "require 'langfuse'; puts Langfuse::VERSION"
-```
-
-### 3. 更新文档
-- [ ] 更新 README 中的安装说明
-- [ ] 更新项目网站（如有）
-- [ ] 发布公告
-
-## 🔧 常见问题解决
-
-### RubyGems 认证问题
-```bash
-# 登录 RubyGems
-gem signin
-
-# 或设置 API 密钥
-gem signin --key your_api_key
-```
-
-### Git 标签问题
-```bash
-# 删除本地标签
-git tag -d v0.1.0
-
-# 删除远程标签
-git push origin --delete v0.1.0
-
-# 重新创建标签
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-### 版本冲突
-```bash
-# 检查现有版本
-gem search langfuse
-
-# 更新版本号后重新发布
-# 编辑 lib/langfuse/version.rb
-# 重新构建和发布
+gem push langfuse-ruby-X.Y.Z.gem
 ```
 
-## 📞 获取帮助
-
-如果遇到问题：
-1. 查看 RubyGems 文档
-2. 检查 GitHub Issues
-3. 联系 Ruby 社区
-4. 参考其他成功的 gem 项目
-
-## 🎉 发布成功后
-
-1. 🎊 庆祝！您的 gem 已成功发布
-2. 📢 在社交媒体上分享
-3. 📝 写博客文章介绍
-4. 🔗 联系 Langfuse 团队添加到官方文档
-5. 📈 监控使用情况和反馈
-
----
+## 发布后
 
-**记住：发布是一个里程碑，但维护才是长期的工作！** 
+- [ ] https://rubygems.org/gems/langfuse-ruby 版本正确
+- [ ] `gem install langfuse-ruby && ruby -e "require 'langfuse'; puts Langfuse::VERSION"`
+- [ ] GitHub Release 已创建

data/docs/V4.md

@@ -0,0 +1,159 @@
+# Langfuse v4 with the Ruby SDK
+
+This SDK talks to **Langfuse v4** through OpenTelemetry (OTLP/HTTP JSON). The
+tracing API (`Langfuse.trace`, `#generation`, `#span`, `#agent`, …) is the same
+as in 0.2.0; only the transport, ID format, and how create/update events are
+exported change.
+
+Official references:
+
+- [Migrate custom ingestion to Langfuse v4](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4)
+- [OpenTelemetry integration](https://langfuse.com/integrations/native/opentelemetry)
+- [Observation types](https://langfuse.com/docs/observability/features/observation-types)
+- [SDK overview](https://langfuse.com/docs/observability/sdk/overview)
+
+On **Langfuse Cloud**, `POST /api/public/ingestion` stops accepting everything
+except scores on **16 November 2026**. New work should use `:otel` now.
+
+## Enable v4
+
+`ingestion_mode` still defaults to `:legacy` so existing 0.2.0 apps do not
+change transport on upgrade. Set it explicitly:
+
+```ruby
+Langfuse.configure do |config|
+  config.public_key = ENV.fetch("LANGFUSE_PUBLIC_KEY")
+  config.secret_key = ENV.fetch("LANGFUSE_SECRET_KEY")
+  config.host = ENV["LANGFUSE_HOST"] || ENV["LANGFUSE_BASE_URL"] || "https://us.cloud.langfuse.com"
+  config.ingestion_mode = :otel
+end
+```
+
+```bash
+export LANGFUSE_INGESTION_MODE=otel
+```
+
+Unrecognized values (for example `otlp`) used to silently behave like
+`:legacy`. They now log a warning and fall back to `:legacy`. Values are
+downcased (`OTEL` → `:otel`).
+
+The SDK default host is **US Cloud** (`https://us.cloud.langfuse.com`). Use
+`https://cloud.langfuse.com` (EU), `https://jp.cloud.langfuse.com`,
+`https://hipaa.cloud.langfuse.com`, or your self-hosted origin.
+
+No extra gems. The OTEL Faraday connection sends:
+
+- `Authorization: Basic …` (public key : secret key)
+- `x-langfuse-ingestion-version: 4` (real-time v4 path; without it, OTEL data
+  can be delayed up to ~10 minutes)
+- `POST {host}/api/public/otel/v1/traces`
+
+## Observations-first model
+
+In v4 a **trace** is not a separately ingested record. It is the group of
+**observations** that share a trace ID. The SDK still has a `Trace` object: in
+`:otel` mode that object is exported as the **root span**
+(`langfuse.internal.as_root = true`).
+
+| You call | Exported as |
+| --- | --- |
+| `client.trace(...)` / `Langfuse.trace(...)` | Root OTEL span; `langfuse.trace.name`, `user.id`, `session.id`, tags, metadata, `langfuse.trace.input` / `output` |
+| `#generation` | Child span, `langfuse.observation.type = generation`, plus `gen_ai.*` |
+| `#span` / `#agent` / `#tool` / … | Child span with the matching `langfuse.observation.type` |
+| `#event` | Zero-duration child span, type `event` |
+| `#score` / `client.score` | **Not** OTLP — `score-create` on `/api/public/ingestion`, IDs coerced to W3C hex |
+
+v4 queries observations directly. For filters and observation-level evaluators:
+
+1. Put **operation** input/output on that observation (`generation.end(output:)`,
+   `retriever.end(output:)`, …).
+2. Put the **overall** request/response on the trace (`Langfuse.trace(..., input:)`
+   and `trace.update(output:)`). The SDK sends those as `langfuse.trace.input` /
+   `langfuse.trace.output` on the root span (still required by some legacy
+   trace-level LLM-as-a-judge configs).
+3. Prefer typed observations (`#agent`, `#tool`, `#retriever`, …) over a generic
+   `#span` when the UI should filter or evaluate that step.
+
+Do not export the same span ID twice to “update” it. The SDK collapses each
+observation’s `*-create` and `*-update` events into **one** OTEL span before
+flush, because v4 is append-only and a second export with the same ID becomes a
+duplicate observation.
+
+## Usage and cost
+
+v4 cost uses `langfuse.observation.usage_details`, not the legacy `usage`
+object. Prefer:
+
+```ruby
+generation.end(
+  output: text,
+  usage_details: { input: 100, output: 50, cache_read: 30, total: 180 },
+  cost_details: { input: 0.001, output: 0.003, total: 0.004 }
+)
+```
+
+If you only have a legacy `usage` hash, still pass it. In `:otel` mode the
+exporter:
+
+- maps `promptTokens` / `inputTokens` / `input` (and snake_case forms) to
+  `gen_ai.usage.prompt_tokens` / `completion_tokens` / `total_tokens`
+- copies that into `langfuse.observation.usage_details` when you did not set
+  `usage_details` yourself
+- **skips** usage whose `unit` is not tokens, so bytes/milliseconds are not
+  billed as tokens
+
+`Span#generation` and `Generation#generation` forward `usage_details`,
+`cost_details`, and `prompt` (this was broken before 0.2.1).
+
+Link a prompt version with `prompt:` (`Langfuse::Prompt` or
+`{ name:, version: }`) → `langfuse.observation.prompt.name` / `.version`.
+
+## IDs
+
+| Mode | Trace ID | Observation ID |
+| --- | --- | --- |
+| `:otel` | 32-char W3C hex | 16-char W3C hex |
+| `:legacy` | UUID | UUID |
+
+Do not mix modes for the same IDs in one project.
+
+## Scores
+
+Scores are not OTLP spans. In both modes they are `score-create` batches.
+In `:otel` mode `trace_id` / `observation_id` are normalized with
+`OtelExporter.to_otel_trace_id` / `to_otel_span_id` so they attach to hex
+spans. If OTEL export fails, not-yet-sent OTEL chunks **and** that batch’s
+scores are re-queued together.
+
+```ruby
+generation.score(name: "faithfulness", value: 0.9, data_type: "NUMERIC")
+trace.score(name: "user-satisfaction", value: 0.8)
+client.score(name: "csat", value: 5, session_id: "sess-1")
+```
+
+## Flush, errors, and limits
+
+- Background flush on `flush_interval` (default 5s) **or** `flush_at` (default
+  15 events). `Langfuse.trace { ... }` flushes when the block ends.
+- OTLP and ingestion payloads are chunked at 3.5 MB. HTTP 200 with
+  `partialSuccess` is logged as a warning.
+- Transient failures (network, timeout, 429, 5xx) re-queue; 4xx validation/auth
+  drops the batch with a warning.
+- Queue cap: `max_queue_size` (default 10_000); oldest events dropped.
+- After `fork` (Puma workers) each process gets its own flush thread; inherited
+  events are dropped so the parent still owns them.
+
+## Cutover checklist
+
+1. Point `host` at the correct region or self-hosted v4 origin.
+2. Set `ingestion_mode: :otel` (or `LANGFUSE_INGESTION_MODE=otel`).
+3. Send a canary trace: root + one `generation` + one child (`retriever` /
+   `tool` / `span`), unique tag or metadata.
+4. Confirm in the UI: all observations appear without the legacy delay,
+   hierarchy and timestamps look right, generation has model / usage / cost.
+5. Confirm scores on that generation attach.
+6. Stop dual-sending the same IDs through `:legacy` and `:otel`.
+7. Move evaluators to **observation** level where possible; trace-level I/O is
+   compatibility-only in v4.
+
+Runnable sample: [`examples/v4_otel_tracing.rb`](../examples/v4_otel_tracing.rb).

data/examples/basic_tracing.rb

@@ -7,7 +7,8 @@ require 'langfuse'
 client = Langfuse.new(
   public_key: ENV.fetch('LANGFUSE_PUBLIC_KEY', nil),
   secret_key: ENV.fetch('LANGFUSE_SECRET_KEY', nil),
-  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+  host: ENV['LANGFUSE_HOST'] || ENV['LANGFUSE_BASE_URL'] || 'https://us.cloud.langfuse.com',
+  ingestion_mode: :otel # Langfuse v4
 )
 
 puts '🚀 Starting basic tracing example...'
@@ -35,10 +36,10 @@ generation = trace.generation(
     { role: 'user', content: 'Hello, how are you?' }
   ],
   output: { content: "I'm doing well, thank you! How can I help you today?" },
-  usage: {
-    prompt_tokens: 12,
-    completion_tokens: 18,
-    total_tokens: 30
+  usage_details: {
+    input: 12,
+    output: 18,
+    total: 30
   },
   model_parameters: {
     temperature: 0.7,
@@ -71,7 +72,7 @@ retrieval_span.generation(
   model: 'text-embedding-ada-002',
   input: 'What is machine learning?',
   output: [0.1, 0.2, 0.3, 0.4, 0.5], # Simplified embedding
-  usage: { prompt_tokens: 5, total_tokens: 5 }
+  usage_details: { input: 5, total: 5 }
 )
 
 # End retrieval span
@@ -113,10 +114,10 @@ answer_gen = answer_span.generation(
   output: {
     content: '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.'
   },
-  usage: {
-    prompt_tokens: 85,
-    completion_tokens: 45,
-    total_tokens: 130
+  usage_details: {
+    input: 85,
+    output: 45,
+    total: 130
   }
 )
 

data/examples/simplified_usage.rb

@@ -7,7 +7,8 @@ require 'langfuse'
 Langfuse.configure do |config|
   config.public_key = ENV.fetch('LANGFUSE_PUBLIC_KEY', nil)
   config.secret_key = ENV.fetch('LANGFUSE_SECRET_KEY', nil)
-  config.host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+  config.host = ENV['LANGFUSE_HOST'] || ENV['LANGFUSE_BASE_URL'] || 'https://us.cloud.langfuse.com'
+  config.ingestion_mode = :otel # Langfuse v4
 end
 
 puts '🚀 Simplified usage example...'
@@ -26,10 +27,10 @@ result = Langfuse.trace('simplified-chat', user_id: 'user-123', input: { message
 
   # Simulate LLM response
   response_content = "Hi there! How can I help you today?"
-  usage = { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 }
+  usage_details = { input: 10, output: 15, total: 25 }
 
-  # End the generation with output and usage
-  generation.end(output: response_content, usage: usage)
+  # End the generation with output and v4 usage_details (cost model)
+  generation.end(output: response_content, usage_details: usage_details)
 
   # Update trace with final output
   trace.update(output: response_content)
@@ -54,7 +55,7 @@ Langfuse.trace('document-qa', user_id: 'user-456') do |trace|
     model: 'text-embedding-ada-002',
     input: 'What is Ruby?',
     output: [0.1, 0.2, 0.3],
-    usage: { prompt_tokens: 5, total_tokens: 5 }
+    usage_details: { input: 5, total: 5 }
   )
   
   retrieval.end(output: { documents: ['Ruby is a programming language...'] })
@@ -70,7 +71,7 @@ Langfuse.trace('document-qa', user_id: 'user-456') do |trace|
   
   gen.end(
     output: 'Ruby is a dynamic, object-oriented programming language.',
-    usage: { prompt_tokens: 50, completion_tokens: 20, total_tokens: 70 }
+    usage_details: { input: 50, output: 20, total: 70 }
   )
   
   answer_span.end(output: { answer: 'Ruby is a dynamic programming language.' })

data/examples/v4_otel_tracing.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Langfuse v4 (OTLP) tracing example.
+# Tracing APIs are the same as :legacy; only ingestion_mode: :otel changes the
+# transport (OTLP/HTTP + x-langfuse-ingestion-version: 4).
+#
+#   export LANGFUSE_PUBLIC_KEY=pk-lf-...
+#   export LANGFUSE_SECRET_KEY=sk-lf-...
+#   export LANGFUSE_HOST=https://us.cloud.langfuse.com   # or EU / self-hosted
+#   ruby examples/v4_otel_tracing.rb
+
+require 'langfuse'
+
+Langfuse.configure do |config|
+  config.public_key = ENV.fetch('LANGFUSE_PUBLIC_KEY', nil)
+  config.secret_key = ENV.fetch('LANGFUSE_SECRET_KEY', nil)
+  config.host = ENV['LANGFUSE_HOST'] || ENV['LANGFUSE_BASE_URL'] || 'https://us.cloud.langfuse.com'
+  config.ingestion_mode = :otel
+end
+
+puts '🚀 Langfuse v4 / OTEL tracing example'
+puts "   host: #{Langfuse.client.host}"
+puts "   ingestion_mode: #{Langfuse.client.ingestion_mode}"
+
+query = 'What is Ruby?'
+
+Langfuse.trace(
+  'v4-document-qa',
+  user_id: 'user-123',
+  session_id: 'sess-456',
+  tags: %w[v4 example],
+  input: { query: query }
+) do |trace|
+  agent = trace.agent(name: 'qa-agent', input: { query: query })
+
+  retrieval = agent.retriever(
+    name: 'vector-search',
+    input: { query: query, top_k: 3 }
+  )
+  docs = ['Ruby is a dynamic, object-oriented programming language.']
+  retrieval.end(output: { documents: docs })
+
+  generation = agent.generation(
+    name: 'openai-completion',
+    model: 'gpt-4o',
+    input: [
+      { role: 'system', content: 'Answer using the retrieved context only.' },
+      { role: 'user', content: query }
+    ],
+    model_parameters: { temperature: 0.2 }
+  )
+
+  answer = 'Ruby is a dynamic, object-oriented programming language.'
+  generation.end(
+    output: answer,
+    usage_details: { input: 48, output: 16, total: 64 },
+    cost_details: { input: 0.0001, output: 0.0004, total: 0.0005 }
+  )
+  generation.score(name: 'faithfulness', value: 0.92, comment: 'Grounded in retrieved docs')
+
+  agent.end(output: { answer: answer })
+  trace.update(output: { answer: answer })
+  trace.score(name: 'user-satisfaction', value: 0.9)
+
+  puts "Created v4 trace: #{trace.id}"
+  puts "Trace URL: #{trace.get_url}"
+end
+
+puts '✅ Flushed. Check the Langfuse UI — observations should appear in real time.'

data/langfuse-ruby.gemspec

@@ -43,6 +43,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   # Dependencies
+  spec.add_dependency 'base64', '>= 0.1.0' # stdlib in Ruby < 4.0, bundled gem since Ruby 4.0
   spec.add_dependency 'concurrent-ruby', '~> 1.0'
   spec.add_dependency 'faraday', '>= 1.8', '< 3.0'
   spec.add_dependency 'faraday-multipart', '~> 1.0'
@@ -54,6 +55,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'tsort', '>= 0.1.0' # stdlib in Ruby < 4.0, default gem since Ruby 4.0
   spec.add_development_dependency 'vcr', '~> 6.0'
   spec.add_development_dependency 'webmock', '~> 3.0'
   spec.add_development_dependency 'yard', '~> 0.9'