FEATURE: add Config#valid? and Langfuse.configured?

[Alan-Marx]

TL;DR

Introduces non-raising Langfuse.configured? and Langfuse::Config#valid? methods.

Why

Langfuse might not be configured in all application environments. Application code therefore needs a way to check whether an operation should be wrapped in a Langfuse observation or not. The only way to do that at the moment is to manually check ENV vars or call Langfuse.configuration.validate! and rescue the call.

This PR adds some new convenience methods to make these guards easier to write:

• Adds Config#valid? — a non-raising predicate that returns true/false instead of raising ConfigurationError
• Adds Langfuse.configured? — a module-level convenience method delegating to configuration.valid?
• Replaces the internal tracing_config_ready? helper (which only checked three fields) with direct calls to configuration.valid?, so tracing readiness now requires a fully valid config. This is technically a stricter guard, however given that most Langfuse operations will trigger a full configuration validation via Langfuse::Client I think this is justified.
• Updates the error message in tracer_provider to reflect the broader validation

Checklist

• Tests added for new behavior
• Docs updated (if user-facing)

---

Note

Medium Risk
Changes when tracing starts vs when the API client validates, and alters failure modes for misconfigured export settings; behavior is covered by new specs but affects observability in production.

Overview
Adds Config#valid? and Langfuse.configured? so apps can guard Langfuse usage without rescuing ConfigurationError. These reflect client config validity (credentials, cache, timeouts, etc.), not whether tracing can start.

Validation is split and tightened: validate! now uses shared type-aware helpers so bad types (e.g. string timeouts, non-string keys, bogus cache_stale_ttl) raise ConfigurationError instead of ArgumentError/NoMethodError. validate_tracing! is a separate, narrower check (credentials, should_export_span, batch_size, flush_interval) used when OTel setup runs; invalid client-only settings no longer block tracing, and invalid batch_size/flush_interval no longer fail full client validation.

Tracing behavior: lazy setup calls validate_tracing! via OtelSetup; failures on observe/start_observation emit a one-time warning naming the bad setting and use a no-op tracer (safe with nil logger). Langfuse.tracer_provider still raises, with messages prefixed by “Langfuse tracing is disabled: …”. Docs and changelog updated to describe the distinction between configured vs tracing-ready.

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

[kxzk]

Pushed a revision (d887e03) implementing AAI-338 — keeps the new Config#valid? / Langfuse.configured? predicates but decouples tracing readiness from full config validity:

• Tracing gating restored: internal readiness now uses a new Config#validate_tracing! (credentials, base_url, should_export_span, batch_size, flush_interval) instead of configuration.valid?, so an invalid cache setting (e.g. bad cache_backend) can no longer silently disable tracing. This matches the Python/JS SDKs, where tracing and client config are orthogonal.
• valid? can't leak non-ConfigurationError exceptions: validate! now uses type-safe helpers, so string/symbol numerics and non-string credentials raise ConfigurationError instead of ArgumentError/NoMethodError.
• SpanProcessor crash surface closed: batch_size/flush_interval are validated before tracing setup (previously batch_size = nil crashed with NoMethodError inside SpanProcessor). Tracing-disabled warnings and Langfuse.tracer_provider errors now name the specific offending setting.
• Release flow restored: version reverted to 0.10.1 and changelog entries moved back under [Unreleased] — version bumps happen via the release tooling, not feature PRs.

Verified: 1369 specs green (96.91% coverage), rubocop clean, and a live end-to-end check — with valid credentials plus cache_backend = :bogus, an observation was created, flushed, and read back from Langfuse (configured? correctly returns false while tracing stays fully functional).

[cursor]

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

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

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 15911b7. Configure here.}

[cursor]

Incomplete nil logger hardening

Medium Severity

Safe-navigation on config.logger lets OtelSetup.setup succeed when logger is nil, but SpanProcessor still calls @logger.error without nil-safety when should_export_span raises. That turns the intended span-drop path into a NoMethodError during finish. This is easy to hit because Config#default_logger can return a nil Rails.logger.

Additional Locations (1)

• lib/langfuse/otel_setup.rb#L87-L93

 

^{Reviewed by Cursor Bugbot for commit 15911b7. Configure here.}