fix(telemetry): attribute studio renders to the browser user (joinable funnel) (#1492)

Studio-triggered renders emit render_complete / render_error from the CLI
preview-server process, which stamps every event with the install's
anonymousId (client.ts drainQueueToPayload). The browser, meanwhile, fires
studio_session_start / studio_render_start under its own getAnonymousId(). So
the render outcome and the render start never share a person_id — verified in
data: of 15,125 users who started a studio render in 30d, ZERO have any
render_complete under any source, and the 898 studio-tagged completers are
disjoint server UUIDs. The studio render funnel — the product's core value
moment and strongest retention signal — is therefore unmeasurable.

Thread the browser's telemetry id through to the render-outcome events:

- client.ts: trackEvent takes an optional distinctId; drainQueueToPayload uses
  `event.distinctId ?? config.anonymousId`. CLI renders unchanged.
- events.ts: trackRenderComplete/trackRenderError forward an optional distinctId.
- studioRenderTelemetry.ts: emitStudioRender* pass opts.distinctId through.
- core studio-api (types.ts + routes/render.ts): the render route reads
  `telemetryDistinctId` from the request body (validated string) and passes it
  to the adapter's startRender, which already forwards opts to the emitters.
- studio (useRenderQueue.ts): include getAnonymousId() as telemetryDistinctId
  in the render POST — the same id studio_* events already use.

Result: studio render_complete/error now carry the browser user's id and join
studio_session_start / studio_render_start. Older clients that don't send the
field fall back to anonymousId (no regression). No new tracking surface — it's
the existing anonymous studio id.

Tests: per-event override forwarding (events), studio render distinctId
threading + older-client fallback (studioRenderTelemetry), and route body →
adapter forwarding incl. non-string rejection (core render route).

packages/cli/src/server/studioRenderTelemetry.test.ts

@@ -132,6 +132,16 @@ describe("studioRenderTelemetry", () => {
       expect(payload.gpu).toBe(false);
     });
 
+    it("forwards the browser user's distinctId so the render funnel is joinable", () => {
+      emitStudioRenderComplete({ ...opts, distinctId: "browser-user-123" }, 5000, fullPerf);
+      expect(trackRenderComplete.mock.calls[0]![0].distinctId).toBe("browser-user-123");
+    });
+
+    it("leaves distinctId undefined for older clients that don't send one", () => {
+      emitStudioRenderComplete(opts, 5000, fullPerf);
+      expect(trackRenderComplete.mock.calls[0]![0].distinctId).toBeUndefined();
+    });
+
     it("maps every RenderPerfSummary field to the expected payload key", () => {
       emitStudioRenderComplete(opts, 5000, fullPerf);
       const p = trackRenderComplete.mock.calls[0]![0];

packages/cli/src/server/studioRenderTelemetry.ts

@@ -20,6 +20,10 @@ import { bytesToMb } from "../telemetry/system.js";
 export interface StudioRenderOpts {
   fps: Fps;
   quality: string;
+  // Telemetry id of the browser user who triggered the render, so the render
+  // outcome joins their studio_session_start / studio_render_start events.
+  // Undefined for older studio clients → falls back to the install anonymousId.
+  distinctId?: string;
 }
 
 type RenderCompleteProps = Parameters<typeof trackRenderComplete>[0];
@@ -105,6 +109,7 @@ export function emitStudioRenderError(
     failedStage,
     errorMessage: err instanceof Error ? err.message : String(err),
     elapsedMs,
+    distinctId: opts.distinctId,
     ...renderJobObservabilityTelemetryPayload(job),
     ...memSnapshot(),
   });
@@ -122,6 +127,7 @@ export function emitStudioRenderComplete(
     docker: false,
     gpu: false,
     source: "studio",
+    distinctId: opts.distinctId,
     ...perfPayload(perf, elapsedMs),
     ...memSnapshot(),
   });

packages/cli/src/telemetry/client.ts

@@ -24,6 +24,10 @@ let eventQueue: Array<{
   event: string;
   properties: EventProperties;
   timestamp: string;
+  // Override for the batch distinct_id. Defaults to the install's anonymousId.
+  // Used to attribute server-side studio renders to the browser user who
+  // triggered them, so the render funnel is joinable across processes.
+  distinctId?: string;
 }> = [];
 
 let telemetryEnabled: boolean | null = null;
@@ -59,12 +63,17 @@ export function shouldTrack(): boolean {
 /**
  * Queue a telemetry event. Non-blocking, fail-silent.
  */
-export function trackEvent(event: string, properties: EventProperties = {}): void {
+export function trackEvent(
+  event: string,
+  properties: EventProperties = {},
+  distinctId?: string,
+): void {
   if (!shouldTrack()) return;
 
   const sys = getSystemMeta();
   eventQueue.push({
     event,
+    distinctId,
     properties: {
       ...properties,
       cli_version: VERSION,
@@ -102,7 +111,7 @@ function drainQueueToPayload(): string | null {
   const batch = eventQueue.map((e) => ({
     event: e.event,
     properties: { ...e.properties, $ip: null },
-    distinct_id: config.anonymousId,
+    distinct_id: e.distinctId ?? config.anonymousId,
     timestamp: e.timestamp,
   }));
   eventQueue = [];

packages/cli/src/telemetry/events.test.ts

@@ -29,6 +29,23 @@ describe("render telemetry events", () => {
         error_message: "ENOENT: open '[path]' https://example.com/video.mp4?…",
         observability_composition_hash: "abc123",
       }),
+      undefined,
+    );
+  });
+
+  it("forwards distinctId to trackEvent so studio renders attribute to the browser user", () => {
+    trackRenderError({
+      fps: 30,
+      quality: "standard",
+      docker: false,
+      source: "studio",
+      distinctId: "browser-user-123",
+    });
+
+    expect(trackEvent).toHaveBeenCalledWith(
+      "render_error",
+      expect.objectContaining({ source: "studio" }),
+      "browser-user-123",
     );
   });
 

packages/cli/src/telemetry/events.ts

@@ -135,44 +135,51 @@ export function trackRenderComplete(
     extractPhase3Ms?: number;
     extractCacheHits?: number;
     extractCacheMisses?: number;
+    // Attribute this event to a specific user (e.g. the browser user who
+    // triggered a studio render); defaults to the install anonymousId.
+    distinctId?: string;
   } & RenderObservabilityTelemetryPayload,
 ): void {
-  trackEvent("render_complete", {
-    duration_ms: props.durationMs,
-    fps: props.fps,
-    quality: props.quality,
-    workers: props.workers,
-    docker: props.docker,
-    gpu: props.gpu,
-    source: props.source ?? "cli",
-    composition_duration_ms: props.compositionDurationMs,
-    composition_width: props.compositionWidth,
-    composition_height: props.compositionHeight,
-    total_frames: props.totalFrames,
-    speed_ratio: props.speedRatio,
-    capture_avg_ms: props.captureAvgMs,
-    capture_peak_ms: props.capturePeakMs,
-    peak_memory_mb: props.peakMemoryMb,
-    memory_free_mb: props.memoryFreeMb,
-    tmp_peak_bytes: props.tmpPeakBytes,
-    stage_compile_ms: props.stageCompileMs,
-    stage_video_extract_ms: props.stageVideoExtractMs,
-    stage_audio_process_ms: props.stageAudioProcessMs,
-    stage_capture_ms: props.stageCaptureMs,
-    stage_encode_ms: props.stageEncodeMs,
-    stage_assemble_ms: props.stageAssembleMs,
-    extract_resolve_ms: props.extractResolveMs,
-    extract_hdr_probe_ms: props.extractHdrProbeMs,
-    extract_hdr_preflight_ms: props.extractHdrPreflightMs,
-    extract_hdr_preflight_count: props.extractHdrPreflightCount,
-    extract_vfr_probe_ms: props.extractVfrProbeMs,
-    extract_vfr_preflight_ms: props.extractVfrPreflightMs,
-    extract_vfr_preflight_count: props.extractVfrPreflightCount,
-    extract_phase3_ms: props.extractPhase3Ms,
-    extract_cache_hits: props.extractCacheHits,
-    extract_cache_misses: props.extractCacheMisses,
-    ...renderObservabilityEventProperties(props),
-  });
+  trackEvent(
+    "render_complete",
+    {
+      duration_ms: props.durationMs,
+      fps: props.fps,
+      quality: props.quality,
+      workers: props.workers,
+      docker: props.docker,
+      gpu: props.gpu,
+      source: props.source ?? "cli",
+      composition_duration_ms: props.compositionDurationMs,
+      composition_width: props.compositionWidth,
+      composition_height: props.compositionHeight,
+      total_frames: props.totalFrames,
+      speed_ratio: props.speedRatio,
+      capture_avg_ms: props.captureAvgMs,
+      capture_peak_ms: props.capturePeakMs,
+      peak_memory_mb: props.peakMemoryMb,
+      memory_free_mb: props.memoryFreeMb,
+      tmp_peak_bytes: props.tmpPeakBytes,
+      stage_compile_ms: props.stageCompileMs,
+      stage_video_extract_ms: props.stageVideoExtractMs,
+      stage_audio_process_ms: props.stageAudioProcessMs,
+      stage_capture_ms: props.stageCaptureMs,
+      stage_encode_ms: props.stageEncodeMs,
+      stage_assemble_ms: props.stageAssembleMs,
+      extract_resolve_ms: props.extractResolveMs,
+      extract_hdr_probe_ms: props.extractHdrProbeMs,
+      extract_hdr_preflight_ms: props.extractHdrPreflightMs,
+      extract_hdr_preflight_count: props.extractHdrPreflightCount,
+      extract_vfr_probe_ms: props.extractVfrProbeMs,
+      extract_vfr_preflight_ms: props.extractVfrPreflightMs,
+      extract_vfr_preflight_count: props.extractVfrPreflightCount,
+      extract_phase3_ms: props.extractPhase3Ms,
+      extract_cache_hits: props.extractCacheHits,
+      extract_cache_misses: props.extractCacheMisses,
+      ...renderObservabilityEventProperties(props),
+    },
+    props.distinctId,
+  );
 }
 
 export function trackRenderError(
@@ -188,22 +195,29 @@ export function trackRenderError(
     elapsedMs?: number;
     peakMemoryMb?: number;
     memoryFreeMb?: number;
+    // Attribute this event to a specific user (e.g. the browser user who
+    // triggered a studio render); defaults to the install anonymousId.
+    distinctId?: string;
   } & RenderObservabilityTelemetryPayload,
 ): void {
-  trackEvent("render_error", {
-    fps: props.fps,
-    quality: props.quality,
-    docker: props.docker,
-    workers: props.workers,
-    gpu: props.gpu,
-    source: props.source ?? "cli",
-    failed_stage: props.failedStage,
-    error_message: props.errorMessage ? redactTelemetryMessage(props.errorMessage) : undefined,
-    elapsed_ms: props.elapsedMs,
-    peak_memory_mb: props.peakMemoryMb,
-    memory_free_mb: props.memoryFreeMb,
-    ...renderObservabilityEventProperties(props),
-  });
+  trackEvent(
+    "render_error",
+    {
+      fps: props.fps,
+      quality: props.quality,
+      docker: props.docker,
+      workers: props.workers,
+      gpu: props.gpu,
+      source: props.source ?? "cli",
+      failed_stage: props.failedStage,
+      error_message: props.errorMessage ? redactTelemetryMessage(props.errorMessage) : undefined,
+      elapsed_ms: props.elapsedMs,
+      peak_memory_mb: props.peakMemoryMb,
+      memory_free_mb: props.memoryFreeMb,
+      ...renderObservabilityEventProperties(props),
+    },
+    props.distinctId,
+  );
 }
 
 export function trackRenderObservation(props: {