fix(tracing): detach orphan spans before database flush

[erichare]

Summary

Prevent native trace persistence from aborting workflow execution when a completed span references a parent that is not present in the trace's single flush batch.

The existing topological sort already keeps valid parents before children. This change additionally detaches spans from parents that cannot be inserted, preserving the span as a root instead of sending an invalid span.parent_span_id foreign key to the database.

Root cause

topological_sort_spans() treated a parent outside the current batch as though it had already been persisted. Native tracing writes a trace and all of its spans in one batch, so that assumption is invalid for a new trace: an out-of-batch parent row is missing, and PostgreSQL rejects the child row.

Disabling session autoflush does not resolve that case because the referenced row does not exist. It would also change flush semantics for every Langflow database session, well beyond tracing.

Validation

• uv run pytest -q src/backend/tests/unit/services/tracing/test_native_tracer.py — 81 passed
• uv run ruff check src/backend/base/langflow/services/tracing/span_sorting.py src/backend/tests/unit/services/tracing/test_native_tracer.py
• Repository pre-commit checks, including Ruff and detect-secrets

The regression tests cover both layers:

• sorting converts a missing-parent reference to a root span;
• the native database flush receives parent_span_id=None for that span;
• valid parent-before-child ordering remains unchanged.

Credit

Thanks to @ashutoshdharibm for reporting the production impact and investigating the trace flush path in #14229. That PR prompted this focused re-audit of the foreign-key failure.

Relates to DSLF-524.

Summary by CodeRabbit

• Bug Fixes

  • Improved tracing span ordering when a span references a parent that is not included in the current batch.
  • Orphaned spans are now safely detached and persisted without invalid parent references.
  • Added warnings when spans are detached due to missing parents.

• Tests

  • Expanded coverage for span ordering and database flush behavior involving missing parent spans.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 88fabceb-8a1f-4787-b5d0-9d5238e7817f

📥 Commits

Reviewing files that changed from the base of the PR and between ba22f53 and 9463b32.

📒 Files selected for processing (2)

• src/backend/base/langflow/services/tracing/span_sorting.py
• src/backend/tests/unit/services/tracing/test_native_tracer.py

---

Walkthrough

Missing parent references are detached before topological sorting, and database flush tests verify spans are persisted with parent_span_id = None when their parent is absent from the batch.

Changes

Span parent detachment

Layer / File(s)	Summary
Normalize missing parents and validate persistence src/backend/base/langflow/services/tracing/span_sorting.py, src/backend/tests/unit/services/tracing/test_native_tracer.py	Span sorting normalizes unavailable parent UUIDs to None, updates insertion checks, and tests confirm detached spans remain sortable and are flushed without parent links.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 9

✅ Passed checks (9 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main change: detaching orphan spans before database flush.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Coverage For New Implementations	✅ Passed	The PR adds regression tests in test_native_tracer.py for both span sorting and flush detachment, and they assert missing parents become None.
Test Quality And Coverage	✅ Passed	Tests cover sort and async flush behavior with concrete assertions, not smoke tests, and fit the repo’s pytest-asyncio auto-mode pattern.
Test File Naming And Structure	✅ Passed	PASS: The backend test file follows test_*.py pytest structure, uses descriptive test names, async markers, and covers positive/negative edge cases.
Excessive Mock Usage Warning	✅ Passed	Mocks are limited to env/session/logger boundaries; most tests exercise real NativeTracer state and real SpanTable/TraceTable objects, so no excessive mocking.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/native-tracing-orphan-span-fk-release-1.11.1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Test Coverage Advisor

No source changes detected without accompanying tests. Thanks for keeping coverage up! 🎉

Advisory check only — never blocks merge.