The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Puppeteer tracing records browser activity for the current page. Call page.tracing.start() with the options you need, perform the actions you want to inspect, and finish with page.tracing.stop(). The four documented options are bufferSize, categories, path, and screenshots. Only one trace can be active per browser.
What Puppeteer tracing options control
Tracing captures diagnostic events that you can inspect in Chrome DevTools or a timeline viewer. The options determine the trace buffer, included event categories, output destination, and whether screenshots are captured along with the trace. See the Puppeteer TracingOptions reference for the option definitions.
| Option | What it does | When to use it |
|---|---|---|
bufferSize |
Sets the trace buffer size in kilobytes. When omitted or set to zero, the reference reports Chromium’s default as 200 MB (200,000 KB). | Change it only when you have a specific reason to alter the trace buffer; it does not guarantee an output-file size. |
categories |
Specifies tracing categories to include or exclude. Prefix an excluded category with a hyphen, for example -toplevel. |
Use categories to focus the trace on relevant events or exclude categories that are not useful to your investigation. If omitted, Puppeteer uses the categories in its implementation; consult the implementation for the version you run. |
path |
Specifies a file path for writing the trace. | Provide it when you want a trace file. Omit it to retrieve trace data from stop() instead. |
screenshots |
Enables or disables screenshot capture in the trace. It defaults to false. |
Turn it on when visual snapshots help explain the behavior you are investigating. The reference does not quantify its effect on performance or trace size. |
The 200 MB default is the Chromium trace-buffer default reported by the Puppeteer TracingOptions reference, version 25.12.0; it is not a recommended buffer size or a promise about the size of the saved trace.
Start, capture, and stop a trace
Start tracing before the page activity you want to inspect, then stop tracing when that activity is complete. This example writes a trace to trace.json and includes screenshots:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.tracing.start({
path: 'trace.json',
screenshots: true,
});
await page.goto('https://example.com');
// Perform the interaction or page work you want to inspect here.
await page.tracing.stop();
} finally {
await browser.close();
}
})();The Page tracing documentation describes the start-and-stop workflow. Keep the trace active only for the actions under investigation; the API allows only one active trace per browser.
Choose file output or an in-memory trace
Write the trace to a file
Set path in page.tracing.start() when you want Puppeteer to write the trace to disk. After the capture, call stop() to finish writing it. For example, use path: 'trace.json' and then open the resulting trace in Chrome DevTools or a timeline viewer.
Retrieve trace data from stop()
To receive the trace data in your program instead, omit path and save the value returned by stop():
await page.tracing.start({ screenshots: false });
await page.goto('https://example.com');
const trace = await page.tracing.stop();
if (trace) {
// trace is a Uint8Array containing trace data.
// Save or process it using your application's file or storage code.
}The documented return type is Promise<Uint8Array | undefined>; the resolved value contains trace data when returned. See the Tracing.stop() reference.
Configure categories and buffer size
Include or exclude categories
Pass category strings in the categories array. A leading hyphen marks an excluded category, as in -toplevel. The categories available and Puppeteer’s defaults can depend on the implementation version, so consult the implementation used by your installed version rather than assuming a fixed default list.
await page.tracing.start({
path: 'trace.json',
categories: ['devtools.timeline', '-toplevel'],
});This illustrates the option syntax; select categories that fit your investigation. The API reference does not prescribe a universal category set.
Set a buffer size only for a reason
bufferSize is expressed in kilobytes. If omitted or zero, the Puppeteer TracingOptions reference reports Chromium’s default buffer as 200 MB (200,000 KB). A larger buffer setting is not an output-size estimate, and the documentation does not establish a generally optimal value.
Capture screenshots inside the trace
Set screenshots: true when visual snapshots are useful for correlating the page’s appearance with trace events. The default is false. The cited API reference does not quantify additional runtime cost or trace-file growth, so decide based on whether the visual context helps answer your debugging question.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Trace limits and practical considerations
- One active trace per browser: a browser cannot record multiple traces simultaneously, even if it has multiple pages. Finish the current trace before starting another. The Tracing.start() reference documents this limit.
- Keep the capture focused: start immediately before the page actions of interest and stop once they finish. This keeps the trace aligned with the question you are investigating.
- Choose output intentionally: specify
pathfor a disk file, or omit it if your program needs the returned trace data. - No documented performance benchmark: the cited references provide no benchmark or numeric estimate of screenshot-capture overhead. Do not treat a trace as a performance measurement independent of the capture configuration.
Troubleshooting tracing
A second trace will not start
Check whether another page in the same browser still has an active trace. Stop that trace with page.tracing.stop() before starting a new one; the restriction is per browser, not per page.
No trace file appears
Confirm that path was supplied to page.tracing.start() and that page.tracing.stop() completed. If you omitted path, look for the returned value from stop() instead of expecting a disk file.
The returned trace value is undefined
The API documents the return type as Uint8Array | undefined. Check that your code awaits stop() and handles the possibility of no returned buffer; use a path if your workflow requires file output.
The trace lacks screenshots
Set screenshots: true when starting the trace. Screenshot capture is disabled by default.
Recommended Free Tools
The event list differs from an example
Check the installed Puppeteer version and its tracing implementation. If you do not pass categories, Puppeteer uses implementation-defined categories; the reference does not promise the same default list for every version.
Or skip the browser setup
If your goal is a clean screenshot of a URL rather than a browser-event trace, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. Its clean-shot steps can accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request options and response details. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo to get started with the free plan.
Frequently Asked Questions
Can Puppeteer save a trace without setting a path?
Yes. Omit path and use the trace data returned by page.tracing.stop() in your program.
Does enabling screenshots have a documented numeric overhead?
No. The cited Puppeteer reference does not quantify the performance or trace-size impact.
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.
