bug: Intermittent traces.filterOptions Request Timed Out on self-hosted Langfuse v3.200.0

问题场景

用户自托管 Langfuse v3.200.0（Docker Compose），ClickHouse 26.6.1 为后端数据库。打开 Traces 页面时偶发超时，报错 traces.filterOptions Request Timed Out；关闭弹窗后立即重试可成功。相同请求在正常时仅需 300–700 ms。另外还观察到 scores.getScoreColumns 和 projects.environmentFilterOptions 也间歇性失败，返回 HTTP 422 ClickHouseResourceError。

报错原文

Request Timed Out
Path: traces.filterOptions

HTTPSConnectionPool(...) Read timed out. (read timeout=4.99999)

HTTP 422
ClickHouseResourceError
"Your query could not be completed. Please narrow your request..."

原因分析

可能原因是 ClickHouse 26.6.x 版本中新的查询分析器（默认启用）对 FINAL + LEFT JOIN 模式存在已知回归，导致部分查询偶发性能下降或错误。同时，Langfuse 的 traces.filterOptions 端点会并行执行 6 个过滤查询（trace 名称、标签、用户等），这些查询未设置自定义超时，继承 ClickHouse 客户端默认约 30 秒超时，在回归影响下容易超时。此外，如果 Langfuse 版本未包含 PR #13335/#13336 的时间范围限定修复，查询可能扫描整个表（即使数据量小），增加资源争用。

环境排查

• 确认 ClickHouse 版本：SELECT version()，若是 26.x 则需降级或设置 CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION=true。
• 确认 Langfuse 版本：v3.200.0 是受影响版本，升级到最新版（含 PR #13335、#13336）可减少全表扫描。
• 检查 ClickHouse 表合并状态：SELECT count() FROM system.parts WHERE table='traces' AND active=1，若 parts 过多说明合并延迟。
• 确认 Nginx/Docker 网络、CPU、内存健康（Issue 中已检查正常，但仍可复查）。
• 如有只读 ClickHouse 副本，可配置 CLICKHOUSE_READ_ONLY_URL 将查询路由到副本。

解决步骤

1. 降级 ClickHouse：在 docker-compose.yml 中将 ClickHouse 镜像版本改为 clickhouse/clickhouse-server:24.3，然后重启容器（注意数据兼容性，建议先备份）。
2. （备选）禁用 26.x 回归优化器：若必须保留 26.6.1，在 ClickHouse 服务环境变量中添加 CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION=true，重启 ClickHouse 容器。
3. 升级 Langfuse：将 Langfuse 升级到最新稳定版本（≥ v3.200.0 之后修复版本），确保包含 PR #13335 和 #13336 的时间范围过滤优化。
4. 手动合并 ClickHouse 表 parts：在 ClickHouse 客户端执行 OPTIMIZE TABLE traces FINAL 和 OPTIMIZE TABLE scores FINAL，减少合并开销。
5. （可选）配置只读副本：若存在只读 ClickHouse 副本，设置 CLICKHOUSE_READ_ONLY_URL 环境变量，让过滤查询走副本，降低主库负载。

验证方法

反复打开 Traces 页面，观察是否不再出现 Request Timed Out 弹窗。也可监控 ClickHouse 慢查询日志（system.query_log），确认 filterOptions 相关查询耗时恢复至正常范围（300–700 ms）。同时检查是否有 HTTP 422 ClickHouseResourceError 持续出现。

参考来源

langfuse/langfuse #15529