Skip to content

Open source CapCut alternative.

TypeScript
10.6 KB
Raw Blame
"use client";

/**
 * A durable record of the frames the main thread was blocked in.
 *
 * The meter in perfTrace boils a half minute down to one summary, which is
 * the shape a chart wants and the wrong shape for a bug report: "the delete
 * at 10:19 took 1.7 seconds inside X" is one frame, and it is gone from the
 * summary the moment a longer one lands. This keeps the frames themselves —
 * the last few hundred, in fixed memory — and gets them to PostHog when the
 * machine has nothing better to do.
 *
 * Nothing here runs on the hot path. A frame is an object pushed onto an
 * array. The array reaches localStorage at idle, at most once every ten
 * seconds and only when something was added, so a tab that crashes still
 * leaves its log behind.
 *
 * Every machine records. Few send: with ten thousand accounts, a log from
 * each would be a flood of pages that were fine. A session sends when it has
 * seen trouble — a frame over a second, a half minute mostly blocked, a play
 * that hitched or whose sound ran late — so the frames that led up to it
 * arrive with it, and a small random share of sessions send regardless,
 * which is the baseline the trouble is measured against.
 * Batches go out at idle, on the page hiding (the analytics client beacons
 * what it holds), and on the next open for whatever the last page never got
 * to send — a session that crashed reads as trouble on the page after it.
 *
 * Every record is timings, a script's name in the page's own bundle, and
 * which control was pressed — see perfTrace's meter for what is kept out.
 */

import { heapBytes, mb, memoryCeiling, memoryTotalCached, memoryUsage } from "./memoryBudget";

export interface PerfLogRecord {
  /** Monotonic across page loads on this machine, so a batch sent twice —
   * once by a beacon that did land, once by the next open that could not
   * know — reads as one. */
  id: number;
  /** Epoch milliseconds the frame started, and when the page it happened on
   * was opened, so frames group by page load after the fact. */
  at: number;
  open: number;
  ms: number;
  blockedMs: number;
  scriptMs: number;
  layoutMs: number;
  invoker: string;
  fn: string;
  src: string;
  char: number;
  activity: string;
  input: string;
  inputAgoMs: number;
  /** What the editor was holding when the frame blocked, modeled in megabytes.
   * A machine short of memory stalls for a page fault, which looks from here
   * exactly like a machine short of processor — this is what tells them
   * apart. Absent on records a build before this one wrote and left in
   * storage. */
  memMb?: number;
}

export interface PerfLogBatch {
  /** Which batch of the drain this is, out of how many, and why this session
   * is sending at all. */
  batch: number;
  of: number;
  reason: PerfUploadReason;
  records: PerfLogRecord[];
  cores: number;
  memoryGb: number;
  /** What the editor is holding as this sends, what it is allowed to hold on
   * this machine, and what the JavaScript heap says — see `memoryBudget`. */
  memMb: number;
  memCeilingMb: number;
  heapMb: number;
}

/** Why a session uploads: it drew the sample, or it saw trouble. */
export type PerfUploadReason = "sampled" | "trouble";

const KEY = "cut-perf-log";
const VERSION = 1;
/** Frames kept. At ~150 bytes each this is a write of tens of kilobytes,
 * which is what the machines this runs on can afford to spend on being
 * measured. */
const CAP = 250;
/** Frames older than this are dropped at open: a stall last week is not the
 * context for a stall today. */
const KEEP_MS = 24 * 60 * 60_000;
/** Records per batch sent. */
const BATCH = 40;
/** Storage writes and in-session drains wait at least this long apart. A
 * struggling machine produces long frames without pause, so this is the
 * cadence of the write, and the page hiding flushes whatever it holds. */
const WRITE_MIN_MS = 30_000;
const DRAIN_MIN_MS = 5 * 60_000;
/** A drain right after open waits this long, so the open itself is not what
 * it competes with; one that trouble asked for waits only long enough for
 * the frames around it to land. */
const DRAIN_AFTER_OPEN_MS = 20_000;
const DRAIN_AFTER_TROUBLE_MS = 5_000;
/** Share of sessions that send without having seen trouble. One in a
 * hundred is a few dozen baselines a day at the current size, which is
 * enough to draw a percentile against. */
const SAMPLE_RATE = 0.01;
/** Drains one session will send, and batches each may hold: at most ten
 * events of frames from one session, however long it ran. */
const DRAIN_CAP = 2;
const BATCH_CAP = 5;

interface Stored {
  v: number;
  /** Records in order; `id` is monotonic across page loads. */
  records: PerfLogRecord[];
  nextId: number;
  sentThrough: number;
  /** Epoch milliseconds a session last saw trouble it has not drained, so a
   * page that ended before its drain hands the reason to the next one. */
  troubleAt: number;
}

let state: Stored | null = null;
let sink: ((batch: PerfLogBatch) => void) | null = null;
let sampled = false;
let rolled = false;
let trouble = false;
let drains = 0;
let dirty = false;
let writeTimer: ReturnType<typeof setTimeout> | null = null;
let drainTimer: ReturnType<typeof setTimeout> | null = null;
let openedAt = 0;
let removePageHide: (() => void) | null = null;

const idle = (fn: () => void): void => {
  if (typeof requestIdleCallback === "function") requestIdleCallback(() => fn(), { timeout: 5_000 });
  else setTimeout(fn, 0);
};

