refactor(cli): rename "trace id" to "correlation id"

.changeset/alpha-release-notes.md

@@ -12,7 +12,7 @@ Introducing the Catalyst CLI (`@bigcommerce/catalyst`) — a command-line tool f
 - **Local preview** — `catalyst start` launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
 - **Live log tailing** — `catalyst logs tail` streams real-time application logs from your deployed storefront with color-coded log levels and multiple output formats.
 - **Smart credential resolution** — Configuration is resolved in priority order: CLI flags → `--env-file` → process environment variables → `.bigcommerce/project.json`.
-- **Telemetry** — Anonymous usage telemetry with session and trace IDs for support. Opt out anytime with `catalyst telemetry disable`.
+- **Telemetry** — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with `catalyst telemetry disable`.
 
 ### Commands
 

packages/catalyst/CHANGELOG.md

@@ -19,7 +19,7 @@
   - **Local preview** — `catalyst start` launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
   - **Live log tailing** — `catalyst logs tail` streams real-time application logs from your deployed storefront with color-coded log levels and multiple output formats.
   - **Smart credential resolution** — Configuration is resolved in priority order: CLI flags → `--env-file` → process environment variables → `.bigcommerce/project.json`.
-  - **Telemetry** — Anonymous usage telemetry with session and trace IDs for support. Opt out anytime with `catalyst telemetry disable`.
+  - **Telemetry** — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with `catalyst telemetry disable`.
 
   ### Commands
 

packages/catalyst/src/cli/commands/deploy.ts

@@ -118,7 +118,7 @@ export const generateUploadSignature = async (
         'X-Auth-Token': accessToken,
         'Content-Type': 'application/json',
         Accept: 'application/json',
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
       body: JSON.stringify({}),
     },
