Skip to content

Build your personal knowledge base with Trilium Notes

10.0 KB
Raw Blame
/**
 * Opt-in main-thread instrumentation for tracking down UI stalls.
 *
 * Recording is off by default and every entry point costs one boolean check when off, so call
 * sites can sit in hot paths (per-card renders, per-cell formatting) without being paid for in
 * normal use. Drive it from the devtools console:
 *
 * ```js
 * triliumPerf.enable();     // start recording; also logs every long task as it happens
 * triliumPerf.report();     // print what has been gathered so far
 * triliumPerf.reset();      // clear the counters, keep recording
 * triliumPerf.disable();
 * triliumPerf.components(); // census the widget tree, for hunting leaked widgets
 * ```
 *
 * Spans additionally land on the User Timing track via `performance.measure()`, so a DevTools
 * performance capture shows them lined up against the long tasks they explain.
 *
 * Nothing calls into this by default, and that is deliberate rather than an oversight: instrument
 * whatever is being investigated for as long as it takes to answer the question, then take the call
 * sites back out. Adding the first `perfSpan()` or `perfCount()` anywhere is what pulls this module
 * into the bundle, which is also what puts `triliumPerf` on `window` -- so there is nothing to arm
 * beyond the call site itself.
 */

interface Counter {
    calls: number;
    totalMs: number;
    maxMs: number;
}

/** Closing a span that was never opened, because recording is off. */
const NOOP_SPAN = () => 0;

/**
 * A main-thread block this long counts as a stall. Matches the Long Tasks API's own threshold, so
 * the two detectors below report comparable numbers.
 */
const STALL_THRESHOLD_MS = 50;

let enabled = false;
let recordingStartedAt = 0;
let longTaskObserver: PerformanceObserver | undefined;
let stallFrameHandle: number | undefined;
const counters = new Map<string, Counter>();

export function isPerfRecording() {
    return enabled;
}

/**
 * Opens a span. Call the returned function to close it, which records the elapsed time under
 * `label`, emits a matching `performance.measure()` entry, and returns the elapsed milliseconds.
 *
 * Prefer that returned number over the STALL lines for "what did this one operation cost": a stall
 * is the gap between animation frames, so on a saturated main thread it reports the whole
 * contiguous busy period and lumps however many operations fell inside it together.
 *
 * Returns a no-op when recording is off, so the caller does not need to branch.
 */
export function perfSpan(label: string): () => number {
    if (!enabled) {
        return NOOP_SPAN;
    }

    const start = performance.now();
    return () => {
        const end = performance.now();
        const duration = end - start;
        record(label, duration);

        try {
            // Same clock as performance.now(), so the span lands where it actually happened.
            performance.measure(label, { start, end });
        } catch (e) {
            // A measure() that the browser rejects must not take the instrumented code down.
        }

        return duration;
    };
}

/** Records `count` occurrences of `label` without timing them. */
export function perfCount(label: string, count = 1) {
    if (!enabled) {
        return;
    }

    record(label, 0, count);
}

/** Times a synchronous call and returns its result untouched. */
export function perfTime<T>(label: string, fn: () => T): T {
    if (!enabled) {
        return fn();
    }

    const start = performance.now();
    try {
        return fn();
    } finally {
        record(label, performance.now() - start);
    }
}

/** Logs a one-off event, stamped with how far into the recording it happened. */
export function perfLog(label: string, detail?: Record<string, unknown>) {
    if (!enabled) {
        return;
    }

    const at = (performance.now() - recordingStartedAt).toFixed(0);
    console.log(`[perf +${at}ms] ${label}`, detail ?? "");
}

function record(label: string, durationMs: number, count = 1) {
    let counter = counters.get(label);
    if (!counter) {
        counter = { calls: 0, totalMs: 0, maxMs: 0 };
        counters.set(label, counter);
    }

    counter.calls += count;
    counter.totalMs += durationMs;
    counter.maxMs = Math.max(counter.maxMs, durationMs);
}

function enable() {
    if (enabled) {
        return;
    }

    enabled = true;
    recordingStartedAt = performance.now();
    counters.clear();

    startStallDetection();

    console.log("[perf] recording. triliumPerf.report() to print, triliumPerf.disable() to stop.");
}

function disable() {
    enabled = false;
    longTaskObserver?.disconnect();
    longTaskObserver = undefined;

    if (stallFrameHandle !== undefined) {
        cancelAnimationFrame(stallFrameHandle);
        stallFrameHandle = undefined;
    }

    console.log("[perf] stopped.");
}

/**
 * Starts reporting main-thread stalls, preferring the Long Tasks API and falling back to watching
 * for late animation frames where it is missing.
 *
 * The fallback exists because only Chromium implements the `longtask` entry type, and
 * `observe({ entryTypes })` drops an unrecognized type with nothing but a console warning rather
 * than throwing — so on Firefox the observer silently reports nothing at all, which reads as "no
 * stalls happened" instead of "this browser cannot see them".
 */
