langfuse-ruby 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e15fd7f7f4e2e8b1a8018f27de35f42a3124973c8a455b50781a0d08924aa3d
-  data.tar.gz: 91253f7addf89cef33fcf047376f8667fae8e2e9d75f096b4096d4c876d06b20
+  metadata.gz: 7b2c65ac52311951b2658204cbf3f76afff090465ef9e500718f59f194dbcea9
+  data.tar.gz: db397fdd6ca24db06b67c92eed232663d7845504d9dc0e7759098ebdbe88e620
 SHA512:
-  metadata.gz: 62d8773683844ecc44a1d258765f0522f77e83b02cbb7b7441d892e3e6a9252348f8ccfd331e185186b46aa9fb30203146e7beffd29a1330b5ab14ff75862a47
-  data.tar.gz: 23e33a0b7d7b8b25c07e9663cf320771a6db8160fb18302179acc8aeaaf99c1740add31c84448106df46efe22e89b2c36ce7bae6b66e600e525226854a2003d7
+  metadata.gz: a1ba2f150b0a6d16ccc99d26144455d6fcb66d95a7e9d644bb50d12de91c95fa7751b6b3145f507a74da1b367eacaf3d43a91073a249815695f7260fc2c66d56
+  data.tar.gz: 6d27a0bd423f14637597acfc243eaf4c74e3e533eb87ceab62e46fffc8249bd3043866ec6d5a0450b8eb7bc82b29c4e553fdfe3ae9c4c3d468d5fa241b0a3c68

data/.github/workflows/ci.yml

@@ -7,15 +7,30 @@ on:
     branches: [ master ]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler-cache: true
+
+    - name: Run RuboCop
+      run: bundle exec rubocop
+
   test:
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        ruby-version: ['3.1', '3.2', '3.3', '3.4']
+        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
@@ -29,25 +44,21 @@ jobs:
     - name: Run offline tests
       run: bundle exec ruby scripts/test_offline.rb
 
-    - name: Run RuboCop
-      run: bundle exec rubocop
-      continue-on-error: true
-  
   build:
     runs-on: ubuntu-latest
-    needs: test
+    needs: [lint, test]
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.4'
+        ruby-version: '4.0'
         bundler-cache: true
     
     - name: Build gem
       run: gem build langfuse-ruby.gemspec
     
     - name: Verify gem can be installed
-      run: gem install langfuse-ruby-*.gem 
+      run: gem install langfuse-ruby-*.gem

data/.github/workflows/release.yml

@@ -9,14 +9,16 @@ jobs:
   release:
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.4'
+        ruby-version: '4.0'
         bundler-cache: true
     
     - name: Run tests

data/.mise.toml

@@ -0,0 +1,8 @@
+# mise project toolchain config
+# https://mise.jdx.dev/configuration.html
+#
+# This project defaults to the latest stable Ruby release.
+# Run `mise install` after cloning to install it, then `bundle install`.
+
+[tools]
+ruby = "latest"

data/.rubocop.yml

@@ -47,7 +47,7 @@ Metrics/CyclomaticComplexity:
   Max: 20
 
 Metrics/PerceivedComplexity:
-  Max: 20
+  Max: 25
 
 Metrics/ParameterLists:
   Enabled: false
@@ -63,4 +63,4 @@ Lint/UnusedMethodArgument:
     - 'lib/langfuse/evaluation.rb'
 
 Metrics/ClassLength:
-  Max: 600
+  Max: 800

data/CHANGELOG.md

@@ -7,17 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-18
+
 ### Added
