bug: incorrect value for dashboard widget for unique user ids count

快速结论：该 bug 出现在 Langfuse 仪表盘的自定义 Big Number/Count 小部件中，当 Metric 选择 “Unique User IDs / Count” 时，小部件错误地返回了所有 trace 的总数，而非去重后的唯一用户数。优先排查 Langfuse 版本是否已包含修复（PR #9808），升级到包含该 PR 的版本（在 v3.129.0 之后）通常可解决。

问题场景

在 Langfuse 的自托管或云版仪表盘中，用户创建了一个自定义小部件，配置为：视图（View）选择 “Traces”，指标（Metric）选择 “Unique User IDs / Count”，图表类型（Chart Type）选择 “Big Number”。当项目中有多个 trace 但都来自同一个用户（如 user1）时，小部件显示的是 trace 总数（例如 10），而不是预期的唯一用户数（应为 1）。同时，该 bug 也影响 “Unique Session IDs” 指标。

报错原文

# 核心表现：小部件显示的值为 trace 总数，而非唯一用户数。
# 例如：10 条 trace 全为 user1，显示 10，预期为 1。

原因分析

该 bug 的根本原因是：仪表盘小部件在计算 “Unique User IDs / Count” 时，错误地使用了简单的计数聚合（count），而不是计算去重后的用户 ID 数量（即 distinct count）。在后台 SQL 查询中，缺少类似 uniq(traces.user_id) 的去重逻辑，导致返回了项目中的所有 trace 条数。

环境排查

• 确认 Langfuse 版本（自托管用户请检查版本号，例如 v3.129.0 或更早/更新版本）。
• 确认小部件的配置：视图（View）为 Traces，指标（Metric）为 Unique User IDs / Count，图表类型为 Big Number。
• 验证项目是否有多条 trace 但仅来自同一用户（或少量用户），以复现数值偏大问题。
• 检查 “Observability / Users” 页面中显示的唯一用户数量是否与预期一致（此处正确），用于对比确认 bug 仅存在于仪表盘小部件。

解决步骤

1. 升级 Langfuse 版本：确认您的 Langfuse 版本是否包含了 PR #9808 的修复。该 PR 在 Trace 视图的小部件指标中引入了正确的去重聚合（使用 SQL 的 uniq(traces.user_id) 和 uniq(traces.session_id)）。如果版本早于该 PR 的合并时间（2026-02-11 之后），建议升级到最新稳定版。
2. 重启服务：升级后，确保重启 Langfuse 服务（如果使用 Docker Compose，运行 docker compose down && docker compose up -d；如果使用其他部署方式，请按相应方式重启）。
3. 重新打开仪表盘：刷新浏览器或重新打开仪表盘页面，让前端加载最新的小部件配置。
4. （可选）如果升级后问题仍然存在，尝试删除该小部件并重新创建，以确保配置正确加载。

验证方法

在升级并重启服务后，重新打开仪表盘，观察自定义的 “Unique User IDs / Count” 小部件：

• 如果项目中有 10 条 trace 全部来自 user1，小部件应显示 1（而不是 10）。
• 对比 “Observability / Users” 页面中显示的唯一用户数，两者应一致。
• 同样，测试 “Unique Session IDs” 小部件，确认其也返回去重后的 session 数量。

参考来源

langfuse/langfuse #10405