Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To monitor Puppeteer performance, capture a trace around the slow page load or interaction with page.tracing.start() and page.tracing.stop(), then inspect the timeline in Chrome DevTools. Use browser DevTools to pause page JavaScript, Node’s inspector to debug the Puppeteer script, and page.metrics() for supporting measurements. These tools answer different questions: a trace shows browser work over time, while a debugger pauses code and exposes its state.
Choose the right inspection method
| Method | Use it to answer | What you get |
|---|---|---|
| Trace | What browser work happened during a slow load or interaction? | A timeline for a recorded interval that you inspect in Chrome DevTools or a timeline viewer. |
| Browser DevTools | Which page-code line is running, and what is its state? | An interactive browser debugger with breakpoints. |
| Node inspector | What is the Puppeteer automation script doing? | A debugger for the Node.js process that drives the browser. |
page.metrics() |
What summary measurements does Puppeteer report? | A key/value metrics object; its timestamps are monotonic elapsed-time values, not calendar time. |
Puppeteer describes trace capture as a way to help diagnose performance issues, not as an automatic explanation of their cause. You still need to inspect the relevant interval and determine which work corresponds to the slowdown. See the Puppeteer overview.
Capture a trace of the slow behavior
Reproduce the same page, navigation path, and interaction that exhibits the problem. Start tracing before the behavior you want to study and stop after it finishes. This runnable example writes a trace to trace.json:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.tracing.start({ path: 'trace.json' });
try {
await page.goto('https://example.com', { waitUntil: 'load' });
// Run the interaction you want to investigate here.
} finally {
await page.tracing.stop();
}
} finally {
await browser.close();
}Replace the example URL and add the relevant interaction inside the traced interval. Open trace.json in Chrome DevTools or a timeline viewer. Consult the version-matched Puppeteer Tracing class reference before relying on API details, since documentation snapshots can differ from the version installed in your project.
#1 Best Overall
Keep the capture focused
- Trace the specific load or interaction that reproduces the slowdown; unrelated activity makes the interval harder to interpret.
- Only one trace can be active per browser at a time.
- Tracing options include categories, screenshots, output path, and buffer size. The TracingOptions reference reports a Chromium default buffer of 200 MB (200,000 KB) when the buffer size is omitted or set to zero. This is a buffer configuration, not a page-speed result.
- If you omit
path, the trace is not written to disk;tracing.stop()can return it as aUint8Array.
Read the timeline as evidence, not a verdict
Find the slow user-visible interval, then examine the browser work recorded within it. The trace supplies a timeline; deciding which work dominates the interval requires interpretation. After a code or environment change, reproduce the same scenario and compare the relevant trace interval rather than assuming instrumentation itself represents an exact user-experienced duration.
Open Chrome DevTools for page-side debugging
Launch Puppeteer with devtools: true to open a DevTools panel for browser-side inspection:
Rank #2
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ devtools: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com');
await page.evaluate(() => {
debugger;
// Page-side code to inspect goes here.
});
} finally {
await browser.close();
}The debugger statement pauses page JavaScript so you can inspect it in the opened browser. The LaunchOptions reference says enabling devtools forces headless to false; this is a visible-browser debugging workflow, not a headless performance run.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsUse Node’s inspector when the automation is slow or stuck
When the issue may be in your Puppeteer script rather than the page, use Node’s inspector to pause and step through the automation code. Puppeteer’s debugging guide documents starting Node with --inspect-brk, opening chrome://inspect/#devices, and selecting inspect.
- Start your script with Node’s inspector, for example
node --inspect-brk script.js. - Open
chrome://inspect/#devicesin Chrome and select inspect for the Node target. - Set breakpoints or add a server-side
debuggerstatement, then step through the script as it controls the browser.
The Node inspector is for server-side automation code; it is distinct from the browser DevTools panel used for page JavaScript. Puppeteer’s guide also notes a Chromium limitation: page.click() cannot be run directly from the DevTools console. Put that action in the test script instead.
Add summary measurements with page.metrics()
Use page.metrics() when a summary metrics object will help supplement the timeline:
const metrics = await page.metrics();
console.log(metrics);The Page API reference specifies that timestamps in the metrics object are monotonic time in seconds since an arbitrary point in the past. They are not wall-clock times or dates. Use the trace to investigate when browser work occurred and metrics as supporting measurements; do not treat the two outputs as interchangeable.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common inspection problems
- No trace file appears: Check that you supplied a
pathtopage.tracing.start(). Without one, retrieve the trace data returned bypage.tracing.stop()rather than looking for a disk file. - Tracing cannot start: Check whether another trace is already active in the same browser. Puppeteer allows only one active trace per browser.
- The trace does not show the slowdown: The traced interval may not include the slow load or interaction. Reproduce the scenario and start tracing before the behavior begins.
- DevTools opens a visible browser: That is expected when
devtools: trueis enabled; the launch option forcesheadlesstofalse. - A page-side
debuggerstatement does not pause where expected: Confirm the browser DevTools panel is open and that the statement runs in browser code, such as apage.evaluate()callback. Use Node’s inspector for a breakpoint in the automation script. page.click()fails from the DevTools console: The Puppeteer debugging guide identifies this as a Chromium bug. Issue the click from the Puppeteer script.- A metrics timestamp looks like an odd date or is not comparable to a clock reading: It is monotonic elapsed time from an arbitrary origin, not a calendar timestamp.
Or skip the browser setup
If your goal is to obtain a clean screenshot rather than inspect a performance timeline, ScreenshotNeo returns an image or PDF from one GET request. For example, this cURL command saves a WebP screenshot; see the ScreenshotNeo API docs for options:
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status in headers. Its MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. It captures screenshots, not Puppeteer traces or interactive debugging sessions.
Sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I capture a trace without saving it to a file?
Yes. Omit the trace path and retrieve the trace data returned by page.tracing.stop() as a Uint8Array.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Can I use Puppeteer tracing and the inspector in the same investigation?
Yes. A trace records browser activity over time, while browser DevTools or Node’s inspector pauses code in a particular execution context. They can complement each other, but are not interchangeable.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
