Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ If your agent environment supports on-demand skills (such as `.gemini/skills/chr
````markdown
---
name: chrome-trace-analysis
description: Inspect and query Chrome/DevTools performance trace files and test fixtures (.json, .json.gz) using trace-engine-cli. Use when analyzing trace events, insights, or fixtures.
description: Inspect and query saved Chrome/DevTools performance trace files and test fixtures (.json, .json.gz) using trace-engine-cli. Use when analyzing trace events, CPU activity, Web Vitals, or diagnostic insights.
---

# Chrome & Chromium DevTools Trace Analysis
Expand Down Expand Up @@ -226,6 +226,14 @@ trace-engine-cli scan fixtures/traces/ --cat devtools.timeline --phase X
2. Inspect navigations and insight set IDs: `trace-engine-cli navigations <fixture>`
3. Inspect relevant subsystem: `trace-engine-cli shifts <fixture> --events`, `trace-engine-cli network <fixture>`, or `trace-engine-cli insights <fixture> --category <category>`
4. Inspect raw event payloads: `trace-engine-cli events <fixture> --name <EventName> --fields <fieldPaths>`

---

## 5. Capture Caveats

- **Missing page frames**. Browser-target CDP recordings can omit frame metadata. Record and save a trace from the DevTools Performance panel, or send `Tracing.start` on a CDP session attached to the page target. Use `trace-engine-cli scan <file>` to search raw events in an existing recording.
- **Missing layout-shift data**. Include the `loading` category in CDP recordings for CLS analysis.
- **Missing JavaScript samples**. Leave JavaScript sampling enabled in DevTools or include `disabled-by-default-v8.cpu_profiler` in CDP recordings for sampled call stacks.
````

</details>
Expand Down
21 changes: 17 additions & 4 deletions src/engine/extractors/overview.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,14 @@

import type { TimeRange } from '../../utils/filter.js';
import { microToMilli, round } from '../../utils/units.js';
import { getMainRendererThread, getPrimaryInsightSet } from '../helpers.js';
import {
getMainRendererThread,
getPrimaryInsightSet,
MISSING_CPU_SAMPLES,
PAGE_TRACE_CAPTURE_HINT,
shouldWarnAboutLayoutShiftCapture,
UNCONFIRMED_LAYOUT_SHIFT_CAPTURE,
} from '../helpers.js';
import type { LoadedTrace } from '../loader.js';
import type { CwvRating, OverviewResult } from '../types.js';

Expand Down Expand Up @@ -65,14 +72,16 @@ export function extractOverview(
const durationMs = round(maxMs - minMs);

// 2. Main URL & Navigation Start
const mainUrl = data.Meta.mainFrameURL || null;
const mainFrameId = data.Meta.mainFrameId;
// The engine can retain the previous trace's main frame ID and URL when no frame is recorded.
const hasMainFrame = data.Meta.rendererProcessesByFrame.has(mainFrameId);
const mainUrl = hasMainFrame ? data.Meta.mainFrameURL || null : null;
const mainNavs = data.Meta.mainFrameNavigations || [];
const allNavs = Array.from(data.Meta.navigationsByNavigationId?.values() || []);
const firstNav = mainNavs[0] || allNavs[0];
const navigationStartMs = firstNav ? round(microToMilli(firstNav.ts)) : null;

// 3. Core Web Vitals
const mainFrameId = data.Meta.mainFrameId;
const pageMetrics = data.PageLoadMetrics?.metricScoresByFrameId?.get(mainFrameId);

let fcp: OverviewResult['coreWebVitals']['fcp'] = null;
Expand Down Expand Up @@ -126,7 +135,8 @@ export function extractOverview(
// CLS
let cls: OverviewResult['coreWebVitals']['cls'] = null;
const layoutShifts = data.LayoutShifts;
if (layoutShifts) {
const warnAboutShiftCapture = shouldWarnAboutLayoutShiftCapture(loadedTrace);
if (layoutShifts && !warnAboutShiftCapture) {
const score = layoutShifts.sessionMaxScore ?? 0;
const worstCluster = layoutShifts.clusters?.[0]?.clusterCumulativeScore;
cls = {
Expand Down Expand Up @@ -234,6 +244,9 @@ export function extractOverview(

// 5. Warnings
const warnings: string[] = [];
if (!hasMainFrame) warnings.push(`No main page frame found. ${PAGE_TRACE_CAPTURE_HINT}`);
if (warnAboutShiftCapture) warnings.push(UNCONFIRMED_LAYOUT_SHIFT_CAPTURE);
if (mainThread && !mainThread.profileCalls.length) warnings.push(MISSING_CPU_SAMPLES);
if (fcp && fcp.rating === 'poor') {
warnings.push(`Poor First Contentful Paint: ${fcp.valueMs}ms (threshold: 1800ms)`);
}
Expand Down
14 changes: 10 additions & 4 deletions src/engine/extractors/shifts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,11 @@

import { isEventInBounds, type TimeRange } from '../../utils/filter.js';
import { microToMilli, round } from '../../utils/units.js';
import { getPrimaryInsightSet } from '../helpers.js';
import {
getPrimaryInsightSet,
shouldWarnAboutLayoutShiftCapture,
UNCONFIRMED_LAYOUT_SHIFT_CAPTURE,
} from '../helpers.js';
import type { LoadedTrace } from '../loader.js';
import type {
ShiftClusterItem,
Expand Down Expand Up @@ -156,7 +160,9 @@ export function extractShifts(
// Sort by score descending
clusters.sort((a, b) => b.cumulativeScore - a.cumulativeScore);

return {
clusters,
};
const result: ShiftsResult = { clusters };
if (shouldWarnAboutLayoutShiftCapture(loadedTrace)) {
result.warnings = [UNCONFIRMED_LAYOUT_SHIFT_CAPTURE];
}
return result;
}
30 changes: 29 additions & 1 deletion src/engine/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

import type { ParsedTrace } from './loader.js';
import type { LoadedTrace, ParsedTrace } from './loader.js';

type MapValue<T> = T extends Map<unknown, infer V> ? V : never;
type RendererProcess = MapValue<NonNullable<ParsedTrace['data']['Renderer']>['processes']>;
Expand Down Expand Up @@ -101,6 +101,34 @@ export function getPrimaryInsightSet(
return findInsightEntry(parsedTrace, navigationId)?.model ?? null;
}

export const PAGE_TRACE_CAPTURE_HINT =
'Record and save a trace from the DevTools Performance panel, or send CDP Tracing.start on a page target session.';

export const UNCONFIRMED_LAYOUT_SHIFT_CAPTURE =
'No layout shifts or loading-category events were observed in this navigation recording. If you used CDP, check whether the loading category was enabled.';

export const MISSING_CPU_SAMPLES =
'No CPU samples were recorded for this thread. Recapture with JavaScript samples enabled in the DevTools Performance panel, or include disabled-by-default-v8.cpu_profiler in CDP.';

const LOADING_CATEGORY = /(?:^|,)loading(?:,|$)/;

export function shouldWarnAboutLayoutShiftCapture({
rawEvents,
parsedTrace,
}: LoadedTrace): boolean {
const { Meta, LayoutShifts } = parsedTrace.data;
// A recording of an already-loaded page may contain no loading events even with CLS enabled.
if (!Meta.mainFrameNavigations.length || LayoutShifts?.clusters.length) return false;

return !rawEvents.some(
(event) =>
typeof event === 'object' &&
event !== null &&
(('name' in event && event.name === 'LayoutShift') ||
('cat' in event && typeof event.cat === 'string' && LOADING_CATEGORY.test(event.cat))),
);
}

/**
* Traverses an object along a dot-separated property path.
*/
Expand Down
9 changes: 9 additions & 0 deletions src/engine/loader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import fs from 'node:fs';
import path from 'node:path';
import zlib from 'node:zlib';
import { loadTraceEngine, type TraceEngine } from './adapter.js';
import { PAGE_TRACE_CAPTURE_HINT } from './helpers.js';

export type ParsedTrace = NonNullable<
ReturnType<InstanceType<TraceEngine['TraceModel']['Model']>['parsedTrace']>
Expand Down Expand Up @@ -149,6 +150,14 @@ export async function loadTraceFromFile(
};

await model.parse(rawEvents as Parameters<typeof model.parse>[0]);
} catch (error) {
if (error instanceof Error && error.message === 'No frames found in trace data') {
throw new Error(
`No frames found in trace data. ${PAGE_TRACE_CAPTURE_HINT} Use scan to search raw events in this file.`,
{ cause: error },
);
}
throw error;
} finally {
console.warn = origWarn;
console.error = origError;
Expand Down
1 change: 1 addition & 0 deletions src/engine/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,7 @@ export interface ShiftClusterItem {
* Layout shifts analysis result.
*/
export interface ShiftsResult {
warnings?: string[];
clusters: ShiftClusterItem[];
}

Expand Down
3 changes: 3 additions & 0 deletions src/formatters/markdown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,9 @@ function formatCulpritLabel(item: {

export function formatShiftsMarkdown(shifts: ShiftsResult): string {
const lines: string[] = ['# Layout Shifts', ''];
if (shifts.warnings?.length) {
lines.push(...shifts.warnings.map((warning) => `- ${warning}`), '');
}
if (shifts.clusters.length === 0) {
lines.push('No layout shifts or clusters detected in trace.');
return lines.join('\n');
Expand Down
30 changes: 30 additions & 0 deletions test/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
// limitations under the License.

import assert from 'node:assert/strict';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import test, { describe } from 'node:test';
import { runCli } from '../src/cli.js';
Expand All @@ -38,6 +40,7 @@ describe('CLI Dispatcher', () => {
assert.ok(output.includes('bounds:'));
assert.ok(output.includes('https://example.com/test'));
assert.ok(output.includes('Drill-down commands:'));
assert.doesNotMatch(output, /No main page frame found/);
});

test('runs explicit overview command in markdown mode', async () => {
Expand Down Expand Up @@ -311,4 +314,31 @@ describe('CLI Dispatcher', () => {
]);
assert.ok(output.includes('https://example.com/styles.css'));
});

test('offers a recapture hint when a trace parses without main frame metadata', async (t) => {
const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-'));
t.after(() => rm(dir, { recursive: true, force: true }));
const file = path.join(dir, 'no-frames.json');
const tracingStarted = {
name: 'TracingStartedInBrowser',
cat: 'disabled-by-default-devtools.timeline',
ph: 'I',
pid: 1,
tid: 1,
ts: 1000,
args: { data: { frames: [] } },
};
await writeFile(file, JSON.stringify([tracingStarted]));

const args = ['node', 'trace-engine-cli', 'overview'];
const validFixture = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json');
await captureCliOutput([...args, validFixture]);

const output = await captureCliOutput([...args, file]);
assert.match(output, /^mainUrl: null$/m);
assert.match(
output,
/No main page frame found.*DevTools Performance panel.*page target session/,
);
});
});
18 changes: 18 additions & 0 deletions test/extractors/overview.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import assert from 'node:assert/strict';
import path from 'node:path';
import test, { describe } from 'node:test';
import { extractOverview } from '../../src/engine/extractors/overview.js';
import { extractShifts } from '../../src/engine/extractors/shifts.js';
import { loadTraceFromFile } from '../../src/engine/loader.js';

describe('Overview Extractor', () => {
Expand All @@ -24,6 +25,9 @@ describe('Overview Extractor', () => {
const loaded = await loadTraceFromFile(fixturePath);
const overview = extractOverview(loaded);

assert.equal(overview.coreWebVitals.cls, null);
assert.ok(overview.warnings.some((warning) => warning.includes('loading category')));
assert.ok(overview.warnings.some((warning) => warning.includes('cpu_profiler')));
assert.equal(overview.bounds.minMs, 1000);
assert.equal(overview.bounds.maxMs, 1160);
assert.equal(overview.bounds.durationMs, 160);
Expand Down Expand Up @@ -101,4 +105,18 @@ describe('Overview Extractor', () => {
worstClusterScore: 0.15,
});
});

test('reports zero CLS without capture warnings for a recording without navigation', async () => {
const fixture = path.resolve(import.meta.dirname, '../fixtures/wrapped-trace.json');
const loaded = await loadTraceFromFile(fixture);

const overview = extractOverview(loaded);
assert.equal(overview.navigationStartMs, null);
assert.equal(overview.coreWebVitals.cls?.value, 0);
assert.doesNotMatch(overview.warnings.join(' '), /loading category/);

const shifts = extractShifts(loaded);
assert.deepEqual(shifts.clusters, []);
assert.equal(shifts.warnings, undefined);
});
});
3 changes: 2 additions & 1 deletion test/extractors/shifts.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,13 @@ import { extractShifts } from '../../src/engine/extractors/shifts.js';
import { loadTraceFromFile } from '../../src/engine/loader.js';

describe('Layout Shifts Extractor', () => {
test('extractShifts handles empty layout shift traces gracefully', async () => {
test('extractShifts warns when the recording has no layout shift data', async () => {
const fixturePath = path.resolve(import.meta.dirname, '../fixtures/basic-trace.json');
const loaded = await loadTraceFromFile(fixturePath);

const result = extractShifts(loaded);
assert.deepEqual(result.clusters, []);
assert.match(result.warnings?.[0] ?? '', /loading category/);
});

test('extractShifts parses cluster score and culprit elements', async () => {
Expand Down
20 changes: 20 additions & 0 deletions test/loader.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
// limitations under the License.

import assert from 'node:assert/strict';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import test, { describe } from 'node:test';
import { isGzipBuffer, loadTraceFromFile, parseTraceJson } from '../src/engine/loader.js';
Expand Down Expand Up @@ -75,6 +77,24 @@ describe('Trace Loader', () => {
assert.equal(loaded.parsedTrace.data.Meta.mainFrameURL, 'https://example.com/wrapped');
});

test('loadTraceFromFile tells users how to record a trace when frame metadata is missing', async (t) => {
const dir = await mkdtemp(path.join(os.tmpdir(), 'trace-cli-'));
t.after(() => rm(dir, { recursive: true, force: true }));
const file = path.join(dir, 'browser.json');
const tracingStarted = {
name: 'TracingStartedInBrowser',
cat: 'disabled-by-default-devtools.timeline',
ph: 'I',
pid: 1,
tid: 1,
ts: 1000,
args: {},
};
await writeFile(file, JSON.stringify([tracingStarted]));

await assert.rejects(() => loadTraceFromFile(file), { message: /page target session.*scan/ });
});

test('loadTraceFromFile throws when file is missing', async () => {
await assert.rejects(() => loadTraceFromFile('/non/existent/path.json'), {
message: /Trace file not found/,
Expand Down