🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
/* eslint-disable no-nested-ternary */
import { useRouter } from "next/router";
import { useCallback, useEffect, useMemo, useRef } from "react";
import {
NumberParam,
StringParam,
useQueryParam,
useQueryParams,
withDefault,
} from "use-query-params";
import { DataTableToolbar } from "@/src/components/table/data-table-toolbar";
import { DataTable } from "@/src/components/table/data-table";
import {
DataTableControls,
DataTableControlsProvider,
} from "@/src/components/table/data-table-controls";
import { StickySearchableTableFilterLayout } from "@/src/components/table/resizable-filter-layout";
import { createTagTableColumn } from "@/src/components/design-system/table/columns/createTagTableColumn";
import { createLinkTableColumn } from "@/src/components/design-system/table/columns/createLinkTableColumn";
import { createTextTableColumn } from "@/src/components/design-system/table/columns/createTextTableColumn";
import { type LangfuseColumnDef } from "@/src/components/table/types";
import { getUsersFilterConfig } from "@/src/features/filters/config/users-config";
import {
USERS_FIELD_REGISTRY,
LEGACY_USERS_FIELD_REGISTRY,
} from "@/src/features/filters/config/usersSearchRegistry";
import {
useSidebarFilterPresentation,
useSidebarFilterStateCore,
type FacetOptions,
type UseSidebarFilterStateOptions,
} from "@/src/features/filters/hooks/useSidebarFilterState";
import { buildSidebarFilterSessionContextId } from "@/src/features/filters/lib/persistedSidebarFilterQuery";
import { sortOptionValues } from "@/src/features/filters/lib/option-sort";
import { useDetailPageLists } from "@/src/features/navigate-detail-pages/DetailPageListsProvider";
import { useEventsFilterOptions } from "@/src/features/events/hooks/useEventsFilterOptions";
import { TableSearchBar } from "@/src/features/search-bar/components/TableSearchBar";
import { toObservedOptions } from "@/src/features/search-bar/lib/observed-options";
import { useTableViewManager } from "@/src/components/table/table-view-presets/hooks/useTableViewManager";
import { useTableViewFilterChange } from "@/src/components/table/table-view-presets/hooks/useTableViewFilterChange";
import { default as useColumnOrder } from "@/src/features/column-visibility/hooks/useColumnOrder";
import { default as useColumnVisibility } from "@/src/features/column-visibility/hooks/useColumnVisibility";
import { api } from "@/src/utils/api";
import { compactNumberFormatter, usdFormatter } from "@/src/utils/numbers";
import { type RouterOutput } from "@/src/utils/types";
import {
DEFAULT_SIDEBAR_IMPLICIT_ENVIRONMENT_CONFIG,
TableViewPresetTableName,
type FilterState,
type TimeFilter,
} from "@langfuse/shared";
import { joinTableCoreAndMetrics } from "@/src/components/table/utils/joinTableCoreAndMetrics";
import { useTableDateRange } from "@/src/hooks/useTableDateRange";
import { toAbsoluteTimeRange } from "@/src/utils/date-range-utils";
import { TableHeaderControls } from "@/src/components/table/TableHeaderControls";
type RowData = {
userId: string;
environment?: string;
firstEvent: string;
lastEvent: string;
totalEvents: string;
totalTraces: string;
totalTokens: string;
totalCost: string;
};
export function UsersTable({
isV4,
showControlsInPageHeader = false,
}: {
isV4: boolean;
showControlsInPageHeader?: boolean;
}) {
const router = useRouter();
const projectId = router.query.projectId as string;
// The two read paths answer different facet sets from different tables, so
// they get different configs — and different persistence keys, or a v4-only
// filter would rehydrate on a v3 project as a failed query.
const usersFilterConfig = useMemo(() => getUsersFilterConfig(isV4), [isV4]);
const { setDetailPageList } = useDetailPageLists();
const [paginationState, setPaginationState] = useQueryParams({
pageIndex: withDefault(NumberParam, 0),
pageSize: withDefault(NumberParam, 50),
});
// The picker renders in the page header via the header controls slot; this
// reads the same shared per-project range to filter the table.
const { timeRange, setTimeRange } = useTableDateRange(projectId);
// Convert timeRange to absolute date range for compatibility
const dateRange = useMemo(() => {
return toAbsoluteTimeRange(timeRange) ?? undefined;
}, [timeRange]);
// Both users queries map "Timestamp" onto their own time column
// (`t.timestamp` on v3, `e.start_time` on v4), so one filter serves both.
const dateRangeFilter = useMemo<FilterState>(
() =>
dateRange
? [
{
column: "Timestamp",
type: "datetime",
operator: ">=",
value: dateRange.from,
},
{
column: "Timestamp",
type: "datetime",
operator: "<=",
value: dateRange.to,
},
]
: [],
[dateRange],
);
const { viewControllersRef, onExplicitFilterStateChange } =
useTableViewFilterChange();
const filterStateOptions: UseSidebarFilterStateOptions = useMemo(
() => ({
stateLocation: "urlAndSessionStorage",
onExplicitFilterStateChange,
sessionFilterContextId: buildSidebarFilterSessionContextId(projectId),
// Environment is a sidebar facet here, like every other filter — the page
// no longer keeps its own environment selection beside the filter state.
implicitDefaultConfig: DEFAULT_SIDEBAR_IMPLICIT_ENVIRONMENT_CONFIG,
isV4,
}),
[isV4, projectId, onExplicitFilterStateChange],
);
// Split core/presentation so the v4 facet scan can refine its counts against
// the filters already applied — the presentation half needs the options the
// scan produces, so it cannot also be the thing that supplies the filters.
const filterCore = useSidebarFilterStateCore(
usersFilterConfig,
filterStateOptions,
);
// v3 facet options: the trace facets this page inherits, from the traces
// endpoint that already answers them.
const traceFilterOptionsResponse = api.traces.filterOptions.useQuery(
{
projectId,
timestampFilter:
dateRangeFilter.length > 0
? (dateRangeFilter as TimeFilter[])
: undefined,
},
{
enabled: !isV4,
trpc: { context: { skipBatch: true } },
refetchOnMount: false,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
staleTime: Infinity,
},
);
const environmentFilterOptions =
api.projects.environmentFilterOptions.useQuery(
{
projectId,
fromTimestamp: dateRange?.from,
},
{
enabled: !isV4,
trpc: { context: { skipBatch: true } },
refetchOnMount: false,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
staleTime: Infinity,
},
);
const v3FacetOptions = useMemo<FacetOptions>(
() => ({
environment:
environmentFilterOptions.data?.map((value) => value.environment) ??
undefined,
traceName:
traceFilterOptionsResponse.data?.name?.map((n) => ({
value: n.value,
count: Number(n.count),
})) ?? undefined,
// tags don't have counts; they read A→Z
traceTags: sortOptionValues(
traceFilterOptionsResponse.data?.tags?.map((t) => t.value),
),
userId:
traceFilterOptionsResponse.data?.users?.map((u) => ({
value: u.value,
count: Number(u.count),
})) ?? undefined,
sessionId:
traceFilterOptionsResponse.data?.sessions?.map((s) => ({
value: s.value,
count: Number(s.count),
})) ?? undefined,
}),
[environmentFilterOptions.data, traceFilterOptionsResponse.data],
);
// v4 facet options: the events facet scan, lazily per column, refined by the
// filters already applied.
const facetStartTimeFilter = useMemo<TimeFilter[]>(
() =>
dateRange
? [
{
column: "startTime",
type: "datetime",
operator: ">=",
value: dateRange.from,
},
{
column: "startTime",
type: "datetime",
operator: "<=",
value: dateRange.to,
},
]
: [],
[dateRange],
);
const {
filterOptions: v4FacetOptions,
isFilterOptionsPending: isV4FacetOptionsPending,
erroredColumns,
loadingColumns,
requestColumns,
} = useEventsFilterOptions({
projectId,
startTimeFilter: facetStartTimeFilter,
refiningFilter: filterCore.filterState,
lazy: true,
enabled: isV4,
});
const isSidebarFilterLoading = isV4
? isV4FacetOptionsPending
: traceFilterOptionsResponse.isPending ||
environmentFilterOptions.isPending;
const queryFilter = useSidebarFilterPresentation(
filterCore,
usersFilterConfig,
isV4 ? v4FacetOptions : v3FacetOptions,
{
loading: isSidebarFilterLoading,
loadingColumns,
isV4,
},
);
// Lazy filter-options: load a facet's values when its sidebar section is
// expanded (also covers active filters, which auto-expand on mount).
const expandedFacets = queryFilter.expanded;
useEffect(() => {
requestColumns(expandedFacets);
}, [expandedFacets, requestColumns]);
const [searchQuery, setSearchQuery] = useQueryParam(
"search",
withDefault(StringParam, null),
);
const queryFilterRef = useRef(queryFilter);
queryFilterRef.current = queryFilter;
const setFiltersWrapper = useCallback(
(filters: FilterState) =>
queryFilterRef.current?.setFilterState(filters, { origin: "user" }),
[],
);
const observedOptions = toObservedOptions(
isV4 ? v4FacetOptions : v3FacetOptions,
isSidebarFilterLoading,
);
const filterState = queryFilter.effectiveFilterState.concat(dateRangeFilter);
const usersV3 = api.users.all.useQuery(
{
filter: filterState,
page: paginationState.pageIndex,
limit: paginationState.pageSize,
projectId,
searchQuery: searchQuery ?? undefined,
},
{ enabled: !isV4 },
);
const userMetricsV3 = api.users.metrics.useQuery(
{
projectId,
userIds: usersV3.data?.users.map((u) => u.userId) ?? [],
filter: filterState,
},
{
enabled: usersV3.isSuccess && !isV4,
trpc: {
context: {
skipBatch: true,
},
},
},
);
const usersV4 = api.users.allFromEvents.useQuery(
{
filter: filterState,
page: paginationState.pageIndex,
limit: paginationState.pageSize,
projectId,
searchQuery: searchQuery ?? undefined,
},
{ enabled: isV4 },
);
const userMetricsV4 = api.users.metricsFromEvents.useQuery(
{
projectId,
userIds: usersV4.data?.users.map((u) => u.userId) ?? [],
filter: filterState,
},
{
enabled: usersV4.isSuccess && isV4,
trpc: {
context: {
skipBatch: true,
},
},
},
);
// Select the active query based on beta state
const users = isV4 ? usersV4 : usersV3;
const userMetrics = isV4 ? userMetricsV4 : userMetricsV3;
type UserCoreOutput = RouterOutput["users"]["all"]["users"][number];
type UserMetricsOutput = RouterOutput["users"]["metrics"][number];
type CoreType = Omit<UserCoreOutput, "userId"> & {
id: string;
traceCount: UserCoreOutput["totalTraces"];
};
type MetricType = Omit<UserMetricsOutput, "userId"> & { id: string };
const userRowData = joinTableCoreAndMetrics<CoreType, MetricType>(
users.data?.users.map((u) => ({
...u,
id: u.userId,
traceCount: u.totalTraces,
})),
userMetrics.data?.map((u) => ({
...u,
id: u.userId,
})),
);
const totalCount = users.data?.totalUsers
? Number(users.data.totalUsers)
: null;
useEffect(() => {
if (users.isSuccess) {
setDetailPageList(
"users",
users.data.users.map((u) => ({ id: encodeURIComponent(u.userId) })),
);
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [users.isSuccess, users.data]);
const columns: LangfuseColumnDef<RowData>[] = [
createLinkTableColumn<RowData>({
accessorKey: "userId",
enableColumnFilter: true,
header: "User ID",
headerTooltip: {
description:
"The unique identifier for the user that was logged in Langfuse. See docs for more details on how to set this up.",
href: "https://langfuse.com/docs/observability/features/users",
},
size: 150,
getCell: (value) => {
if (typeof value !== "string") return undefined;
return {
type: "link",
props: {
path: `/project/${projectId}/users/${encodeURIComponent(value)}`,
value,
},
};
},
}),
createTagTableColumn<RowData>({
accessorKey: "environment",
header: "Environment",
size: 150,
enableHiding: true,
}),
createTextTableColumn<RowData>({
accessorKey: "firstEvent",
header: "First Event",
headerTooltip: {
description: "The earliest trace recorded for this user.",
},
size: 150,
mapValue: (value) =>
userMetrics.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
createTextTableColumn<RowData>({
accessorKey: "lastEvent",
header: "Last Event",
headerTooltip: {
description: "The latest trace recorded for this user.",
},
size: 150,
mapValue: (value) =>
userMetrics.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
createTextTableColumn<RowData>({
accessorKey: "totalTraces",
header: "Trace Count",
size: 120,
mapValue: (value) =>
users.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
createTextTableColumn<RowData>({
accessorKey: "totalEvents",
header: "Total Events",
headerTooltip: {
description:
"Total number of events for the user, includes traces and observations. See data model for more details.",
href: "https://langfuse.com/docs/observability/data-model",
},
size: 120,
mapValue: (value) =>
userMetrics.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
createTextTableColumn<RowData>({
accessorKey: "totalTokens",
header: "Total Tokens",
headerTooltip: {
description:
"Total number of tokens used for the user across all generations.",
href: "https://langfuse.com/docs/model-usage-and-cost",
},
size: 120,
mapValue: (value) =>
userMetrics.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
createTextTableColumn<RowData>({
accessorKey: "totalCost",
header: "Total Cost",
headerTooltip: {
description: "Total cost for the user across all generations.",
href: "https://langfuse.com/docs/model-usage-and-cost",
},
size: 120,
mapValue: (value) =>
userMetrics.isSuccess ? (value ?? undefined) : { type: "loading" },
}),
];
const [columnVisibility, setColumnVisibility] = useColumnVisibility(
"users",
columns,
);
// Its own key: "users" is the visibility state's, and one key cannot hold
// two shapes (an object and a string list) without them overwriting each
// other and being read back as the wrong type.
const [columnOrder, setColumnOrder] = useColumnOrder<RowData>(
"usersColumnOrder",
columns,
);
const { isLoading: isViewLoading, ...viewControllers } = useTableViewManager({
tableName: TableViewPresetTableName.Users,
projectId,
stateUpdaters: {
setFilters: (filters) =>
queryFilterRef.current.setFilterState(filters, {
origin: "saved_view",
}),
setExpandedFilters: queryFilter.onExpandedChange,
setSearchQuery,
setColumnOrder,
setColumnVisibility,
},
currentFilterState: queryFilter.explicitFilterState,
currentExpandedFilters: queryFilter.expanded,
validationContext: {
columns,
filterColumnDefinition: usersFilterConfig.columnDefinitions,
expandableFilterColumns: usersFilterConfig.facets.map(
(facet) => facet.column,
),
},
});
viewControllersRef.current = viewControllers;
const handleSearchChange = (query: string | null) => {
viewControllers.handleUserStateChange(searchQuery ?? "", query ?? "");
setSearchQuery(query);
setPaginationState({ pageIndex: 0 });
};
const handleColumnOrderChange: typeof setColumnOrder = (update) => {
const next = typeof update === "function" ? update(columnOrder) : update;
viewControllers.handleUserStateChange(columnOrder, next);
setColumnOrder(next);
};
const handleColumnVisibilityChange: typeof setColumnVisibility = (update) => {
const next =
typeof update === "function" ? update(columnVisibility) : update;
viewControllers.handleUserStateChange(columnVisibility, next);
setColumnVisibility(next);
};
return (
<DataTableControlsProvider tableName={usersFilterConfig.tableName}>
<div className="flex h-full w-full flex-col">
{showControlsInPageHeader && (
<TableHeaderControls
timeRange={timeRange}
setTimeRange={setTimeRange}
/>
)}
<StickySearchableTableFilterLayout
search={
<TableSearchBar
size={showControlsInPageHeader ? "large" : "default"}
key={`${viewControllers.filterEditorResetKey}-${queryFilter.draftResetKey}`}
isV4={isV4}
filterState={queryFilter.searchBarFilterState}
setFilterState={setFiltersWrapper}
search={{ query: searchQuery, setQuery: handleSearchChange }}
projectId={projectId}
tableName={usersFilterConfig.tableName}
observed={observedOptions}
erroredColumns={erroredColumns}
onRequestColumns={requestColumns}
registry={
isV4 ? USERS_FIELD_REGISTRY : LEGACY_USERS_FIELD_REGISTRY
}
/>
}
toolbar={
<DataTableToolbar
tableName={usersFilterConfig.tableName}
isV4={isV4}
rowClassName="my-1"
filterState={queryFilter.explicitFilterState}
columns={columns}
timeRange={showControlsInPageHeader ? undefined : timeRange}
setTimeRange={showControlsInPageHeader ? undefined : setTimeRange}
currentSearchQuery={searchQuery ?? ""}
columnVisibility={columnVisibility}
setColumnVisibility={handleColumnVisibilityChange}
columnOrder={columnOrder}
setColumnOrder={handleColumnOrderChange}
viewConfig={{
tableName: TableViewPresetTableName.Users,
projectId,
controllers: viewControllers,
}}
/>
}
>
<DataTableControls
key={viewControllers.filterEditorResetKey}
queryFilter={queryFilter}
/>
<div className="flex flex-1 flex-col overflow-hidden">
<DataTable
tableName="users"
columns={columns}
data={
users.isLoading || isViewLoading
? { isLoading: true, isError: false }
: users.isError
? {
isLoading: false,
isError: true,
error: users.error.message,
}
: {
isLoading: false,
isError: false,
data: userRowData.rows?.map((t) => {
return {
userId: t.id,
environment: t.environment ?? undefined,
totalTraces: compactNumberFormatter(
Number(t.traceCount),
),
firstEvent:
t.firstTrace?.toLocaleString() ?? "No event yet",
lastEvent:
t.lastTrace?.toLocaleString() ?? "No event yet",
totalEvents: compactNumberFormatter(
isV4
? Number(t.totalObservations ?? 0)
: Number(t.totalTraces ?? 0) +
Number(t.totalObservations ?? 0),
),
totalTokens: compactNumberFormatter(
t.totalTokens ?? 0,
),
totalCost: usdFormatter(
t.sumCalculatedTotalCost ?? 0,
2,
2,
),
};
}),
}
}
pagination={{
totalCount,
onChange: setPaginationState,
state: paginationState,
}}
columnVisibility={columnVisibility}
onColumnVisibilityChange={handleColumnVisibilityChange}
columnOrder={columnOrder}
onColumnOrderChange={handleColumnOrderChange}
cellPadding="comfortable"
/>
</div>
</StickySearchableTableFilterLayout>
</div>
</DataTableControlsProvider>
);
}