Skip to content

docs: align docs with implementation #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kxzk merged 1 commit into from
Mar 5, 2026
Merged

docs: align docs with implementation #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions docs/API_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,16 @@ Block receives a configuration object with these properties:
| `cache_max_size` | Integer | No | `1000` | Max cached prompts |
| `cache_backend` | Symbol | No | `:memory` | `:memory` or `:rails` |
| `cache_lock_timeout` | Integer | No | `10` | Lock timeout (seconds) |
| `cache_stale_while_revalidate` | Boolean | No | `false` | Enable stale-while-revalidate |
| `cache_stale_ttl` | Integer | No | `0` | Stale TTL (seconds) |
| `cache_stale_while_revalidate` | Boolean | No | `false` | Enable SWR (requires stale TTL) |
| `cache_stale_ttl` | Integer | No | `0` | Stale TTL (seconds, >0 enables) |
| `cache_refresh_threads` | Integer | No | `5` | Background refresh threads |
| `batch_size` | Integer | No | `50` | Score batch size |
| `flush_interval` | Integer | No | `10` | Score flush interval (seconds) |
| `batch_size` | Integer | No | `50` | Score + trace export batch size |
| `flush_interval` | Integer | No | `10` | Score + trace export interval (s) |
| `logger` | Logger | No | Auto-detected | Logger instance |
| `tracing_async` | Boolean | No | `true` | ⚠️ Experimental (not implemented) |
| `tracing_async` | Boolean | No | `true` | ⚠️ Experimental (OTel export mode) |
| `job_queue` | Symbol | No | `:default` | ⚠️ Experimental (not implemented) |
| `environment` | String | No | `nil` | Default trace environment |
| `release` | String | No | `nil` | Default release identifier |

**Example:**

Expand All @@ -61,6 +63,7 @@ Langfuse.configure do |config|
config.cache_ttl = 300
config.cache_backend = :rails
config.cache_stale_while_revalidate = true # Serve stale data while refreshing
config.cache_stale_ttl = 300
end
```

Expand Down
5 changes: 4 additions & 1 deletion docs/CACHING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,10 +180,12 @@ Langfuse.configure do |config|
config.cache_backend = :memory # Works with both :memory and :rails
config.cache_ttl = 300 # Fresh for 5 minutes
config.cache_stale_while_revalidate = true # Enable SWR
# cache_stale_ttl automatically set to 300 (same as cache_ttl)
config.cache_stale_ttl = 300 # Serve stale for up to 5 minutes
end
```

**Important:** SWR is only active when `cache_stale_ttl` is a positive value.

#### Custom Stale TTL

```ruby
Expand Down Expand Up @@ -236,6 +238,7 @@ Langfuse.configure do |config|
config.cache_backend = :memory
config.cache_ttl = 60
config.cache_stale_while_revalidate = true
config.cache_stale_ttl = 60
config.cache_refresh_threads = 5 # Background refresh threads
end

Expand Down
44 changes: 34 additions & 10 deletions docs/CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,13 @@ When enabled, serves stale cached data immediately while refreshing in the backg
- `false` (default): Cache expires at TTL, next request waits for API (~100ms)
- `true`: After TTL, serves stale data instantly (~1ms) + refreshes in background

**Important:** SWR only activates when `cache_stale_ttl` is a positive value. Set it explicitly (typically equal to `cache_ttl`).

**Compatibility:**

- ✅ Works with `:memory` backend
- ✅ Works with `:rails` backend
- Set `cache_stale_ttl` to control how long stale data is served (e.g., same as `cache_ttl`)
- Set `cache_stale_ttl` to a positive value to activate SWR (often the same as `cache_ttl`)

See [CACHING.md](CACHING.md#stale-while-revalidate-swr) for detailed usage.

Expand All @@ -162,7 +164,7 @@ config.cache_stale_ttl = :indefinite # Never expire (normalized to 1000 years i

**Recommended values:**

- Same as `cache_ttl` (default when SWR enabled): Balanced freshness/latency
- Same as `cache_ttl`: Balanced freshness/latency
- `2x cache_ttl`: More tolerance for API slowdowns
- `:indefinite`: Maximum performance, eventual consistency, high availability

Expand All @@ -188,25 +190,25 @@ config.cache_refresh_threads = 10 # More threads for high-traffic apps

**Memory impact:** ~1-2MB per thread pool (negligible)

Only used when SWR is enabled (`cache_stale_while_revalidate = true`).
Only used when SWR is enabled (`cache_stale_ttl > 0`).

#### `batch_size`

- **Type:** Integer
- **Default:** `50`
- **Description:** Number of scores to batch before sending to API
- **Description:** Number of scores to batch before sending to API. Also used for OpenTelemetry trace export batching.

```ruby
config.batch_size = 100 # Larger batches for high-volume scoring
```

Used by scoring API. See [SCORING.md](SCORING.md).
Used by scoring API and OpenTelemetry tracing export. See [SCORING.md](SCORING.md).

#### `flush_interval`

- **Type:** Integer (seconds)
- **Default:** `10`
- **Description:** Maximum time to wait before flushing batched scores
- **Description:** Maximum time to wait before flushing batched scores. Also controls OpenTelemetry trace export schedule when tracing is async.

```ruby
config.flush_interval = 5 # Flush more frequently
Expand All @@ -231,14 +233,14 @@ config.logger = Logger.new(IO::NULL)

- **Type:** Boolean
- **Default:** `true`
- **Status:** Not yet implemented (placeholder)
- **Description:** Future: enable async background processing for traces
- **Status:** Implemented for OpenTelemetry batching; ActiveJob integration is not implemented
- **Description:** Controls OpenTelemetry export behavior. When `true`, spans are exported in the background on a schedule. When `false`, spans are queued and exported on explicit flush with a long schedule delay.

```ruby
config.tracing_async = true # Placeholder - no effect currently
config.tracing_async = true
```

**Current Behavior:** All trace operations are synchronous with OpenTelemetry export. This option is reserved for future async job processing.
**Current Behavior:** Uses OpenTelemetry `BatchSpanProcessor` in both modes. Async mode uses `flush_interval` for scheduled export; sync mode uses a long schedule delay and relies on explicit `force_flush`.

#### `job_queue` ⚠️ Experimental

Expand All @@ -253,13 +255,35 @@ config.job_queue = :langfuse # Placeholder - no effect currently

**Current Behavior:** No ActiveJob integration yet. Reserved for future implementation.

#### `environment`

- **Type:** String
- **Default:** `nil` (or `ENV["LANGFUSE_TRACING_ENVIRONMENT"]` if set)
- **Description:** Default tracing environment applied to new traces/observations

```ruby
config.environment = "production"
```

#### `release`

- **Type:** String
- **Default:** `nil` (or `ENV["LANGFUSE_RELEASE"]` / CI commit env if set)
- **Description:** Default release identifier applied to new traces/observations

```ruby
config.release = "2024.1"
```

## Environment Variables

The SDK automatically reads these environment variables as defaults when no explicit value is configured:

- `LANGFUSE_PUBLIC_KEY` — public API key
- `LANGFUSE_SECRET_KEY` — secret API key
- `LANGFUSE_BASE_URL` — API endpoint (defaults to `https://cloud.langfuse.com`)
- `LANGFUSE_TRACING_ENVIRONMENT` — default trace environment
- `LANGFUSE_RELEASE` — default release identifier (falls back to common CI commit envs if present)

Explicit configuration always takes precedence:

Expand Down