function startStallDetection() {
    if (PerformanceObserver.supportedEntryTypes?.includes("longtask")) {
        longTaskObserver = new PerformanceObserver((list) => {
            for (const entry of list.getEntries()) {
                reportStall(entry.startTime, entry.duration);
            }
        });
        longTaskObserver.observe({ entryTypes: [ "longtask" ] });
        console.log("[perf] stalls: Long Tasks API.");
        return;
    }

    console.log("[perf] stalls: animation-frame watchdog (this browser has no Long Tasks API).");
    watchForLateFrames();
}

/**
 * Approximates long tasks by measuring the gap between animation frames: work that blocks the main
 * thread pushes the next frame out by roughly its own duration.
 *
 * Less precise than the Long Tasks API -- it cannot see a block that lands while the page is not
 * painting, and it charges the gap to the frame boundary rather than to the task -- but it is
 * enough to time a stall and line it up against the spans around it.
 */
function watchForLateFrames() {
    let previousFrameAt = performance.now();

    const onFrame = () => {
        if (!enabled) {
            return;
        }

        const now = performance.now();
        const gap = now - previousFrameAt;
        if (gap >= STALL_THRESHOLD_MS) {
            reportStall(previousFrameAt, gap);
        }

        previousFrameAt = now;
        stallFrameHandle = requestAnimationFrame(onFrame);
    };

    stallFrameHandle = requestAnimationFrame(onFrame);
}

function reportStall(startTime: number, durationMs: number) {
    record("stall", durationMs);
    const at = (startTime - recordingStartedAt).toFixed(0);
    console.log(`[perf +${at}ms] STALL ${durationMs.toFixed(0)}ms`);
}

function reset() {
    counters.clear();
    recordingStartedAt = performance.now();
}

function report() {
    const elapsed = performance.now() - recordingStartedAt;
    const rows = [ ...counters.entries() ]
        .sort((a, b) => b[1].totalMs - a[1].totalMs || b[1].calls - a[1].calls)
        .map(([ label, { calls, totalMs, maxMs } ]) => ({
            label,
            calls,
            "total (ms)": +totalMs.toFixed(1),
            "avg (ms)": +(totalMs / calls).toFixed(3),
            "max (ms)": +maxMs.toFixed(1)
        }));

    console.log(`[perf] ${(elapsed / 1000).toFixed(1)}s recorded`);
    console.table(rows);
}

/** The parts of a `Component` the census reads, so that this module doesn't have to import one. */
interface CensusComponent {
    children: CensusComponent[];
    /** Handlers registered by `useTriliumEvent`. Private on the component, hence the local shape. */
    listeners: Record<string, Set<unknown>> | null;
}

let previousCensus = new Map<string, number>();

/**
 * Prints how many components are reachable from the root of the widget tree, and how many React
 * event handlers they hold, broken down by class and by event.
 *
 * For hunting leaks of the "the tab was closed but its widgets kept handling events" kind: take a
 * reading, open and close a few tabs, take another. The `since last` column is what matters --
 * anything that doesn't come back down stayed in the tree. `NoteWrapperWidget` should always equal
 * the number of open splits.
 *
 * Independent of `enable()`: it walks live state rather than anything that had to be recorded.
 */
function components() {
    const root = window.glob?.appContext as unknown as CensusComponent | undefined;
    if (!root) {
        console.log("[perf] no appContext to walk (is the app still starting up?).");
        return;
    }

    const counts = new Map<string, number>();
    let total = 0;
    let handlers = 0;

    function count(key: string, by: number) {
        counts.set(key, (counts.get(key) ?? 0) + by);
    }

    (function walk(component: CensusComponent) {
        total++;
        count(`class ${component.constructor.name}`, 1);

        for (const [ eventName, listeners ] of Object.entries(component.listeners ?? {})) {
            handlers += listeners.size;
            count(`event ${eventName}`, listeners.size);
        }

        component.children.forEach(walk);
    })(root);

    const rows = [ ...counts.entries() ]
        .map(([ what, count ]) => ({ what, count, "since last": count - (previousCensus.get(what) ?? 0) }))
        .sort((a, b) => b["since last"] - a["since last"] || b.count - a.count);

    // Anything gone since the last reading has no row of its own, so surface it as a negative one.
    for (const [ what, count ] of previousCensus) {
        if (!counts.has(what)) {
            rows.push({ what, count: 0, "since last": -count });
        }
    }

    previousCensus = counts;

    console.log(`[perf] ${total} components, ${handlers} React handlers reachable from the root`);
    console.table(rows);
}

const triliumPerf = { enable, disable, reset, report, components };
export default triliumPerf;

window.triliumPerf = triliumPerf;