bug: Observations API v2 traceName becomes null for generation records starting ~2026-09-15 (Langfuse Cloud)

问题场景

用户使用 Langfuse Cloud，通过 Python SDK 的 client.api.observations.get_many(...) 导出生产环境 GENERATION observation，并在 fields 中包含 trace_context。在按 observation 起始时间分批导出时发现：2026-09-14 的数据中，子 generation 的 traceName 全部有值；2026-09-15 当天约 ~10:00 UTC 之后开始出现 null，全天约 11% 有值、89% 为 null；2026-09-16 起子 generation 的 traceName 全部为 null。同一 traceId 的根 observation 的 traceName 仍然有值。用户使用 langfuse.openai.AsyncOpenAI 创建子 generation，生产者侧此前从 Langfuse Python SDK v3 迁移到 v4。

报错原文

bug: Observations API v2 traceName becomes null for generation records starting ~2026-09-15 (Langfuse Cloud)

{ "name": "OpenAI-generation", "traceName": null, "isRootObservation": false }

{ "name": "my-workflow", "traceName": "my-workflow", "isRootObservation": true }

原因分析

核心原因不是 Python SDK 反序列化失败，也不是字段从响应模型中消失。Issue 中已确认原始 HTTP 响应里子 generation 明确返回 "traceName": null（键存在、值为 null）。在与维护者讨论后，问题指向 Langfuse Python SDK v4 的传播行为变化：v4 中仅给根 observation 设置 name=... 并不会自动把该名称作为 trace 名称传播给子 generation；而旧版 SDK（维护者称为“pre v4”）会自动传播。用户的生产者在 2026-08-24 从 SDK v3 迁移到 v4，并且在受影响的时间段内没有调用 propagate_attributes(trace_name=...)，因此由 langfuse.openai 自动创建的子 generation 不再自动获得 trace 名称。用户随后测试在 propagate_attributes 中显式加入 trace_name=func.__name__，问题看起来得到解决。

环境排查

• 确认部署方式：是否为 Langfuse Cloud（本 Issue 为 Cloud 用户）。
• 确认 Python 版本：Issue 中为 Python 3.12。
• 确认生产者 SDK 版本：langfuse-python=4.15.3 和 4.14.6。
• 确认生产者是否已从 SDK v3 迁移到 v4（例如使用 start_as_current_observation、propagate_attributes）。
• 确认创建子 generation 的方式：是否为 langfuse.openai.AsyncOpenAI 等 integration 自动创建，而非手动通过 Langfuse SDK 创建。
• 确认代码中是否显式设置 propagate_attributes(trace_name="...")，以及该调用是否包裹了创建子 generation 的代码。
• 确认导出请求参数：fields="core,basic,usage,metrics,trace_context,model"、type="GENERATION"、时间边界为带时区的 UTC datetime，并跟随所有分页 cursor。

解决步骤

1. 在生产者代码中，把创建根 observation 和子 generation 的逻辑包在 propagate_attributes(trace_name=...) 上下文中。Issue 中用户验证有效的写法是在 propagate_attributes 内加入 trace_name=func.__name__。
2. 确保 propagate_attributes(trace_name=...) 的作用范围覆盖真正产生子 generation 的调用（例如 await func(...) 中通过 langfuse.openai.AsyncOpenAI 发起的 LLM 调用）。
3. 不要在 v4 下只依赖根 observation 的 name=... 来自动传播 trace 名称到子 generation。
4. 修正后重新运行生产导出，针对新产生的数据确认子 generation 的 traceName 是否恢复为非空。
5. 如果需要在导出侧回收历史数据的 trace 名称，可按 Issue 中用户提出的思路，通过 Observations API v2 查找同一 traceId 的逻辑根 observation，再用 traceId 做关联恢复子 generation 的标签；Issue 中未给出完整实现。
6. 如果历史缺失值怀疑来自 Cloud 侧迁移或 enrichment 问题，Issue 中未确认可服务端修复，应通过 Langfuse 官方支持渠道提供项目标识和受影响的 trace/observation ID 进一步核查。

验证方法

在修正后的生产者代码上发起新的 trace，然后使用相同的 client.api.observations.get_many(...) 查询条件导出对应的子 GENERATION observation，检查响应中 traceName 是否为期望的 trace 名称而非 null；同时确认同一 traceId 的根 observation 的 traceName 仍保持正常。若仅做原始 HTTP 验证，应直接查看响应体中 traceName 字段的值，而不是只依赖 SDK 模型属性。

参考来源

langfuse/langfuse #17636

AI 工具推荐

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

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

了解 GamsGo AI

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