fix: detach root observations from the host application's ambient OpenTelemetry context

[Eth3rnit3]

Problem

create_otel_span creates root observations with:

else
  # Create root span
  otel_tracer.start_span(name, start_timestamp: start_time)
end

Tracer#start_span implicitly parents the new span to OpenTelemetry::Context.current. That context is process-wide and provider-agnostic — it is not scoped to the TracerProvider the tracer came from. So this branch only produces an actual root span when nothing else is currently active.

In a host application that runs its own OpenTelemetry instrumentation (Rack, ActiveJob, Sidekiq…) on a separate provider — a very common setup — a root observation started inside an instrumented request or job silently becomes a child of that ambient span.

The consequence is only visible on the Langfuse side: Langfuse ingests the child, whose trace_id belongs to a root span that was exported to the application's own backend and never reaches Langfuse. The UI then renders an empty, unnamed trace wrapping the real observation. Grouping or filtering by trace name becomes unusable, since a large share of traces have no name at all.

This is distinct from the isolated tracer provider introduced in 0.8.0 (#77): that change isolates which spans are exported to Langfuse (and it works — thank you for it). This issue is about which span a new span is parented to, which context propagation decides independently of the provider.

Fix

Reset to OpenTelemetry::Context::ROOT for the duration of the root span creation only:

OpenTelemetry::Context.with_current(OpenTelemetry::Context::ROOT) do
  otel_tracer.start_span(name, start_timestamp: start_time)
end

Nesting is deliberately unaffected: once the span is started it becomes current again, so child observations keep attaching to it, and the caller's ambient context is restored on the way out. The child branch is untouched.

Tests

Three specs under .start_observation, covering the fix and the two properties a naive fix would break:

• a root observation gets its own trace, not the ambient one (fails on main, passes with the change);
• child observations still nest under the root;
• the caller's ambient context is restored afterwards.

bundle exec rspec spec/langfuse_spec.rb → 100 examples, 0 failures. rubocop clean on both changed files.

Happy to adjust naming, comment length or spec placement to your preferences.

---

Note

Medium Risk
Changes core root-span parenting in mixed OpenTelemetry setups; incorrect detection of “foreign” vs Langfuse ambient spans could mis-nest traces, though the scope check and new specs narrow the blast radius.

Overview
Fixes root Langfuse observations being parented to the host app’s unrelated OpenTelemetry span when Rack/ActiveJob/Sidekiq (or another provider) already has Context.current set. Those roots showed up in Langfuse as orphan children under empty, unnamed traces.

Root span creation in create_otel_span now temporarily clears only the active span (invalid span in context) before start_span, so a new trace_id is generated without wiping propagate_attributes context values. If the ambient span is Langfuse’s own (ambient_langfuse_span? via tracer instrumentation scope), behavior is unchanged so nested observe / start_observation calls still attach.

Adds specs for a foreign ambient span: own trace_id, nested children, restored caller context, nested Langfuse observations, and propagated user.id / session.id.

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

[cursor]

Stale Bugbot comment from a previous run.

[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.}

^{Reviewed by Cursor Bugbot for commit 60ac94a. Configure here.}

[kxzk]

I checked this against langfuse-js and langfuse-python. Both preserve the active OpenTelemetry context, including with isolated providers. The JS SDK documents this explicitly. Both handle Langfuse application-root identification separately, and Ruby main already does the same.

I also reproduced two regressions in the current patch:

• When sampling drops a Langfuse parent, that span has no instrumentation scope. The guard treats it as foreign. A nested observation can then start a new trace and be exported independently.
• A third-party span can use Langfuse’s own provider. The guard still treats it as foreign, splitting an existing parent-child tree.

Both checks pass on main and fail with this PR.

Could you add a minimal reproduction of the empty or unnamed trace on current main, including the Ruby SDK and Langfuse server versions? That would help establish the cause before we change default parentage.