feat(span-processor): mark app root spans

[hassiebp]

What

Adds SDK-side app-root marking for exported spans so Langfuse V4 can default observation tables to the top-most exported observations without relying on the OpenTelemetry root span being exported.

Why

Default and custom span filtering can remove infrastructure or instrumentation spans before export. When that happens, the backend may never receive the original OTEL root span, so filtering the UI by parent_observation_id IS NULL can miss the useful root row. The SDK now marks the best-effort app root on the span before export.

Changes

• Add langfuse.internal.is_app_root as the internal app-root marker attribute.
• Track per-trace, processor-local parent export state in LangfuseSpanProcessor.
• Mark an exported span as an app root when its immediate parent is not expected to export.
• Use langfuse_trace_id baggage for best-effort distributed suppression after active Langfuse spans start.
• Avoid self-suppression by reading baggage from the span's parent context and writing baggage only into the child context used for downstream work.
• Keep internal langfuse_trace_id baggage out of propagated user metadata.
• Add focused unit coverage for filtered parents, sibling roots, baggage suppression, local parent precedence, and start-time false positive behavior.

Limitations

• The decision is best-effort and made at span start using currently available filter information.
• If should_export_span changes its decision by span end, the SDK does not repair already-started descendants.
• Distributed suppression depends on normal OTEL context and baggage propagation.
• Processor-local state is cleaned when spans end; never-ended spans can retain state for that trace.

Verification

• uv run --frozen ruff check langfuse/_client/span_processor.py langfuse/_client/client.py langfuse/_client/propagation.py langfuse/_client/attributes.py tests/unit/test_app_root_detection.py tests/unit/test_propagate_attributes.py
• uv run --frozen ruff format --check langfuse/_client/span_processor.py langfuse/_client/client.py langfuse/_client/propagation.py langfuse/_client/attributes.py tests/unit/test_app_root_detection.py tests/unit/test_propagate_attributes.py
• uv run --frozen mypy langfuse --no-error-summary
• uv run --frozen pytest tests/unit/test_app_root_detection.py tests/unit/test_propagate_attributes.py tests/unit/test_otel.py -q

Greptile Summary

This PR adds best-effort "app root" span detection to the Langfuse SDK so that Langfuse V4 can identify the topmost exported observation per trace even when OTEL infrastructure spans are filtered out before export.

• LangfuseSpanProcessor now tracks per-trace, per-span export-expectation state in a thread-safe dict, marking a span as langfuse.internal.is_app_root at on_start time when its immediate parent is not expected to export. Cleanup runs in on_end's finally block to ensure the state is always released.
• client.py injects a langfuse_trace_id baggage entry into the child context after each start_as_current_observation span starts, enabling distributed suppression for downstream services while avoiding self-suppression.
• The internal baggage key is explicitly excluded from _get_propagated_attributes_from_context to prevent it from surfacing as user metadata.

Confidence Score: 3/5

The feature is logically sound and the threading model is correct, but _get_readable_span relies on a private OTel SDK method that, if ever removed or renamed, will silently disable app-root marking across the entire SDK with only a DEBUG-level log.

The core detection and cleanup logic is well-designed and the new test coverage is thorough. The risk is concentrated in _get_readable_span, which bridges from the mutable Span seen at on_start to the ReadableSpan interface expected by _should_export_span. Using span._readable_span() achieves this, but if the OTel SDK drops the private method the feature degrades invisibly with no warning and no fallback.

langfuse/_client/span_processor.py, specifically the _get_readable_span static method around line 311.

Sequence Diagram

sequenceDiagram
    participant C as Client (start_as_current_observation)
    participant SP as LangfuseSpanProcessor
    participant BS as BatchSpanProcessor

    C->>SP: on_start(span, parent_context)
    SP->>SP: _mark_app_root_candidate(span, parent_context)
    note over SP: Reads langfuse_trace_id from parent_context baggage
    SP->>BS: super().on_start(span, parent_context)
    SP-->>C: returns

    C->>C: attach baggage token (langfuse_trace_id)
    C->>C: yield Langfuse span wrapper

    C->>C: finally: detach baggage token

    C->>SP: on_end(span)
    SP->>SP: project/scope/filter checks
    alt should export
        SP->>BS: super().on_end(span)
    end
    SP->>SP: finally: _cleanup_app_root_state(span)

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
langfuse/_client/span_processor.py:311-317
**Private OTel SDK API creates silent feature degradation path**

`_readable_span` is a private method on `opentelemetry.sdk.trace.Span`. If the OTel SDK ever renames or removes it, `getattr` returns `None`, the callable check raises `TypeError`, which is caught by the `try/except` in `on_start` at DEBUG level — and the entire `IS_APP_ROOT` feature silently stops working with no user-visible error. Since `opentelemetry.sdk.trace.Span` already implements `ReadableSpan` (it inherits from it), you can replace the private accessor with a direct cast: `cast(ReadableSpan, span)`. This removes the fragile dependency without changing runtime behavior.

### Issue 2 of 2
tests/unit/test_propagate_attributes.py:1638-1641
Import added inside a test method — the team's style rule requires imports to live at the top of the module, not nested inside functions or methods. The pre-existing `from opentelemetry import baggage` and `from opentelemetry import context as otel_context` in this same method also violate the rule, but this PR adds a third one. All three should be hoisted to the module level.

```suggestion
        from opentelemetry import baggage
        from opentelemetry import context as otel_context
```

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into add-app-root-sp..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Rule used - Move imports to the top of the module instead of p... (source)

Learned From
langfuse/langfuse-python#1387

[github-actions]

@claude review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fffa395845

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba553a13db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.