function load(): Stored {
  if (state) return state;
  let parsed: Stored | null = null;
  try {
    const raw = localStorage.getItem(KEY);
    if (raw) parsed = JSON.parse(raw) as Stored;
  } catch {
    parsed = null;
  }
  state =
    parsed && parsed.v === VERSION && Array.isArray(parsed.records)
      ? { ...parsed, troubleAt: parsed.troubleAt || 0 }
      : { v: VERSION, records: [], nextId: 1, sentThrough: 0, troubleAt: 0 };
  return state;
}

function persist(): void {
  if (!dirty || !state) return;
  dirty = false;
  try {
    localStorage.setItem(KEY, JSON.stringify(state));
  } catch {
    // Storage full or unavailable; the records stay in memory and send from
    // there.
  }
}

function scheduleWrite(): void {
  dirty = true;
  if (writeTimer) return;
  writeTimer = setTimeout(() => {
    writeTimer = null;
    idle(persist);
  }, WRITE_MIN_MS);
}

/** Keep one frame. Cheap enough to call from a performance observer. */
export function logPerfRecord(rec: Omit<PerfLogRecord, "id" | "open" | "memMb">): void {
  if (typeof window === "undefined") return;
  const s = load();
  s.records.push({ ...rec, open: openedAt, id: s.nextId++, memMb: mb(memoryTotalCached()) });
  if (s.records.length > CAP) s.records.splice(0, s.records.length - CAP);
  scheduleWrite();
}

/** Why this session sends, or null while it has no reason to. The meters
 * ask before every summary. */
export function perfUploadReason(): PerfUploadReason | null {
  if (trouble) return "trouble";
  if (sampled) return "sampled";
  return null;
}

/** The session has seen something worth sending: the log drains shortly,
 * carrying the frames that led here, and summaries send from now on. */
export function notePerfTrouble(): void {
  if (trouble) return;
  trouble = true;
  if (state) {
    state.troubleAt = Date.now();
    scheduleWrite();
  }
  if (sink) scheduleDrain(DRAIN_AFTER_TROUBLE_MS);
}

/** Send everything not yet sent, in batches, and remember how far that got.
 * Sends nothing while the session has no reason to, and after its share of
 * drains is spent. */
export function drainPerfLog(): void {
  const s = state;
  const reason = perfUploadReason();
  if (!s || !sink || !reason || drains >= DRAIN_CAP) return;
  const pending = s.records.filter((r) => r.id > s.sentThrough).slice(-BATCH * BATCH_CAP);
  if (pending.length === 0) return;
  drains++;
  const of = Math.ceil(pending.length / BATCH);
  const cores = navigator.hardwareConcurrency || 0;
  const memoryGb = (navigator as unknown as { deviceMemory?: number }).deviceMemory ?? 0;
  const usage = memoryUsage();
  for (let i = 0; i < of; i++) {
    sink({
      batch: i + 1,
      of,
      reason,
      records: pending.slice(i * BATCH, (i + 1) * BATCH),
      cores,
      memoryGb,
      memMb: mb(usage.total),
      memCeilingMb: mb(memoryCeiling()),
      heapMb: mb(heapBytes()),
    });
  }
  s.sentThrough = pending[pending.length - 1].id;
  s.troubleAt = 0;
  dirty = true;
  persist();
}

function scheduleDrain(afterMs: number): void {
  if (drainTimer) clearTimeout(drainTimer);
  drainTimer = setTimeout(() => {
    drainTimer = null;
    idle(() => {
      // The editor may have closed while this waited for an idle moment, and
      // a timer armed after that is one nothing can clear.
      if (!sink) return;
      drainPerfLog();
      scheduleDrain(DRAIN_MIN_MS);
    });
  }, afterMs);
}

/**
 * Start keeping the log and sending it through `send`.
 *
 * The first drain, shortly after open, carries what the previous page left
 * behind — and a page that left unsent frames behind is one that never got to
 * send them, which is trouble in itself; later drains run a few minutes
 * apart. The page hiding writes and sends at once — the analytics client
 * beacons what it is handed there.
 */
export function startPerfLog(send: (batch: PerfLogBatch) => void): void {
  sink = send;
  if (typeof window === "undefined" || removePageHide) return;
  openedAt = openedAt || Date.now();
  // Rolled once for the page, not once per project opened in it: a dice throw
  // per editor mount would make the baseline a share of opens rather than a
  // share of sessions, and inflate the very population trouble is measured
  // against.
  if (!rolled) {
    rolled = true;
    sampled = Math.random() < SAMPLE_RATE;
  }
  const s = load();
  const stale = s.records.findIndex((r) => openedAt - r.at < KEEP_MS);
  if (stale !== 0) {
    s.records.splice(0, stale === -1 ? s.records.length : stale);
    dirty = true;
  }
  if (s.troubleAt && s.records.some((r) => r.id > s.sentThrough)) trouble = true;
  scheduleDrain(DRAIN_AFTER_OPEN_MS);
  const onHide = () => {
    if (document.visibilityState !== "hidden") return;
    persist();
    drainPerfLog();
  };
  document.addEventListener("visibilitychange", onHide);
  window.addEventListener("pagehide", onHide);
  removePageHide = () => {
    document.removeEventListener("visibilitychange", onHide);
    window.removeEventListener("pagehide", onHide);
  };
}

/** Stop keeping the log, sending what is in hand first. */
export function stopPerfLog(): void {
  if (writeTimer) clearTimeout(writeTimer);
  writeTimer = null;
  if (drainTimer) clearTimeout(drainTimer);
  drainTimer = null;
  persist();
  drainPerfLog();
  removePageHide?.();
  removePageHide = null;
  sink = null;
}