bug(python-sdk): trace_context creates phantom parent observations with no input/output in v4 preview UI

快速结论：此问题发生在使用 Langfuse Python SDK 进行分布式追踪时，通过 trace_context={"trace_id": "..."} 加入已有 trace 但未提供 parent_span_id。优先排查：在调用 start_as_current_observation 时，手动为 root observation 设置内部属性 langfuse.internal.as_root="true"，或在上下游服务间传递实际的 parent_span_id。

问题场景

用户在使用 Langfuse Python SDK 构建分布式追踪（跨多个 Python 服务共享同一个 trace_id）时触发。典型场景是服务 A（编排器）创建一个 root observation，服务 B（下游工具服务）通过 trace_context 加入同一 trace，但仅提供了 trace_id，未传递 parent_span_id。

报错原文

When using start_as_current_observation(trace_context={"trace_id": "..."}) for distributed tracing, 
the SDK creates a NonRecordingSpan with a random span_id as the parent.

This phantom parent:
1. Shows up as an empty observation in the v4 preview UI (no input, no output, no metadata)
2. Causes ALL observations to have parentObservationId set, so the "Is Root Observation" filter returns False for everything
3. Makes it significantly harder to navigate traces in the new observation-centric UI

The SDK sets langfuse.internal.as_root = True on the actual observation, 
but the v4 preview UI does not appear to use this attribute — it determines root-ness from parentObservationId IS NULL.

原因分析

当 trace_context 中仅有 trace_id 而没有 parent_span_id 时，SDK 内部的 _create_remote_parent_span() 方法会生成一个带有随机 span_id 的 NonRecordingSpan 作为 OTel 父级。这个 span 永远不会被导出，但真实的 observation 会继承其 span_id 作为 parentSpanId。后端多模态处理器的根检测逻辑要求 parentObservationId 为 null 或 langfuse.internal.as_root 属性为 "true"。由于这两个条件均未满足，每个 observation 都会显示为一个非根的、带有空白父 observation 的子节点。

SDK 确实对该 observation 设置了 langfuse.internal.as_root = True，但 v4 preview UI 的根检测逻辑先判定 parentObservationId IS NULL，且未使用该内部属性进行补偿。后端存在一个补救机制（langfuse.internal.as_root 属性），但 Python SDK 在此场景下并未自动设置它。

环境排查

Langfuse Python SDK 版本（如 2.x 或 3.x 系列）
OpenTelemetry SDK 及 API 版本
Langfuse 后端版本（是否使用 v4 preview UI）
服务间传递 trace_context 的具体方式（trace_id 是否包含连字符）

解决步骤

手动设置内部属性（立即解决，但非公开 API 可能变更）：在 start_as_current_observation 的上下文中，对当前 OTel span 设置属性：

from opentelemetry import trace as otel_trace

with langfuse.start_as_current_observation(
    as_type="span",
    name="orchestrator_agent",
    trace_context={"trace_id": trace_id.replace("-", "")},
    input={"user_query": "..."},
) as root_span:
    otel_trace.get_current_span().set_attribute("langfuse.internal.as_root", "true")
    # ... rest of your logic

此属性是后端已检查的内部机制，可优先尝试。

传递完整 parent_span_id（更彻底的方案）：如果上游服务已创建 root observation，通过 get_current_observation_id() 获取实际的 parent_span_id，并连同 trace_id 一起传递给下游服务。这可以完全避免幻影父节点的产生。
观察 SDK 更新：关注 Langfuse Python SDK 的发布说明，看是否有针对此场景的自动修复（例如，SDK 自动设置 langfuse.internal.as_root=true 或跳过 NonRecordingSpan 创建）。

验证方法

在 v4 preview UI 中检查该 trace：确认不再出现空白（无输入/输出/元数据）的父 observation，且 root observation 的 parentObservationId 为 null，“Is Root Observation” 过滤器返回 true。同时，确认分布式追踪中各服务的观察仍保持正确的 trace_id 关联。

参考来源

langfuse/langfuse #12896 — 包含评论链、相关 PR #8008 和 #12307 的讨论，以及后端处理器源码引用。

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

bug(python-sdk): trace_context creates phantom parent observations with no input/output in v4 preview UI