Bug: Traces page stuck on “Configure Tracing” onboarding in events_only mode (hasTracingConfigured is not events-aware)

快速结论：这个报错发生在 Langfuse 自托管实例启用 events_only 写入模式时，Traces 页面会永久卡在 “Configure Tracing” / “Waiting for first trace” 引导界面，即使观测数据（observations）已正常写入并可查询。优先排查 projects.has_traces 标志位是否为 false，或直接执行 UPDATE SQL 绕过该问题。

问题场景

用户在使用 Langfuse v3.205.1 EE（v4 自托管预览版） 时，配置了 LANGFUSE_MIGRATION_V4_WRITE_MODE=events_only 写入模式，通过 Python SDK v4 向新的 Project 写入 traces/observations 数据。打开该 Project 的 Traces 页面后，页面始终显示 “Configure Tracing” 引导界面，无法看到已写入的数据。

报错原文

# 页面表现为永久性 "Configure Tracing" / "Waiting for first trace" 引导屏
# 后端关键判断条件：hasTracingConfigured 返回 false
# tRPC hasTracingConfigured 条件链：
#   hasTracingConfigured = projects.has_traces
#                      || 
#                      || projects.retention_days > 0

原因分析

根本原因是 hasTracingConfigured —> hasAnyTrace(projectId) 检查逻辑只查询了 PostgreSQL projects.has_traces 标志位和 旧版 ClickHouse traces 表。在 events_only 模式下，数据只写入 ClickHouse 的 events 表（events_core/events_full），旧版 traces 表永远不会收到数据，因此 has_traces 永远不会被翻转为 true，hasTracingConfigured 永久返回 false。这是一个 v3 时代遗留的检查，未在 v4 preview 中适配 events_only 模式。

确认数据确实存在的证据：tRPC events.all 返回 200 状态码和观测数据；GET /api/public/v2/observations 返回观测数据；Home 仪表盘显示正确的 Traces/Observations 计数。只有 traces.hasTracingConfigured 返回 false。

环境排查

Langfuse 版本：自托管 v3.205.1 EE（v4 自托管预览版）
关键环境变量：
- LANGFUSE_MIGRATION_V4_WRITE_MODE=events_only
- LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true
- LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct
SDK：Python SDK v4
数据库：ClickHouse（events 表有数据，但旧版 traces 表为空）

解决步骤

临时解决（无副作用，可优先尝试）：在 PostgreSQL 中直接更新 Project 的 has_traces 标志位：
```
UPDATE projects SET has_traces = true WHERE id = '<projectId>';
```
该操作无副作用，执行后引导界面立即消失，正常显示数据。
替代方案：在 Project Settings 中设置 Data Retention > 0（但会启用定期删除旧数据的逻辑，需注意数据保留窗口）。
永久恢复旧行为：将写入模式改为 dual，使旧版 ClickHouse traces 表重新被写入数据。
等待官方修复：PR #13955 已提交，计划在 hasAnyTrace() 中增加 ClickHouse events 表（events_core/events_full）的 fallback 查询，使检查顺序变为：① PostgreSQL project.hasTraces；② ClickHouse 旧版 traces 表；③ ClickHouse events 表。任一来源有数据即可将 has_traces 翻转为 true。

验证方法

执行上述 SQL 更新后，刷新 Traces 页面：如果引导界面消失，显示正常的数据表格（observations 列表），则问题解决。也可通过 tRPC 或 API 确认 hasTracingConfigured 返回 true。

参考来源

langfuse/langfuse #15034

AI 工具推荐

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

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

了解 GamsGo AI

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

Bug: Traces page stuck on “Configure Tracing” onboarding in events_only mode (hasTracingConfigured is not events-aware)