feat(analytics): show user names in usage charts (#269)

* docs: design usage analytics user labels

* feat: support formatted insight group labels

* feat: show names in usage analytics user charts

* fix: keep usage analytics series keys stable

Author: moonrailgun

docs/superpowers/specs/2026-07-14-usage-analytics-user-labels-design.md

@@ -0,0 +1,66 @@
+# Usage Analytics User Labels Design
+
+## Goal
+
+Display users in all three AI Gateway Usage Analytics user charts as
+`name (userId)` instead of showing only the raw user ID.
+
+## Name Resolution
+
+The client will load the current workspace members and resolve each chart
+group's `userId` with this priority:
+
+1. The member's non-empty `nickname`.
+2. The member's `username`.
+3. The original `userId` when the member cannot be resolved.
+
+Resolved users are rendered as `name (userId)`. The fallback remains the raw
+ID without additional punctuation so historical data for removed users stays
+readable.
+
+## Architecture and Data Flow
+
+The existing insights query continues to group AI Gateway logs by `userId`.
+`AIGatewayAnalytics` uses the existing `workspace.members` query to build a
+user-ID-to-display-label map and passes a stable formatter to each of the three
+user charts.
+
+`InsightQueryChart` forwards an optional group-value formatter to
+`useInsightsData`. Chart data keeps its raw, stable series keys, while the
+formatter changes only the corresponding chart configuration labels. It does
+not change the query, grouping, metric values, or raw response.
+
+The formatter is optional, so every existing chart without it preserves its
+current behavior.
+
+## Scope
+
+The formatter is applied to:
+
+- Request Count by User
+- Cost by User
+- Token Usage by User
+
+No locale JSON files, AI Gateway log records, insights SQL, or unrelated chart
+labels are changed.
+
+## Error and Loading Behavior
+
+Charts may render before workspace-member data is available. Until resolution
+is possible, labels fall back to raw IDs. Once member data arrives, memoized
+chart processing reruns and replaces known IDs with resolved labels.
+
+An unknown or removed user never produces an empty label.
+
+## Testing
+
+Focused unit tests for insights data processing will verify:
+
+- a supplied formatter changes grouped series labels;
+- formatted labels do not change the underlying series keys;
+- grouped data values remain unchanged;
+- processing without a formatter remains backward compatible;
+- an unresolved ID stays visible through the formatter's fallback.
+
+Type checking and the production build will provide integration-level
+verification after the focused tests pass.

src/client/components/aiGateway/AIGatewayAnalytics.tsx

@@ -19,6 +19,7 @@ import { LoadingView } from '../LoadingView';
 import { DateUnit, getDateArray } from '@tianji/shared';
 import type { InsightsRawData } from '@/hooks/useInsightsData';
 import type { ChartConfig } from '../ui/chart';
+import { createAIGatewayUserLabelFormatter } from './AIGatewayUserLabel';
 
 // Status color tokens used in the Errors tab.
 // Keep the success/failure colors aligned with the rest of the app
@@ -38,6 +39,13 @@ export const AIGatewayAnalytics: React.FC<AIGatewayAnalyticsProps> = React.memo(
     const { gatewayId } = props;
     const workspaceId = useCurrentWorkspaceId();
     const { startDate, endDate, unit, refresh } = useGlobalRangeDate();
+    const { data: workspaceMembers = [] } = trpc.workspace.members.useQuery({
+      workspaceId,
+    });
+    const userLabelFormatter = useMemo(
+      () => createAIGatewayUserLabelFormatter(workspaceMembers),
+      [workspaceMembers]
+    );
 
     const trpcUtils = trpc.useUtils();
     const handleRefresh = useEvent(async () => {
@@ -473,6 +481,7 @@ export const AIGatewayAnalytics: React.FC<AIGatewayAnalyticsProps> = React.memo(
                     time={timeConfig}
                     chartType="bar"
                     valueProcessor={defaultValueProcessor.alwaysPositive}
+                    groupValueFormatter={userLabelFormatter}
                   />
                 </CardContent>
               </Card>
@@ -498,6 +507,7 @@ export const AIGatewayAnalytics: React.FC<AIGatewayAnalyticsProps> = React.memo(
                     time={timeConfig}
                     chartType="bar"
                     valueProcessor={defaultValueProcessor.alwaysPositive}
+                    groupValueFormatter={userLabelFormatter}
                   />
                 </CardContent>
               </Card>
@@ -537,6 +547,7 @@ export const AIGatewayAnalytics: React.FC<AIGatewayAnalyticsProps> = React.memo(
                   time={timeConfig}
                   chartType="bar"
                   valueProcessor={defaultValueProcessor.alwaysPositive}
+                  groupValueFormatter={userLabelFormatter}
                 />
               </CardContent>
             </Card>

src/client/components/aiGateway/AIGatewayUserLabel.spec.tsx

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { createAIGatewayUserLabelFormatter } from './AIGatewayUserLabel';
+
+describe('createAIGatewayUserLabelFormatter', () => {
+  it('prefers a non-empty nickname', () => {
+    const format = createAIGatewayUserLabelFormatter([
+      { userId: 'user-1', user: { nickname: 'Ada', username: 'ada' } },
+    ]);
+
+    expect(format('user-1')).toBe('Ada (user-1)');
+  });
+
+  it('falls back to username when nickname is blank', () => {
+    const format = createAIGatewayUserLabelFormatter([
+      { userId: 'user-2', user: { nickname: '   ', username: 'grace' } },
+    ]);
+
+    expect(format('user-2')).toBe('grace (user-2)');
+  });
+
+  it('keeps the raw ID for an unknown user', () => {
+    const format = createAIGatewayUserLabelFormatter([]);
+
+    expect(format('removed-user')).toBe('removed-user');
+  });
+
+  it('keeps the raw ID when both nickname and username are blank', () => {
+    const format = createAIGatewayUserLabelFormatter([
+      { userId: 'user-3', user: { nickname: null, username: '   ' } },
+    ]);
+
+    expect(format('user-3')).toBe('user-3');
+  });
+});

src/client/components/aiGateway/AIGatewayUserLabel.ts

@@ -0,0 +1,25 @@
+interface WorkspaceMemberForLabel {
+  userId: string;
+  user: {
+    nickname: string | null;
+    username: string;
+  };
+}
+
+export function createAIGatewayUserLabelFormatter(
+  members: WorkspaceMemberForLabel[]
+) {
+  const labels = new Map(
+    members.map((member) => {
+      const name =
+        member.user.nickname?.trim() || member.user.username.trim() || null;
+
+      return [
+        member.userId,
+        name ? `${name} (${member.userId})` : member.userId,
+      ] as const;
+    })
+  );
+
+  return (userId: string) => labels.get(userId) ?? userId;
+}

src/client/components/insights/InsightQueryChart.tsx

@@ -10,7 +10,11 @@ import { InsightType } from '@/store/insights';
 import { DateUnit, FilterInfo, GroupInfo, MetricsInfo } from '@tianji/shared';
 import { getUserTimezone } from '@/api/model/user';
 import { ChartConfig } from '../ui/chart';
-import { InsightsRawData, useInsightsData } from '@/hooks/useInsightsData';
+import {
+  GroupValueFormatter,
+  InsightsRawData,
+  useInsightsData,
+} from '@/hooks/useInsightsData';
 
 interface InsightQueryChartProps {
   className?: string;
@@ -33,6 +37,7 @@ interface InsightQueryChartProps {
   chartConfig?: ChartConfig;
 
   valueProcessor?: (value: number) => number;
+  groupValueFormatter?: GroupValueFormatter;
 }
 export const InsightQueryChart: React.FC<InsightQueryChartProps> = React.memo(
   (props) => {
@@ -49,6 +54,7 @@ export const InsightQueryChart: React.FC<InsightQueryChartProps> = React.memo(
       chartType,
       chartConfig,
       valueProcessor,
+      groupValueFormatter,
     } = props;
 
     const { data: rawData = [], isLoading } = trpc.insights.query.useQuery(
@@ -83,6 +89,7 @@ export const InsightQueryChart: React.FC<InsightQueryChartProps> = React.memo(
       groups,
       time,
       valueProcessor,
+      groupValueFormatter,
     });
 
     // Use simple data for backward compatibility when it's a single series

src/client/components/insights/useInsightsData.spec.tsx

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { processInsightsData } from '@/hooks/useInsightsData';
+
+const options = {
+  data: [
+    {
+      name: '$all_event',
+      userId: 'user-1',
+      data: [{ date: '2026-07-14', value: 3 }],
+    },
+  ],
+  groups: [{ value: 'userId' }],
+  time: {
+    startAt: new Date('2026-07-14T00:00:00Z').valueOf(),
+    endAt: new Date('2026-07-14T23:59:59Z').valueOf(),
+    unit: 'day' as const,
+  },
+};
+
+describe('processInsightsData group labels', () => {
+  it('formats grouped series labels without changing stable data keys', () => {
+    const result = processInsightsData({
+      ...options,
+      groupValueFormatter: (value) => `Ada (${value})`,
+    });
+
+    expect(result.chartData).toEqual([
+      { date: '2026-07-14', '$all_event-user-1': 3 },
+    ]);
+    expect(result.chartConfig['$all_event-user-1']?.label).toBe(
+      '$all_event-Ada (user-1)'
+    );
+  });
+
+  it('keeps existing grouped series labels without a formatter', () => {
+    const result = processInsightsData(options);
+
+    expect(result.chartData).toEqual([
+      { date: '2026-07-14', '$all_event-user-1': 3 },
+    ]);
+  });
+});

src/client/hooks/useInsightsData.ts

@@ -12,15 +12,20 @@ import { ChartConfig } from '@/components/ui/chart';
  */
 function generateSeriesName(
   item: InsightsRawData,
-  groups: Pick<GroupInfo, 'value'>[]
+  groups: Pick<GroupInfo, 'value'>[],
+  groupValueFormatter?: GroupValueFormatter
 ): string {
   // Use alias if available, otherwise use name
   let name = item.alias ?? item.name;
 
   if (groups.length > 0) {
     const groupSuffixes = groups
       .map((group) => {
-        return get(item, group.value);
+        const value = get(item, group.value);
+
+        return value && groupValueFormatter
+          ? groupValueFormatter(String(value), group)
+          : value;
       })
       .filter(Boolean) // Remove null/undefined values
       .join('-');
@@ -48,6 +53,11 @@ export interface ProcessedChartData {
   [key: string]: string | number;
 }
 
+export type GroupValueFormatter = (
+  value: string,
+  group: Pick<GroupInfo, 'value'>
+) => string;
+
 export interface UseInsightsDataOptions {
   data: InsightsRawData[];
   groups: Pick<GroupInfo, 'value'>[];
@@ -57,6 +67,7 @@ export interface UseInsightsDataOptions {
     unit: DateUnit;
   };
   valueProcessor?: (value: number) => number;
+  groupValueFormatter?: GroupValueFormatter;
 }
 
 /**
@@ -73,7 +84,7 @@ export function processInsightsData(options: UseInsightsDataOptions): {
   isMultiSeries: boolean;
   seriesCount: number;
 } {
-  const { data, groups, time, valueProcessor } = options;
+  const { data, groups, time, valueProcessor, groupValueFormatter } = options;
 
   if (!data || data.length === 0) {
     return {
@@ -117,6 +128,7 @@ export function processInsightsData(options: UseInsightsDataOptions): {
 
   // For complex case (groups or multiple metrics), process full chart data
   const res: { date: string }[] = [];
+  const seriesLabels = new Map<string, string>();
 
   // Collect all unique dates from all data series
   const allDates = new Set<string>();
@@ -131,6 +143,9 @@ export function processInsightsData(options: UseInsightsDataOptions): {
       const value = dataPoint?.value ?? 0;
       const processedValue = valueProcessor?.(value) ?? value;
       const name = generateSeriesName(item, groups);
+      const label = generateSeriesName(item, groups, groupValueFormatter);
+
+      seriesLabels.set(name, label);
 
       res.push({
         date,
@@ -151,7 +166,7 @@ export function processInsightsData(options: UseInsightsDataOptions): {
           return {
             ...prev,
             [curr]: {
-              label: curr,
+              label: seriesLabels.get(curr) ?? curr,
               color: pickColorWithNum(i),
             },
           };
@@ -193,6 +208,7 @@ export function useInsightsData(options: UseInsightsDataOptions) {
       options.time.endAt,
       options.time.unit,
       options.valueProcessor,
+      options.groupValueFormatter,
     ]
   );
 }