feat(analytics): add run_id to every event and $session_id after login (#661)

Author: gewenyu99

src/utils/__tests__/analytics.test.ts

@@ -7,6 +7,21 @@ import type { ApiUser } from '@lib/api';
 jest.mock('posthog-node');
 jest.mock('uuid');
 
+// IS_PRODUCTION_BUILD is read live (property access) in the Analytics
+// constructor, so a getter backed by this mutable flag lets a test flip the
+// build type without re-importing the module. Defaults falsy → 'dev',
+// matching every other test. `var` (not `let`) so the hoisted jest.mock
+// factory can read it at import time without hitting the temporal dead zone;
+// the `mock` prefix satisfies jest's hoisting rule.
+// eslint-disable-next-line no-var
+var mockIsProductionBuild = false;
+jest.mock('@env', () => ({
+  ...jest.requireActual('@env'),
+  get IS_PRODUCTION_BUILD() {
+    return mockIsProductionBuild;
+  },
+}));
+
 const mockUuidv4 = uuidv4 as jest.MockedFunction<typeof uuidv4>;
 const MockedPostHog = PostHog as jest.MockedClass<typeof PostHog>;
 
@@ -16,7 +31,18 @@ describe('Analytics', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    mockUuidv4.mockReturnValue('test-uuid' as any);
+    mockIsProductionBuild = false;
+    // Each run mints several distinct uuids; mock them to different values
+    // so the tests reflect reality (run_id !== $session_id) rather than
+    // collapsing them. Call order: anonymousId, runId (both in the
+    // constructor), then sessionId (lazily, on first identify).
+    let uuidCall = 0;
+    mockUuidv4.mockImplementation((() => {
+      uuidCall += 1;
+      if (uuidCall === 1) return 'test-uuid'; // anonymousId
+      if (uuidCall === 2) return 'run-uuid'; // runId
+      return 'session-uuid'; // sessionId (first identify)
+    }) as any);
 
     mockPostHogInstance = {
       capture: jest.fn(),
@@ -45,6 +71,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
           ...properties,
         },
       );
@@ -64,6 +91,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
           testTag: 'testValue',
           ...properties,
         },
@@ -84,6 +112,8 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
+          $session_id: 'session-uuid',
         },
       );
     });
@@ -100,6 +130,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
         },
       );
     });
@@ -119,6 +150,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
           environment: 'test',
           version: '1.0.0',
           integration: 'nextjs',
@@ -141,6 +173,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
           integration: 'react',
         },
       );
@@ -158,11 +191,37 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
         },
       );
     });
   });
 