-- **Simplified API**: New class-level convenience methods for easier usage
-  - `Langfuse.trace(name, **options, &block)` - Block-based tracing with automatic flush
-  - `Langfuse.get_prompt(name, variables:, retries:)` - Get and compile prompts with retry support
-  - `Langfuse.client` - Thread-safe singleton client access
-  - `Langfuse.flush` / `Langfuse.shutdown` / `Langfuse.reset!` - Client lifecycle management
-- **Graceful Degradation**: Null object pattern for fault tolerance
-  - `NullTrace`, `NullGeneration`, `NullSpan`, `NullEvent` - No-op objects when Langfuse is unavailable
-- **Retry Support**: `get_prompt` now supports configurable retries with exponential backoff (default: 2 retries)
-- New example file `examples/simplified_usage.rb` demonstrating the simplified API
-- Comprehensive test coverage for convenience methods (28 new tests)
+- **Environment support**: `environment` config / `LANGFUSE_TRACING_ENVIRONMENT` env var, injected into trace, observation and score bodies
+- **Sampling**: `sample_rate` config / `LANGFUSE_SAMPLE_RATE` env var, deterministic trace-based sampling (all events of a trace share the same decision)
+- **Masking**: `mask` callable applied to `input`/`output`/`metadata` before sending, for PII redaction
+- **flush_at threshold**: flush as soon as the queue reaches `flush_at` events (default 15, env `LANGFUSE_FLUSH_AT`), via a condition-variable wake-up on the flush thread
+- **Batch chunking**: ingestion batches are split to respect the 3.5 MB API limit; oversized single events are dropped with a warning
+- **207 partial-success handling**: per-event errors from the ingestion API are logged via the structured logger
+- **Score full fields**: `session_id`, `dataset_run_id`, `metadata`, `config_id`, `queue_id`, `id`, `environment`, and string values for CATEGORICAL/CORRECTION scores; `create_score` alias
+- **Generation usage_details / cost_details**: new v4 usage model (arbitrary keys such as cache tokens) alongside legacy `usage`
+- **Generation prompt linking**: `prompt:` accepts a `Langfuse::Prompt` or `{ name:, version: }` hash, emitted as `promptName`/`promptVersion`
+- **Trace public field**: `public:` flag for shareable traces
+- **LANGFUSE_BASE_URL** env var alias (new SDK standard) alongside `LANGFUSE_HOST`
+- **Structured Logger**: replaces `puts` with `Logger`; level controlled by `debug` / `LANGFUSE_DEBUG`
+- **at_exit shutdown hook**: pending events are flushed on process exit (configurable via `shutdown_on_exit`)
+- **W3C hex IDs in OTel mode**: native 32-char trace IDs and 16-char span IDs for OTel ingestion
+- **OTel exporter attributes**: `langfuse.environment`, `langfuse.trace.public`, `langfuse.internal.as_root`, `langfuse.observation.usage_details`, `langfuse.observation.cost_details`, `langfuse.observation.prompt.name`, `langfuse.observation.prompt.version`
+- **Simplified API**: Class-level convenience methods (`Langfuse.trace`, `get_prompt`, `client`, `flush`, `shutdown`, `reset!`) with graceful degradation via null objects
+- **Retry Support**: `get_prompt` supports configurable retries with exponential backoff (default: 2 retries)
+- **Ruby 4.0 support**: CI matrix covers Ruby 3.1–4.0; explicit `base64` / `tsort` dependencies for Ruby 4.0 gem packaging
+
+### Fixed
+- **OTel mode scores lost**: scores were exported as OTLP spans with `langfuse.score.*` attributes, which the server does not map to Langfuse scores. Scores now always route through the ingestion API (`score-create` batch), with trace/observation IDs normalized to OTel hex IDs so they attach to the correct entities
+- **OTel flush failure drops scores**: when OTEL export of non-score events fails, score events in the same batch are now re-queued together with OTEL events (they were previously drained by `flush` and permanently lost on `raise`)
+- **OTel ID mismatch**: observation-level scores referenced full UUIDs while spans used truncated hex, breaking attachment. IDs are now normalized on both sides
+- **Span/Generation score missing trace_id**: `Span#score` and `Generation#score` now pass `trace_id` so the server can attach observation-level scores correctly
+- **Process-level singleton**: `Langfuse.client` was thread-local (`Thread.current`), creating one client + flush thread per thread under Puma/Sidekiq. Now a single process-wide client guarded by a `Mutex`
+- **Idempotent shutdown**: `shutdown` can be called multiple times safely
+- **Body serialization**: event bodies now only camelCase top-level keys; user data under `input`/`output`/`metadata`/`usageDetails`/`costDetails`/`modelParameters` is passed through verbatim so user-provided keys are not mangled
+
+### Changed
+- `Langfuse.client` is now process-wide instead of thread-local. Use `Langfuse.new` for isolated clients in tests
+- Default `flush_interval` behavior unchanged, but the flush thread now also wakes on the `flush_at` threshold
+- `Configuration` gains `environment`, `sample_rate`, `mask`, `flush_at`, `logger`, `shutdown_on_exit` attributes
 
 ## [0.1.5] - 2025-12-26
 

data/CLAUDE.md

