bug: v4-tagged OTEL ingestion not queryable on /api/public/v2/observations for minutes while worker/ClickHouse idle

问题场景

用户在自托管 Langfuse v4.76.0 上，以 events_only 写模式和 direct OTEL 方式接入：通过 POST /api/public/otel/v1/traces 并携带请求头 x-langfuse-ingestion-version: 4 写入 span（每条 observation 都带 session.id、user.id，含标准 gen_ai.* 语义约定及 langfuse.trace.tags / langfuse.trace.metadata.*）。写入 POST 返回成功后，立即用 GET /api/public/v2/observations 按刚写入的 trace 过滤轮询，却持续数分钟查不到结果，而 worker 与 ClickHouse 的 CPU 均低于 5%，基本处于空闲状态。

报错原文

bug: v4-tagged OTEL ingestion not queryable on /api/public/v2/observations for minutes while worker/ClickHouse idle

原因分析

根据 Issue 的后续更新，触发点在用户侧的自定义接入逻辑：部分 span 被写入 start_time = 0（即 1970-01-01）。把时间改为真实的当前时间后，对应 trace 立即可查，因此延迟并非由 worker 或 ClickHouse 资源不足、队列积压导致（全程 CPU/内存占用都很低，延迟与负载无关）。

可优先考虑的另一层原因：调用 GET /api/public/v2/observations?traceId=<id> 时只带 traceId，没有 fromTimestamp/toTimestamp。结果集按时间从新到旧排序，traceId 过滤未能短路这次按时间顺序的扫描，对于 1970 年的 trace，就会返回空但带游标的分页，需要翻过大量无关页才能命中。维护者回复明确这是 v2 API 规范内的行为变更，而非 bug，并指出不指定时间边界的查询本身就不理想。

环境排查

• 确认 Langfuse 版本：是否为自托管 v4.76.0，是否由 v4.54.0 升级而来（该现象在 v4.54.0 上未复现）。
• 确认写模式为 events_only，OTEL 行为为 direct，并核对请求头 x-langfuse-ingestion-version: 4。
• 检查写入侧 span 的 start_time 是否为 0 或其它异常值（例如 1970 年），逐条核对自定义接入代码是否覆盖了真实时间。
• 检查 worker 与 ClickHouse 的 CPU、内存是否有持续饱和或队列积压（Issue 中两者均低于 5%）。
• 核对查询请求是否携带 fromTimestamp/toTimestamp 时间窗口。
• 确认部署形态（ECS Fargate 下 web、worker、单节点 ClickHouse 分离，另有 Redis、S3），以及 worker / ClickHouse 的规格，是否与 Issue 环境一致。
• 确认查询侧 SDK 版本（Issue 使用 4.15.5）。

解决步骤

1. 排查并修正数据源头：在自定义 OTEL 接入逻辑中定位被写成 start_time = 0（1970-01-01）的 span，改为真实当前时间。Issue 报告者确认修正后对应 trace 立即可查。
2. 修正后重新写入一条测试 trace，随后立即查询，确认不再出现数分钟延迟。
3. 对查询侧（可优先尝试）：为 GET /api/public/v2/observations 显式提供 fromTimestamp/toTimestamp 时间窗口，避免无时间边界的查询按时间序扫描全量数据；若按 traceId 查询仍返回空但带游标的分页，应继续翻页或补上时间范围。
4. 若数据时间戳正常且已加时间窗口仍然延迟，再按 Issue 中提出的问题方向排查 v4 的 events → v2/observations 可见性机制（是否有固定间隔的投影或物化步骤），注意这一点 Issue 中没有给出结论。

验证方法

写入一条时间戳正确的 trace（或修正 start_time = 0 的历史数据）后，立即带时间范围调用 GET /api/public/v2/observations?traceId=<id>，确认对应 observation 在预期的秒级窗口内返回，而不是返回空但带游标的分页。同时观察 worker 与 ClickHouse 的 CPU 仍然很低，以确认问题与资源无关。

参考来源

langfuse/langfuse #19976

AI 工具推荐

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

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

了解 GamsGo AI

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