bug: Trace name gets updated after creating a new span

问题场景

用户在使用 Langfuse Python SDK 进行 trace 追踪时，调用 start_as_current_span() 并传入已有的 trace_id（通过 trace_context 参数）来创建新 span。此时发现父 trace 的名称被意外更新为新 span 的名称，导致原始 trace 名称丢失。

报错原文

bug: Trace name gets updated after creating a new span
The trace name is being overwritten by the span name when `start_as_current_span()` is called with a `trace_context` containing an existing `trace_id`.

原因分析

可能原因：当 start_as_current_span() 通过 trace_context 加入已有 trace 时，新 span 在本地 OTel 批次中没有 parentSpanId。后端将任何没有本地父级的 span 判定为 isRootSpan = true——该判断仅基于本地 batch 数据，不会查询数据库确认是否实际存在父级。根 span 会触发 trace-create 事件，此时 trace 的 name 来源于 span 名称。由于 trace name 不是不可变属性，采用后写入覆盖（last-write-wins）语义，最后到达的 span 会覆盖 trace 名称。

环境排查

• 确认 Langfuse Python SDK 版本（Issue 未提供，建议升级到最新版）
• 确认 Langfuse Cloud 所在组织是否已启用 v4 预览（如果涉及该问题）
• 检查 trace_context 中 trace_id 的来源和格式是否正确
• 如果使用自托管，确认 Langfuse 服务端版本（Issue 中未提供）

解决步骤

1. 在调用 start_as_current_span() 时，保留原始 trace 名称的引用。
2. 在进入 span 上下文后，调用 span.update_trace(name="你的原始trace名称") 重新设置 trace 名称，示例代码如下：

   with client.start_as_current_span(
       name="new_span",
       trace_context={"trace_id": trace_id},
       input={"message": "Hello World"},
       output={"status": "Hi", "error": "No"},
   ) as span:
       span.update_trace(name="your_original_trace_name")

3. 确认 Span 上下文中的代码执行完毕后，trace 名称保持为原始名称。
4. 如果仍出现覆盖，检查其他并发 span 是否也在修改同一 trace 名称，可能存在竞争条件。
5. 对于长期解决方案，关注 Langfuse Platform v4 的发布，该版本采用不可变数据模型，trace 级 input/output 将被弃用。

验证方法

修复后，在 Langfuse Cloud 中检查该 trace 的详情页面，确认 trace 名称与最初设置的一致，且新创建的 span 名称不会更新 trace 名称。可以多次创建不同名称的 span，并确认 trace 名称始终保持不变。

参考来源

langfuse/langfuse #16273

AI 工具推荐

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

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

了解 GamsGo AI

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