@@ -8,8 +8,14 @@ This is the official Ruby SDK for [Langfuse](https://langfuse.com) - an open-sou
 
 ## Common Commands
 
+Ruby version is managed with [mise](https://mise.jdx.dev) via `.mise.toml`
+(defaults to the latest stable Ruby). Run `mise install` after cloning, then
+`bundle install`. With mise's shell integration active, the commands below work
+directly; in a non-mise shell prefix them with `mise exec --`.
+
 ```bash
 # Install dependencies
+mise install        # install the pinned Ruby version
 bundle install
 
 # Run all RSpec tests
@@ -39,12 +45,13 @@ bundle exec rake release_gem
 ### Core Classes
 
 - **`Langfuse`** ([lib/langfuse.rb](lib/langfuse.rb)) - Module with class-level convenience methods (`trace`, `get_prompt`, `client`, `flush`, `shutdown`, `reset!`)
-- **`Langfuse::Client`** ([lib/langfuse/client.rb](lib/langfuse/client.rb)) - Main entry point. Handles API authentication, HTTP connections (via Faraday), event queuing, and background flush thread for auto-batching events.
+- **`Langfuse::Client`** ([lib/langfuse/client.rb](lib/langfuse/client.rb)) - Main entry point. Handles API authentication, HTTP connections (via Faraday), event queuing, sampling/masking, and background flush thread for auto-batching events.
 - **`Langfuse::Trace`** ([lib/langfuse/trace.rb](lib/langfuse/trace.rb)) - Top-level container for a request/session.
 - **`Langfuse::Span`** ([lib/langfuse/span.rb](lib/langfuse/span.rb)) - Timed operation with enhanced type support.
-- **`Langfuse::Generation`** ([lib/langfuse/generation.rb](lib/langfuse/generation.rb)) - LLM call tracking.
+- **`Langfuse::Generation`** ([lib/langfuse/generation.rb](lib/langfuse/generation.rb)) - LLM call tracking (supports `usage_details`/`cost_details` and prompt linking).
 - **`Langfuse::Event`** ([lib/langfuse/event.rb](lib/langfuse/event.rb)) - Point-in-time events.
 - **`Langfuse::Prompt`** ([lib/langfuse/prompt.rb](lib/langfuse/prompt.rb)) - Prompt templates with caching.
+- **`Langfuse::OtelExporter`** ([lib/langfuse/otel_exporter.rb](lib/langfuse/otel_exporter.rb)) - Maps Langfuse events to OTLP/HTTP JSON when `ingestion_mode: :otel`.
 - **`Langfuse::NullTrace/NullGeneration/NullSpan`** ([lib/langfuse/null_objects.rb](lib/langfuse/null_objects.rb)) - Null objects for graceful degradation.
 
 ### Simplified API (Recommended)
@@ -63,10 +70,14 @@ Langfuse.get_prompt("my-prompt", variables: { name: "Alice" }, retries: 3)
 
 ### Event Flow
 
-1. Observations (traces, spans, generations, events) are created via Client methods
-2. Events are queued in `@event_queue` (thread-safe `Concurrent::Array`)
-3. Background flush thread sends batched events to `/api/public/ingestion` endpoint
-4. Manual flush available via `client.flush`; graceful shutdown via `client.shutdown`
+1. Observations (traces, spans, generations, events, scores) are created via Client methods
+2. Bodies are prepared via `Utils.prepare_event_body` (top-level camelCase; user data under `input`/`output`/`metadata`/etc. is left verbatim), then environment injection, masking, and sampling are applied
+3. Events are queued in `@event_queue` (thread-safe `Concurrent::Array`)
+4. Background flush thread wakes on `flush_interval` **or** when the queue reaches `flush_at`
+5. Flush path depends on `ingestion_mode`:
+   - `:legacy` → batched POST to `/api/public/ingestion` (chunked to 3.5 MB)
+   - `:otel` → non-score events via OTLP `/api/public/otel/v1/traces`; **scores always go through the ingestion API**, with IDs normalized to OTel hex so they attach correctly. On OTEL transport failure, both OTEL and score events from the batch are re-queued
+6. Manual flush via `client.flush`; idempotent shutdown via `client.shutdown` (plus optional `at_exit` hook)
 
 ### Observation Types
 
@@ -81,7 +92,7 @@ Enhanced types are implemented as spans with `as_type` metadata sent to the API.
 Client accepts config via:
 1. Constructor parameters
 2. `Langfuse.configure` block
-3. Environment variables: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`, `LANGFUSE_FLUSH_INTERVAL`, `LANGFUSE_AUTO_FLUSH`
+3. Environment variables: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST` / `LANGFUSE_BASE_URL`, `LANGFUSE_FLUSH_INTERVAL`, `LANGFUSE_FLUSH_AT`, `LANGFUSE_AUTO_FLUSH`, `LANGFUSE_TRACING_ENVIRONMENT`, `LANGFUSE_SAMPLE_RATE`, `LANGFUSE_DEBUG`, `LANGFUSE_INGESTION_MODE`
 
 ### Error Handling
 
@@ -95,6 +106,7 @@ Graceful degradation: When Langfuse is unavailable, `Langfuse.trace` yields a `N
 - Uses Faraday for HTTP with Basic Auth (public_key:secret_key)
 - Prompt names with special characters are auto-URL-encoded via `Utils.url_encode`
 - `trace-update` events merge into existing `trace-create` in queue (deduplication)
-- All keys are converted to camelCase before API submission via `Utils.deep_camelize_keys`
-- Thread-safe singleton client via `Thread.current[:langfuse_client]`
+- Event bodies use `Utils.prepare_event_body` (top-level camelCase only; nested user data is not mangled)
+- Process-wide singleton client via `Langfuse::CLIENT_MUTEX` (not thread-local); use `Langfuse.new` for isolated clients in tests
+- In OTel mode, IDs are W3C hex (`generate_trace_id` / `generate_observation_id`); scores normalize refs via `OtelExporter.to_otel_trace_id` / `to_otel_span_id`
 - `get_prompt` supports configurable retries with exponential backoff

data/Gemfile

@@ -7,4 +7,5 @@ gemspec
 
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.0'
+gem 'simplecov', '~> 0.22', require: false
 gem 'yard', '~> 0.9'

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.6)
+    langfuse-ruby (0.2.0)
+      base64 (>= 0.1.0)
       concurrent-ruby (~> 1.0)
       faraday (>= 1.8, < 3.0)
       faraday-multipart (~> 1.0)
@@ -21,11 +22,12 @@ GEM
       bigdecimal
       rexml
     diff-lcs (1.6.2)
+    docile (1.4.1)
     faraday (2.13.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-multipart (1.1.1)
+    faraday-multipart (1.2.0)
       multipart-post (~> 2.0)
     faraday-net_http (3.4.1)
       net-http (>= 0.5.0)
@@ -76,12 +78,18 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    tsort (0.2.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-emoji (4.2.0)
     uri (1.0.3)
-    vcr (6.3.1)
-      base64
+    vcr (6.4.0)
     webmock (3.25.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -98,6 +106,8 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.0)
+  simplecov (~> 0.22)
+  tsort (>= 0.1.0)
   vcr (~> 6.0)
   webmock (~> 3.0)
   yard (~> 0.9)

data/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install test spec test-offline test-all lint lint-fix build release clean console help tag
+.PHONY: install test spec test-offline test-all lint lint-fix build release clean console help tag coverage
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
@@ -17,6 +17,10 @@ test-all: ## Run all tests (spec + offline)
 
 test: spec ## Alias for spec
 
+coverage: ## Run tests and open coverage report
+	bundle exec rake spec
+	open coverage/index.html
+
 lint: ## Run RuboCop linter
 	bundle exec rubocop
 
@@ -26,7 +30,7 @@ lint-fix: ## Run RuboCop with auto-correct
 build: ## Build the gem
 	bundle exec rake build
 
-release: tag build ## Release: tag + build + push to RubyGems
+release: tag ## Release: tag + build + push to RubyGems
 	bundle exec rake release_gem
 
 clean: ## Remove built gem files
@@ -39,7 +43,7 @@ console: ## Start an IRB console with the gem loaded
 tag: ## Create and push a version tag. Usage: make tag [VERSION=x.y.z]
 	@git fetch --tags; \
 	if [ -z "$(VERSION)" ]; then \
-		LATEST=$$(git tag -l 'v*' --sort=-v:refname | head -n1); \
+		LATEST=$$(git tag -l 'v[0-9]*' --sort=-v:refname | head -n1); \
 		if [ -z "$$LATEST" ]; then \
 			NEW_TAG="v0.0.1"; \
 		else \
@@ -51,7 +55,7 @@ tag: ## Create and push a version tag. Usage: make tag [VERSION=x.y.z]
 		fi; \
 	else \
 		NEW_TAG="v$(VERSION)"; \
-		LATEST=$$(git tag -l 'v*' --sort=-v:refname | head -n1); \
+		LATEST=$$(git tag -l 'v[0-9]*' --sort=-v:refname | head -n1); \
 		if [ "$$LATEST" = "$$NEW_TAG" ]; then \
 			echo "Tag $$NEW_TAG already exists on remote, deleting and re-pushing..."; \
 			git tag -d "$$NEW_TAG" 2>/dev/null || true; \

data/README.md

@@ -16,6 +16,10 @@ Ruby SDK for [Langfuse](https://langfuse.com) - the open-source LLM engineering
 
 ## Installation
 
+This gem requires Ruby >= 3.1 and is tested against Ruby 3.1–4.0. For
+development, Ruby version is managed with [mise](https://mise.jdx.dev) (defaults
+to the latest stable Ruby via `.mise.toml`).
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -34,6 +38,17 @@ Or install it yourself as:
 $ gem install langfuse-ruby
 ```
 
+### Development setup with mise
+
+```bash
+# Install mise (if not already installed), then trust the project config and
+# install the pinned Ruby version.
+brew install mise                  # macOS; see mise docs for other OSes
+mise install                       # installs Ruby from .mise.toml
+bundle install                     # install gem dependencies
+bundle exec rake spec              # run the test suite
+```
+
 ## Quick Start
 
 ### 1. Initialize the Client
@@ -58,6 +73,52 @@ end
 client = Langfuse.new
 ```
 
+### OpenTelemetry (OTEL) Ingestion Mode
+
+Langfuse v4 introduces a faster data model powered by OpenTelemetry. To use
+it, enable the OTEL ingestion mode. This sends data via the OTLP/HTTP JSON
+endpoint (`/api/public/otel/v1/traces`) with the `x-langfuse-ingestion-version: 4`
+header for real-time ingestion and observation-level online evaluators.
+
+```ruby
+# Via constructor
+client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  ingestion_mode: :otel
+)
+
+# Via global configuration
+Langfuse.configure do |config|
+  config.public_key = "pk-lf-..."
+  config.secret_key = "sk-lf-..."
+  config.ingestion_mode = :otel
+end
+
+# Via environment variable
+# LANGFUSE_INGESTION_MODE=otel
+```
+
+All existing tracing APIs work unchanged. The SDK maps Langfuse events to
+OpenTelemetry spans with the appropriate `langfuse.*` and `gen_ai.*` attributes.
+No additional dependencies are required.
+
+**Scores in OTel mode:** scores are not part of the OTLP trace mapping. The SDK
+always sends them through the ingestion API (`/api/public/ingestion`) as
+`score-create` events, and normalizes `trace_id` / `observation_id` to W3C hex
+IDs so they attach to the correct OTel-ingested entities. If an OTEL export
+fails mid-batch, both the OTEL events and any scores from that batch are
+re-queued for retry.
+
+```ruby
+# Scores work the same in both modes
+client = Langfuse.new(ingestion_mode: :otel, ...)
+trace = client.trace(name: "chat")
+generation = trace.generation(name: "llm", model: "gpt-4o")
+generation.score(name: "faithfulness", value: 0.9)
+client.flush  # traces/spans → OTLP; scores → ingestion API
+```
+
 ### 2. Basic Tracing
 
 ```ruby
@@ -146,16 +207,16 @@ end
 ### Other Class Methods
 
 ```ruby
-# Get the thread-safe singleton client
+# Get the process-wide, thread-safe singleton client
 client = Langfuse.client
 
 # Manual flush (when not using block-based tracing)
 Langfuse.flush
 
-# Shutdown the client
+# Shutdown the client (idempotent; also runs via at_exit when shutdown_on_exit is true)
 Langfuse.shutdown
 
-# Reset the singleton (useful for testing)
+# Reset the singleton (useful for testing; prefer Langfuse.new for isolated clients)
 Langfuse.reset!
 ```
 
@@ -376,6 +437,97 @@ generation.score(
 
 ## Advanced Usage
 
+### Tracing Environment, Sampling and Masking
+
+```ruby
+# Tag all events with a tracing environment (also via LANGFUSE_TRACING_ENVIRONMENT)
+client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  environment: "production"
+)
+
+# Sample a fraction of traces deterministically (also via LANGFUSE_SAMPLE_RATE)
+# All events of a trace share the same keep/drop decision.
+sampled_client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  sample_rate: 0.1
+)
+
+# Mask sensitive fields before sending (applied to input/output/metadata)
+masked_client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  mask: ->(value) { value.to_s.gsub(/\b\d{16}\b, "***CARD***") }
+)
+```
+
+### Batch flushing
+
+Events are flushed in the background every `flush_interval` seconds, or as soon
+as `flush_at` events are queued (default 15, env `LANGFUSE_FLUSH_AT`). Batches
+are automatically split to respect the 3.5 MB ingestion API limit, and a
+process-wide `at_exit` hook flushes pending events on shutdown.
+
+```ruby
+client = Langfuse.new(
+  public_key: "pk-lf-...",
+  secret_key: "sk-lf-...",
+  flush_at: 50,           # flush after 50 events
+  flush_interval: 10,     # or every 10 seconds
+  shutdown_on_exit: true  # flush on process exit (default)
+)
+```
+
+### Scores with full fields
+
+Scores can target a trace, an observation, a session, or a dataset run, and
+carry metadata, a config reference, and an annotation queue link:
+
+```ruby
+# Trace-level score
+trace.score(name: "accuracy", value: 0.9, comment: "good")
+
+# Observation-level score (trace_id is set automatically on Span/Generation)
+generation.score(name: "faithfulness", value: 0.8, data_type: "NUMERIC")
+
+# Session-level score
+client.score(name: "csat", value: 5, session_id: "sess-1", data_type: "NUMERIC")
+
+# Dataset-run score with metadata and config link
+client.score(
+  name: "hallucination",
+  value: 0.2,
+  dataset_run_id: "run-1",
+  trace_id: "trace-1",
+  metadata: { evaluator: "llm-judge" },
+  config_id: "cfg-abc",
+  data_type: "NUMERIC"
+)
+
+# Categorical string value
+client.score(name: "label", value: "good", trace_id: "t1", data_type: "CATEGORICAL")
+```
+
+### Generation usage details, cost details and prompt linking
+
+```ruby
+# New v4 usage model (arbitrary keys, e.g. cache tokens)
+gen = trace.generation(
+  name: "chat",
+  model: "gpt-4o",
+  usage_details: { input: 100, output: 50, cache_read: 30 },
+  cost_details: { input: 0.001, output: 0.003, total: 0.004 }
+)
+gen.end(output: "response")
+
+# Link a generation to a prompt version (accepts a Langfuse::Prompt or a hash)
+prompt = Langfuse.get_prompt("chat-prompt")
+gen = trace.generation(name: "chat", model: "gpt-4o", prompt: prompt)
+# or: prompt: { name: "chat-prompt", version: 3 }
+```
+
 ### Error Handling
 
 ```ruby
@@ -405,11 +557,16 @@ client = Langfuse.new(
   public_key: "pk-lf-...",
   secret_key: "sk-lf-...",
   host: "https://your-instance.langfuse.com",
-  debug: true,        # Enable debug logging
-  timeout: 30,        # Request timeout in seconds
-  retries: 3,         # Number of retry attempts
-  flush_interval: 30, # Event flush interval in seconds (default: 5)
-  auto_flush: true    # Enable automatic flushing (default: true)
+  debug: true,          # Enable debug logging (or LANGFUSE_DEBUG=true)
+  timeout: 30,          # Request timeout in seconds
+  retries: 3,           # Number of retry attempts
+  flush_interval: 30,   # Event flush interval in seconds (default: 5)
+  flush_at: 50,         # Flush once this many events are queued (default: 15)
+  auto_flush: true,     # Enable automatic flushing (default: true)
+  environment: "prod",  # Tracing environment (or LANGFUSE_TRACING_ENVIRONMENT)
+  sample_rate: 0.5,     # Keep 50% of traces deterministically (or LANGFUSE_SAMPLE_RATE)
+  mask: ->(v) { v },    # Callable applied to input/output/metadata
+  shutdown_on_exit: true # Flush pending events on process exit (default: true)
 )
 ```
 
@@ -420,9 +577,14 @@ You can also configure the client using environment variables:
 ```bash
 export LANGFUSE_PUBLIC_KEY="pk-lf-..."
 export LANGFUSE_SECRET_KEY="sk-lf-..."
-export LANGFUSE_HOST="https://cloud.langfuse.com"
+export LANGFUSE_HOST="https://cloud.langfuse.com"   # or LANGFUSE_BASE_URL
 export LANGFUSE_FLUSH_INTERVAL=5
+export LANGFUSE_FLUSH_AT=15
 export LANGFUSE_AUTO_FLUSH=true
+export LANGFUSE_TRACING_ENVIRONMENT="production"
+export LANGFUSE_SAMPLE_RATE=0.5
+export LANGFUSE_DEBUG=false
+export LANGFUSE_INGESTION_MODE=legacy   # or otel
 ```
 
 ### Automatic Flush Control

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'