+  describe('build tag', () => {
+    it("tags dev/test runs as 'dev'", () => {
+      analytics.captureException(new Error('e'));
+
+      expect(
+        (mockPostHogInstance.captureException as jest.Mock).mock.calls.at(
+          -1,
+        )?.[2],
+      ).toMatchObject({ build: 'dev' });
+    });
+
+    it("tags production builds as 'prod'", () => {
+      mockIsProductionBuild = true;
+      const prodAnalytics = new Analytics();
+
+      prodAnalytics.captureException(new Error('e'));
+
+      expect(
+        (mockPostHogInstance.captureException as jest.Mock).mock.calls.at(
+          -1,
+        )?.[2],
+      ).toMatchObject({ build: 'prod' });
+    });
+  });
+
   describe('identifyUser', () => {
     const user = {
       distinct_id: 'user-123',
@@ -209,6 +268,24 @@ describe('Analytics', () => {
       expect(mockPostHogInstance.alias).not.toHaveBeenCalled();
     });
 
+    it('opens the session ($session_id) only once the user is identified', () => {
+      const error = new Error('e');
+
+      // Pre-login: run_id is present, $session_id is not.
+      analytics.captureException(error);
+      const beforeLogin = (mockPostHogInstance.captureException as jest.Mock)
+        .mock.calls[0][2];
+      expect(beforeLogin).toMatchObject({ run_id: 'run-uuid' });
+      expect(beforeLogin).not.toHaveProperty('$session_id');
+
+      // Post-login: both ids ride along.
+      analytics.identifyUser({ distinct_id: 'user-123' } as unknown as ApiUser);
+      analytics.captureException(error);
+      expect(
+        (mockPostHogInstance.captureException as jest.Mock).mock.calls[1][2],
+      ).toMatchObject({ run_id: 'run-uuid', $session_id: 'session-uuid' });
+    });
+
     it('omits person properties the user does not have', () => {
       analytics.identifyUser({
         distinct_id: 'user-123',
@@ -249,6 +326,7 @@ describe('Analytics', () => {
       expect(result?.properties).toEqual({
         $app_name: 'wizard',
         build: 'dev',
+        run_id: 'run-uuid',
         command: 'slack',
         $exception_list: [{ type: 'Error' }],
       });
@@ -411,6 +489,7 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
           integration: 'nextjs',
           localMcp: true,
           debug: false,
@@ -435,6 +514,8 @@ describe('Analytics', () => {
           team: ANALYTICS_TEAM_TAG,
           $app_name: 'wizard',
           build: 'dev',
+          run_id: 'run-uuid',
+          $session_id: 'session-uuid',
           integration: 'svelte',
         },
       );

src/utils/analytics.ts

@@ -53,6 +53,8 @@ export class Analytics {
     {};
   private distinctId?: string;
   private anonymousId: string;
+  private runId: string;
+  private sessionId: string | null = null;
   private appName = 'wizard';
   private activeFlags: Record<string, string> | null = null;
   private groups: Record<string, string> = {};
@@ -83,14 +85,24 @@ export class Analytics {
     });
 
     this.tags = { $app_name: this.appName };
-    // Non-production builds tag every event so they segment out of prod
-    // data. CI runs upgrade the tag to 'ci' (see runWizardCI).
-    if (!IS_PRODUCTION_BUILD) {
-      this.tags.build = 'dev';
-    }
+    // Tag every run with its build type so prod / dev / ci segment cleanly
+    // in analytics. tsdown inlines IS_PRODUCTION_BUILD to `true` in published
+    // builds and `false` for dev/tsx/test runs. CI runs (always non-prod
+    // builds) upgrade this to 'ci' in runWizardCI.
+    this.tags.build = IS_PRODUCTION_BUILD ? 'prod' : 'dev';
 
     this.anonymousId = uuidv4();
 
+    // One id per process = one id per wizard run, registered in the tag bag
+    // so it rides on every capture, exception, and autocaptured exception
+    // (all of which merge `this.tags`). Lets you separate two runs by the
+    // same logged-in user, who otherwise share one distinct id. Distinct
+    // from `anonymousId`, the pre-login *person* id that gets aliased onto
+    // the real user at login. `$session_id` is intentionally not set here —
+    // it stays null until OAuth completes (see identifyUser).
+    this.runId = uuidv4();
+    this.tags.run_id = this.runId;
+
     this.distinctId = undefined;
   }
 
@@ -106,6 +118,15 @@ export class Analytics {
       return;
     }
     this.distinctId = distinctId;
+    // Open the analytics session on first login. Null until here, so
+    // pre-OAuth events carry only `run_id`; from now on every event also
+    // carries `$session_id` and PostHog groups the authenticated run into a
+    // native Session. Stored in the tag bag so it rides on every subsequent
+    // capture and exception.
+    if (!this.sessionId) {
+      this.sessionId = uuidv4();
+      this.tags.$session_id = this.sessionId;
+    }
     this.client.identify({
       distinctId,
       properties: {
@@ -214,6 +235,10 @@ export class Analytics {
       distinctId: this.distinctId ?? this.anonymousId,
       event: 'setup wizard finished',
       properties: {
+        // Hoisted out of `tags` so the run's terminal event is filterable by
+        // run, and joins the session when one was opened (post-OAuth runs).
+        run_id: this.runId,
+        ...(this.sessionId ? { $session_id: this.sessionId } : {}),
         status,
         tags: this.tags,
       },