@@ -195,7 +195,7 @@ export const createDeployment = async (
         'X-Auth-Token': accessToken,
         'Content-Type': 'application/json',
         Accept: 'application/json',
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
       body: JSON.stringify({
         project_uuid: projectUuid,
@@ -235,7 +235,7 @@ export const getDeploymentStatus = async (
         'X-Auth-Token': accessToken,
         Accept: 'text/event-stream',
         Connection: 'keep-alive',
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
     },
   );
@@ -319,7 +319,7 @@ export const fetchProject = async (
         'X-Auth-Token': accessToken,
         'Content-Type': 'application/json',
         Accept: 'application/json',
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
     },
   );

packages/catalyst/src/cli/commands/project.spec.ts

@@ -35,7 +35,7 @@ beforeAll(async () => {
       identify: mockIdentify,
       isEnabled: vi.fn(() => true),
       track: vi.fn(),
-      sessionId: 'test-session-uuid',
+      correlationId: 'test-session-uuid',
       commandName: 'unknown',
       durationMs: vi.fn().mockReturnValue(0),
       analytics: {

packages/catalyst/src/cli/index.ts

@@ -25,11 +25,11 @@ const handleFatalError = async (error: unknown) => {
 
   if (telemetry.isEnabled()) {
     consola.info(
-      `\nTrace ID: ${telemetry.sessionId}\nShare this Trace ID with BigCommerce support.`,
+      `Correlation ID: ${telemetry.correlationId}\nShare this Correlation ID with BigCommerce support.`,
     );
   } else {
     consola.info(
-      '\nEnable telemetry (`catalyst telemetry enable`) for improved troubleshooting with BigCommerce support.',
+      'Enable telemetry (`catalyst telemetry enable`) for improved troubleshooting with BigCommerce support.',
     );
   }
 

packages/catalyst/src/cli/lib/project.ts

@@ -27,7 +27,7 @@ export async function fetchProjects(
       method: 'GET',
       headers: {
         'X-Auth-Token': accessToken,
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
     },
   );
@@ -79,7 +79,7 @@ export async function createProject(
         'X-Auth-Token': accessToken,
         Accept: 'application/json',
         'Content-Type': 'application/json',
-        'X-Correlation-Id': getTelemetry().sessionId,
+        'X-Correlation-Id': getTelemetry().correlationId,
       },
       body: JSON.stringify({ name }),
     },

packages/catalyst/src/cli/lib/telemetry.spec.ts

@@ -14,11 +14,11 @@ afterEach(() => {
 });
 
 describe('Telemetry', () => {
-  test('sessionId is a valid UUID', () => {
+  test('correlationId is a valid UUID', () => {
     const telemetry = new Telemetry();
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
-    expect(telemetry.sessionId).toMatch(uuidRegex);
+    expect(telemetry.correlationId).toMatch(uuidRegex);
   });
 
   test('commandName defaults to unknown', () => {
@@ -54,6 +54,6 @@ describe('getTelemetry', () => {
     const second = getTelemetry();
 
     expect(first).not.toBe(second);
-    expect(first.sessionId).not.toBe(second.sessionId);
+    expect(first.correlationId).not.toBe(second.correlationId);
   });
 });

packages/catalyst/src/cli/lib/telemetry.ts

@@ -10,7 +10,7 @@ const TELEMETRY_KEY_ENABLED = 'telemetry.enabled';
 const TELEMETRY_KEY_ID = `telemetry.anonymousId`;
 
 export class Telemetry {
-  readonly sessionId: string;
+  readonly correlationId: string;
   readonly analytics: Analytics;
   readonly startTime: number;
   commandName = 'unknown';
@@ -26,7 +26,7 @@ export class Telemetry {
 
     this.projectConfig = getProjectConfig();
 
-    this.sessionId = randomUUID();
+    this.correlationId = randomUUID();
     this.startTime = Date.now();
     this.analytics = new Analytics({
       writeKey: process.env.CLI_SEGMENT_WRITE_KEY ?? 'not-a-valid-segment-write-key',
@@ -47,7 +47,7 @@ export class Telemetry {
       anonymousId: this.getAnonymousId(),
       properties: {
         ...payload,
-        sessionId: this.sessionId,
+        correlationId: this.correlationId,
         nodeVersion: process.version,
         platform: process.platform,
         arch: process.arch,
@@ -114,7 +114,7 @@ export class Telemetry {
 let telemetryInstance: Telemetry | undefined;
 
 // Singleton so the pre-hook, post-hook, error handler, and command bodies all
-// share one sessionId for correlation. resetTelemetry() is for test isolation.
+// share one correlationId. resetTelemetry() is for test isolation.
 export function getTelemetry(): Telemetry {
   telemetryInstance ??= new Telemetry();
 

packages/catalyst/vitest.setup.ts

@@ -3,7 +3,7 @@ import { afterAll, afterEach, beforeAll, vi } from 'vitest';
 import { server } from './tests/mocks/node';
 
 const mockTelemetryInstance = {
-  sessionId: 'test-session-uuid',
+  correlationId: 'test-session-uuid',
   commandName: 'unknown',
   analytics: {
     track: vi.fn(),

packages/create-catalyst/src/utils/telemetry/telemetry.ts

@@ -18,7 +18,7 @@ interface Config {
 }
 
 export class Telemetry {
-  readonly sessionId: string;
+  readonly correlationId: string;
   readonly analytics: Analytics;
 
   private conf: Conf<Config> | null;
@@ -39,7 +39,7 @@ export class Telemetry {
       this.conf = null;
     }
 
-    this.sessionId = randomBytes(32).toString('hex');
+    this.correlationId = randomBytes(32).toString('hex');
     this.analytics = new Analytics({
       writeKey: process.env.CLI_SEGMENT_WRITE_KEY ?? 'not-a-valid-segment-write-key',
     });
@@ -55,7 +55,7 @@ export class Telemetry {
       anonymousId: this.getAnonymousId(),
       properties: {
         ...payload,
-        sessionId: this.sessionId,
+        correlationId: this.correlationId,
       },
       context: {
         app: {