feat(config): add telemetry kill switch

[kxzk]

TL;DR

Applications can disable Langfuse tracing and scoring without removing credentials or changing call sites.

Why

The SDK needs a complete telemetry kill switch for incident response, tests, and environments that must not export telemetry.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

Note

Kade's words:

Summary

Applications can now set tracing_enabled = false or LANGFUSE_TRACING_ENABLED=false. Explicit Ruby configuration overrides the Langfuse environment variable. OTEL_SDK_DISABLED=true always disables telemetry.

Disabled trace and score calls are no-ops. They do not require credentials or create requests. Prompt and data API construction stays deferred, so those calls still validate the normal configuration when used. Existing enabled behavior stays unchanged.

Change diagram

flowchart TD
    accTitle: Langfuse telemetry kill switch
    accDescr: Configuration selects enabled telemetry or no-op trace and score behavior while API calls retain normal validation.
    C["Read telemetry configuration"] --> E{"Telemetry enabled"}
    E -->|"Yes"| T["Create trace and score clients"]
    E -->|"No"| N["Use no-op tracing and scoring"]
    N --> P["Defer prompt and data API client"]
    P --> V["Validate configuration on API use"]

Loading

Verification

I ran the complete RSpec suite locally. All 1,586 examples passed. Line coverage was 97.28%.

I ran RuboCop against 100 files. RuboCop reported no offenses.

The enabled Ruby SDK probe delivered trace 37df4a1e645254a82760e18daa9b41a6 and its score. The disabled probe used trace ID 1ecdcf1ebb5833d8c9f4931e9e76ea0b. Its span was non-recording, and both score APIs returned nil. The Langfuse CLI found the enabled trace and score. The CLI found no observation or score for the disabled trace ID.

Unit tests also cover OTEL_SDK_DISABLED=true, environment precedence, explicit Ruby precedence, missing credentials, and deferred prompt validation. I did not preview the rendered Mermaid diagram in GitHub. I reviewed the Mermaid source and syntax locally.

---

Note

Medium Risk
Changes core initialization, runtime telemetry toggling, and export paths; behavior is broad but covered by new specs and mostly fails closed when disabled.

Overview
Adds a tracing_enabled / LANGFUSE_TRACING_ENABLED kill switch so Langfuse tracing and scoring can be turned off without changing call sites. When disabled, observe and score APIs become no-ops (no credentials, no network); create_score! returns nil; buffered spans are dropped via TraceExportGuard on export/flush. OTEL_SDK_DISABLED=true only stops trace export while score ingestion can still run when telemetry is on.

Client no longer always validates credentials at boot: telemetry-off clients use validate_telemetry_disabled!, and the API/score clients are built lazily so prompt/data APIs still enforce full config on first use. Langfuse.configured?, tracer_provider, and ensure_tracing_started respect trace_export_enabled? and fall back to a shared no-op tracer provider.

Also adds PromptVariables and #variables on text/chat prompt clients to list Mustache variables (sections, nested paths; chat skips placeholders), plus docs and specs for the new behavior.

^{Reviewed by Cursor Bugbot for commit 6408b2a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

AAI-391

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9aa3f32. Configure here.}