browsertime 27.5.0 → 28.1.0

package/lib/chrome/parseCpuTrace.js

@@ -3,10 +3,28 @@ import {
   computeMainThreadTasks,
   computeScriptCosts,
   computeForcedReflows,
-  computeNonCompositedAnimations
+  computeNonCompositedAnimations,
+  computeBlockingTime,
+  computeDomainBreakdown,
+  computeFrameStability,
+  computeStyleInvalidations,
+  computeSelectorStats,
+  computeTimerCosts
 } from './trace/index.js';
+import { labelForUrl } from './mediawikiResourceLoader.js';
 const log = getLogger('browsertime.chrome.cpu');
 
+// Additive label field for MediaWiki ResourceLoader URLs so per-bundle
+// time series survive the weekly version= churn. The url field is
+// untouched (browsertime.json shape is a public contract); non-MediaWiki
+// URLs get no label and the output stays byte-identical to before.
+function addResourceLoaderLabels(entries, urlField = 'url', field = 'label') {
+  for (const entry of entries) {
+    const label = labelForUrl(entry[urlField]);
+    if (label) entry[field] = label;
+  }
+}
+
 function round(number_, decimals = 3) {
   const pow = Math.pow(10, decimals);
   return Math.round(number_ * pow) / pow;
@@ -105,6 +123,67 @@ export async function parseCPUTrace(tracelog, url) {
     } catch (error) {
       log.debug('computeNonCompositedAnimations failed: %s', error.message);
     }
+    // These return objects with summary totals, so on failure the
+    // key is omitted instead of publishing a misleading zero total.
+    let blocking;
+    try {
+      blocking = computeBlockingTime(tracelog);
+    } catch (error) {
+      log.debug('computeBlockingTime failed: %s', error.message);
+    }
+    let domains;
+    try {
+      domains = computeDomainBreakdown(tracelog, url);
+    } catch (error) {
+      log.debug('computeDomainBreakdown failed: %s', error.message);
+    }
+    let frames;
+    try {
+      frames = computeFrameStability(tracelog);
+    } catch (error) {
+      log.debug('computeFrameStability failed: %s', error.message);
+    }
+    let styleInvalidations;
+    try {
+      styleInvalidations = computeStyleInvalidations(tracelog);
+    } catch (error) {
+      log.debug('computeStyleInvalidations failed: %s', error.message);
+    }
+    // Only produces output when the SelectorStats trace category is
+    // on (--enableProfileRun); undefined omits the key.
+    let selectorStats;
+    try {
+      selectorStats = computeSelectorStats(tracelog);
+    } catch (error) {
+      log.debug('computeSelectorStats failed: %s', error.message);
+    }
+    let timers;
+    try {
+      timers = computeTimerCosts(tracelog);
+    } catch (error) {
+      log.debug('computeTimerCosts failed: %s', error.message);
+    }
+
+    addResourceLoaderLabels(cleanedUrls);
+    addResourceLoaderLabels(scriptCosts);
+    addResourceLoaderLabels(
+      forcedReflows,
+      'triggeredByUrl',
+      'triggeredByUrlLabel'
+    );
+    if (blocking) {
+      addResourceLoaderLabels(blocking.urls);
+      if (blocking.beforeLargestContentfulPaint) {
+        addResourceLoaderLabels(blocking.beforeLargestContentfulPaint.urls);
+      }
+    }
+    if (styleInvalidations) {
+      addResourceLoaderLabels(styleInvalidations.sources);
+    }
+    if (timers) {
+      addResourceLoaderLabels(timers.byUrl);
+      addResourceLoaderLabels(timers.sites);
+    }
 
     log.debug('Chrome trace log finished parsed and sorted.');
     return {
@@ -113,7 +192,13 @@ export async function parseCPUTrace(tracelog, url) {
       urls: cleanedUrls,
       scriptCosts,
       forcedReflows,
-      nonCompositedAnimations
+      nonCompositedAnimations,
+      ...(blocking ? { blocking } : {}),
+      ...(domains ? { domains } : {}),
+      ...(frames ? { frames } : {}),
+      ...(styleInvalidations ? { styleInvalidations } : {}),
+      ...(selectorStats ? { selectorStats } : {}),
+      ...(timers ? { timers } : {})
     };
   } catch (error) {
     log.error(

package/lib/chrome/trace/blocking-time.js

@@ -0,0 +1,189 @@
+/**
+ * Blocking-time attribution per URL and per kind of work.
+ *
+ * A top-level main-thread task longer than 50 ms blocks input for
+ * (duration - 50) ms — the same definition Lighthouse's Total
+ * Blocking Time uses. Knowing the page's TBT is one thing; knowing
+ * WHICH script produced it is what tells you what to fix first, so
+ * each blocking task is attributed to a URL:
+ *
+ * Top-level tasks are often anonymous wrappers (RunTask et al.) whose
+ * own attributableURLs is empty while the real work sits in child
+ * tasks. So instead of only looking at the top-level task's own URL
+ * chain, the whole subtree is walked and the task is attributed to
+ * the URL that contributed the most self-time (each node credited to
+ * its most-specific URL, attributableURLs.at(-1), the same choice
+ * script-costs.js makes). ParseHTML nodes carry no attributable URL
+ * (main-thread-tasks.js only reads URLs from script events and stack
+ * frames, and stays byte-equivalent for cpu.urls consumers), so here
+ * they fall back to the document URL in args.beginData.url — a page
+ * blocked by parsing its own big HTML gets attributed to that
+ * document instead of disappearing. Tasks where no node carries any
+ * URL go to the 'unknown' bucket — browser-internal work (GC, style,
+ * layout without a JS trigger) no script owns.
+ *
+ * Blocking time is also split by KIND of work: each blocking task's
+ * subtree self-time per task group (parseHTML, styleLayout,
+ * scriptEvaluation, …) is scaled to the task's blocking share and
+ * summed per window into `kinds`. The per-URL list says who to blame;
+ * the kinds split says what kind of fix applies — script blocking
+ * needs code changes, parse/style blocking needs a smaller document
+ * or cheaper CSS.
+ *
+ * Two windows are reported: the whole trace, and navigationStart →
+ * the last largestContentfulPaint::Candidate event (blocking time in
+ * that window is what delayed LCP). Task times from
+ * main-thread-tasks.js are ms rebased to the first task, while the
+ * navigationStart / LCP timestamps are raw trace µs — the window
+ * check therefore uses the task's raw event.ts instead of converting
+ * back and forth. When the trace has no LCP candidate the LCP window
+ * is omitted rather than guessed.
+ *
+ * Returns:
+ *   { totalBlockingTime, tasks, urls: [{ url, value, tasks }, …],
+ *     kinds: { styleLayout: ms, … },
+ *     beforeLargestContentfulPaint?: { totalBlockingTime, tasks,
+ *                                      urls: [...], kinds: {...} } }
+ * Times in ms rounded to one decimal; url lists sorted by value desc
+ * and noise-filtered to entries above 10 ms, matching cpu.urls.
+ * Kinds that round to 0 ms are omitted.
+ */
+
+import { getMainThreadTasks } from './main-thread-tasks.js';
+import { computeTraceOfTab } from './trace-of-tab.js';
+
+const BLOCKING_THRESHOLD_MS = 50;
+const REPORT_LIMIT_MS = 10;
+const UNKNOWN = 'unknown';
+
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+
+function nodeUrl(node) {
+  const url = node.attributableURLs.at(-1);
+  if (url) return url;
+  if (node.event.name === 'ParseHTML') {
+    const beginData = node.event.args && node.event.args.beginData;
+    return beginData && beginData.url;
+  }
+}
+
+// One subtree walk computing both attributions for a blocking task:
+// the dominant URL (most self-time) and the self-time per task kind.
+function analyzeTask(task) {
+  const selfTimeByUrl = new Map();
+  const selfTimeByKind = new Map();
+  const stack = [task];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    const url = nodeUrl(node);
+    if (url) {
+      selfTimeByUrl.set(url, (selfTimeByUrl.get(url) || 0) + node.selfTime);
+    }
+    const kind = node.group.id;
+    selfTimeByKind.set(kind, (selfTimeByKind.get(kind) || 0) + node.selfTime);
+    stack.push(...node.children);
+  }
+  let bestUrl;
+  let bestTime = 0;
+  for (const [url, time] of selfTimeByUrl) {
+    if (time > bestTime) {
+      bestUrl = url;
+      bestTime = time;
+    }
+  }
+  return { url: bestUrl || UNKNOWN, selfTimeByKind };
+}
+
+function newWindow() {
+  return {
+    totalBlockingTime: 0,
+    tasks: 0,
+    byUrl: new Map(),
+    byKind: new Map()
+  };
+}
+
+function addToWindow(window, task, blocking, analysis) {
+  window.totalBlockingTime += blocking;
+  window.tasks += 1;
+  let entry = window.byUrl.get(analysis.url);
+  if (!entry) {
+    entry = { url: analysis.url, value: 0, tasks: 0 };
+    window.byUrl.set(analysis.url, entry);
+  }
+  entry.value += blocking;
+  entry.tasks += 1;
+  // Scale each kind's subtree self-time to the task's blocking share,
+  // so the kinds sum to totalBlockingTime instead of raw durations.
+  for (const [kind, selfTime] of analysis.selfTimeByKind) {
+    const share = (selfTime / task.duration) * blocking;
+    window.byKind.set(kind, (window.byKind.get(kind) || 0) + share);
+  }
+}
+
+function finishWindow(window) {
+  const urls = [];
+  for (const entry of window.byUrl.values()) {
+    if (entry.value > REPORT_LIMIT_MS) {
+      entry.value = round(entry.value);
+      urls.push(entry);
+    }
+  }
+  urls.sort((a, b) => b.value - a.value);
+  const kinds = {};
+  for (const [kind, value] of [...window.byKind.entries()].toSorted(
+    (a, b) => b[1] - a[1]
+  )) {
+    const rounded = round(value);
+    if (rounded > 0) kinds[kind] = rounded;
+  }
+  return {
+    totalBlockingTime: round(window.totalBlockingTime),
+    tasks: window.tasks,
+    urls,
+    kinds
+  };
+}
+
+export function computeBlockingTime(trace) {
+  const { mainThreadEvents, timestamps } = computeTraceOfTab(trace);
+  const tasks = getMainThreadTasks(mainThreadEvents, timestamps.traceEnd);
+
+  let lcpEvent;
+  for (const event of trace.traceEvents) {
+    if (
+      event.name === 'largestContentfulPaint::Candidate' &&
+      (!lcpEvent || event.ts > lcpEvent.ts)
+    ) {
+      lcpEvent = event;
+    }
+  }
+
+  const total = newWindow();
+  const beforeLcp = newWindow();
+
+  for (const task of tasks) {
+    if (task.parent) continue;
+    if (task.duration <= BLOCKING_THRESHOLD_MS) continue;
+
+    const blocking = task.duration - BLOCKING_THRESHOLD_MS;
+    const analysis = analyzeTask(task);
+    addToWindow(total, task, blocking, analysis);
+
+    if (
+      lcpEvent &&
+      task.event.ts >= timestamps.navigationStart &&
+      task.event.ts < lcpEvent.ts
+    ) {
+      addToWindow(beforeLcp, task, blocking, analysis);
+    }
+  }
+
+  const result = finishWindow(total);
+  if (lcpEvent) {
+    result.beforeLargestContentfulPaint = finishWindow(beforeLcp);
+  }
+  return result;
+}

package/lib/chrome/trace/domain-breakdown.js

@@ -0,0 +1,86 @@
+/**
+ * First-party vs third-party main-thread rollup.
+ *
+ * cpu.urls answers "which URL costs the most main-thread time";
+ * this answers the level above it — how much of the main thread the
+ * site's own code uses versus embedded third parties, and which
+ * domains those third parties are. Each task's self-time is credited
+ * to its most-specific attributable URL (attributableURLs.at(-1),
+ * same choice as script-costs.js) so a task counts once — cpu.urls
+ * deliberately credits the full URL chain, which would double-count
+ * across domains here. Tasks with no attributable URL are
+ * browser-internal work no domain owns and are skipped.
+ *
+ * First-party is decided by registrable domain: the last two labels
+ * of the hostname, so every subdomain of the tested page's domain is
+ * first-party (en.wikipedia.org and upload.wikimedia.org roll up to
+ * wikipedia.org / wikimedia.org). Deliberately NOT a full public
+ * suffix list — two-level public suffixes (co.uk, com.au, …) group
+ * one label too high, which is acceptable for a rollup and avoids
+ * carrying an eTLD+1 dependency.
+ *
+ * Returns:
+ *   { firstPartyDomain, firstParty, thirdParty,
+ *     domains: [{ domain, value, firstParty }, …] }
+ * Times in ms rounded to one decimal; domains sorted by value desc
+ * and noise-filtered to entries above 10 ms, matching cpu.urls. The
+ * firstParty / thirdParty totals include the filtered-out remainder.
+ */
+
+import { compute } from './main-thread-tasks.js';
+
+const REPORT_LIMIT_MS = 10;
+
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+
+function registrableDomain(hostname) {
+  const labels = hostname.split('.');
+  return labels.length <= 2 ? hostname : labels.slice(-2).join('.');
+}
+
+function domainOf(url) {
+  try {
+    const { hostname } = new URL(url);
+    return hostname ? registrableDomain(hostname) : undefined;
+  } catch {
+    return;
+  }
+}
+
+export function computeDomainBreakdown(trace, pageUrl) {
+  const firstPartyDomain = registrableDomain(new URL(pageUrl).hostname);
+  const byDomain = new Map();
+
+  for (const task of compute(trace)) {
+    const url = task.attributableURLs.at(-1);
+    if (!url) continue;
+    const domain = domainOf(url);
+    if (!domain) continue;
+    byDomain.set(domain, (byDomain.get(domain) || 0) + task.selfTime);
+  }
+
+  let firstParty = 0;
+  let thirdParty = 0;
+  const domains = [];
+  for (const [domain, value] of byDomain) {
+    const isFirstParty = domain === firstPartyDomain;
+    if (isFirstParty) {
+      firstParty += value;
+    } else {
+      thirdParty += value;
+    }
+    if (value > REPORT_LIMIT_MS) {
+      domains.push({ domain, value: round(value), firstParty: isFirstParty });
+    }
+  }
+  domains.sort((a, b) => b.value - a.value);
+
+  return {
+    firstPartyDomain,
+    firstParty: round(firstParty),
+    thirdParty: round(thirdParty),
+    domains
+  };
+}

package/lib/chrome/trace/frame-stability.js

@@ -0,0 +1,135 @@
+/**
+ * Frame stability — how smoothly the compositor produced frames
+ * during the traced window. Jank (dropped frames, long gaps between
+ * visual updates) is invisible in load metrics; this surfaces it
+ * from the trace browsertime already records.
+ *
+ * Event shapes sampled from Chrome 150.0.7871.115 with the default
+ * browsertime trace categories. The frame pipeline shows up as
+ * `PipelineReporter` async events (cat
+ * `cc,benchmark,disabled-by-default-devtools.timeline.frame`), one
+ * b/e pair per frame attempt, paired via `id2.local` within a
+ * process. The `b` event carries `args.frame_reporter` with the
+ * final outcome: `state` (STATE_PRESENTED_ALL /
+ * STATE_PRESENTED_PARTIAL / STATE_DROPPED / STATE_NO_UPDATE_DESIRED),
+ * `affects_smoothness`, and `frame_sequence`. The `e` timestamp is
+ * when the frame reached the screen (presentation) for presented
+ * frames. The same frame_sequence can have several reporters
+ * (forked / main + impl), so outcomes are merged per sequence. The
+ * legacy instant events (BeginFrame, DrawFrame, DroppedFrame) are
+ * still emitted and were used to cross-check: DroppedFrame instants
+ * match STATE_DROPPED reporters with affects_smoothness=true.
+ *
+ * Only STATE_DROPPED frames flagged `affects_smoothness` are counted
+ * as dropped — Chrome also marks no-damage idle frames STATE_DROPPED
+ * and counting those would alarm on every static page.
+ *
+ * Returns: { presented, partial, dropped, effectiveFps, longestGap }
+ *   presented    — frames that reached the screen after
+ *                  navigationStart
+ *   partial      — subset of presented where the compositor
+ *                  presented without the main-thread update
+ *                  (STATE_PRESENTED_PARTIAL only)
+ *   dropped      — frames Chrome flags as dropped AND affecting
+ *                  smoothness (its own jank signal)
+ *   effectiveFps — presented frames over the first→last
+ *                  presentation span; omitted with <2 presentations
+ *   longestGap   — { duration, startTime } in ms relative to
+ *                  navigationStart, the longest time between two
+ *                  consecutive presented frames. On mostly-static
+ *                  pages this includes idle time (nothing to draw),
+ *                  so read it as "longest time between visual
+ *                  updates", not proof of jank; omitted with <2
+ *                  presentations
+ */
+
+import { computeTraceOfTab } from './trace-of-tab.js';
+
+const PRESENTED_STATES = new Set([
+  'STATE_PRESENTED_ALL',
+  'STATE_PRESENTED_PARTIAL'
+]);
+
+function round1(number_) {
+  return Math.round(number_ * 10) / 10;
+}
+
+export function computeFrameStability(trace) {
+  const { mainFrameIds, timestamps } = computeTraceOfTab(trace);
+  const navStart = timestamps.navigationStart;
+
+  const open = new Map();
+  const bySequence = new Map();
+  for (const event of trace.traceEvents) {
+    if (event.name !== 'PipelineReporter' || event.pid !== mainFrameIds.pid)
+      continue;
+    const id = (event.id2 && event.id2.local) || event.id;
+    if (event.ph === 'b') {
+      open.set(id, event);
+    } else if (event.ph === 'e') {
+      const begin = open.get(id);
+      if (!begin) continue;
+      open.delete(id);
+      if (event.ts < navStart) continue;
+      const reporter = (begin.args && begin.args.frame_reporter) || {};
+      if (reporter.frame_sequence === undefined) continue;
+      let frame = bySequence.get(reporter.frame_sequence);
+      if (!frame) {
+        frame = { presentedAll: false, presentedPartial: false };
+        bySequence.set(reporter.frame_sequence, frame);
+      }
+      if (PRESENTED_STATES.has(reporter.state)) {
+        if (reporter.state === 'STATE_PRESENTED_ALL') frame.presentedAll = true;
+        else frame.presentedPartial = true;
+        frame.presentationTs = Math.min(
+          frame.presentationTs ?? Number.POSITIVE_INFINITY,
+          event.ts
+        );
+      } else if (
+        reporter.state === 'STATE_DROPPED' &&
+        reporter.affects_smoothness === true
+      ) {
+        frame.dropped = true;
+      }
+    }
+  }
+
+  let presented = 0;
+  let partial = 0;
+  let dropped = 0;
+  const presentationTimes = [];
+  for (const frame of bySequence.values()) {
+    if (frame.presentedAll || frame.presentedPartial) {
+      presented++;
+      if (!frame.presentedAll) partial++;
+      presentationTimes.push(frame.presentationTs);
+    } else if (frame.dropped) {
+      dropped++;
+    }
+  }
+  presentationTimes.sort((a, b) => a - b);
+
+  let effectiveFps;
+  let longestGap;
+  if (presentationTimes.length >= 2) {
+    const spanSeconds = (presentationTimes.at(-1) - presentationTimes[0]) / 1e6;
+    if (spanSeconds > 0) {
+      effectiveFps = round1((presentationTimes.length - 1) / spanSeconds);
+    }
+    let worst = 0;
+    let worstStart = presentationTimes[0];
+    for (let index = 1; index < presentationTimes.length; index++) {
+      const gap = presentationTimes[index] - presentationTimes[index - 1];
+      if (gap > worst) {
+        worst = gap;
+        worstStart = presentationTimes[index - 1];
+      }
+    }
+    longestGap = {
+      duration: round1(worst / 1000),
+      startTime: round1((worstStart - navStart) / 1000)
+    };
+  }
+
+  return { presented, partial, dropped, effectiveFps, longestGap };
+}