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).
Addresses review comments on #982:
- studio shouldTrack(): adds VITE_HYPERFRAMES_NO_TELEMETRY (mirrors CLI's
HYPERFRAMES_NO_TELEMETRY) and import.meta.env.DEV gates so dev / CI
studio builds don't pollute production telemetry. shouldTrack() is now
exported for testability.
- App.tsx session dedupe: moves the once-per-session check from a useRef
(which resets on HMR / remount) to sessionStorage via new
hasFiredSessionStart / markSessionStartFired helpers in config.ts.
- studioRenderTelemetry.ts: documents why `workers` is intentionally
omitted from emitStudioRenderError (studio renders don't accept a
user-supplied worker count, so early failures genuinely don't know one).
- client.ts flush(): documents fire-and-forget no-retry design so future
hands don't accidentally add retry logic that double-counts.
Tests:
- studioRenderTelemetry.test.ts (8 tests): perfPayload mapping for every
RenderPerfSummary field, undefined-perf path, missing-extract path,
zero-elapsed edge case, error event shape.
- studio/telemetry/events.test.ts (4 tests): pin event names
(studio_session_start, studio_render_start) and payload shape.
- studio/telemetry/client.test.ts (9 tests): shouldTrack() returns false
for non-phc_ key, opt-out, doNotTrack, build-time env, vite dev mode;
memoization.
Moves StudioRenderOpts, memSnapshot, perfPayload, stagesPayload,
extractPayload, emitStudioRenderComplete, emitStudioRenderError to
packages/cli/src/server/studioRenderTelemetry.ts. studioServer.ts now
has a single-line import diff.
Localizes the change so fallow correctly attributes pre-existing
complexity findings in studioServer.ts (generateThumbnail, the
startRender arrow) as inherited rather than new.
Miguel Ángel