The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Puppeteer’s TracingOptions control which trace categories are recorded, whether screenshots are included, how large the trace buffer is, and whether the result is saved to a file. Set options with page.tracing.start(); finish with page.tracing.stop(). Provide a path to write a file, or omit it to receive trace bytes from stop().
What Puppeteer tracing options control
The Puppeteer TracingOptions API reference, version 25.12.0, documents four options. These configure Puppeteer’s tracing API; they are not a complete list of every setting available in the lower-level Chrome DevTools Protocol tracing domain.
As an Amazon Associate I earn from qualifying purchases.
| Option | What it does | Documented behavior |
|---|---|---|
categories |
Sets trace categories to include or exclude. | An array of strings; prefix a category with - to exclude it. The reference gives -toplevel as an example, but does not provide a fixed exhaustive category list. |
path |
Chooses file output. | When set, Puppeteer writes the trace to that path. When omitted, it does not write a file, and tracing.stop() can return the trace as a Uint8Array. |
screenshots |
Controls whether screenshots are included in the trace. | Optional boolean; defaults to false. This is distinct from page.screenshot(), which captures an image separately. |
bufferSize |
Sets the trace-buffer size in kilobytes. | If unspecified or zero, the reference reports Chromium’s default as 200 MB (200,000 KB). That is the documented default, not a guarantee for every browser build or workload. |
Save a trace to a file
Start tracing before the action you want to investigate, then stop tracing after it. This example writes trace.json to the current working directory:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.tracing.start({
path: 'trace.json',
screenshots: false,
});
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
// Perform the interaction or workload you want to inspect here.
await page.tracing.stop();
} finally {
await browser.close();
}path is optional. If you need the trace in memory instead, leave it out; do not expect a file to be written in that mode.
#1 Best Overall
Choose options for the diagnostic
Keep categories focused
Use categories to include or exclude trace categories. A category prefixed with - is excluded; for example, the API reference shows -toplevel. Since the options reference does not enumerate a complete category set, check the documentation for the Puppeteer version installed in your project before relying on a particular category name.
Include screenshots only when useful
Set screenshots: true when a visual record of the page during the trace helps explain what happened. Leave it omitted or set it to false when screenshots are not relevant. For a standalone screenshot rather than screenshots embedded in a trace, use Puppeteer’s separate page.screenshot() API.
Set a buffer size only when needed
bufferSize is measured in kilobytes. The Puppeteer 25.12.0 options reference says Chromium uses a 200 MB (200,000 KB) default if the value is absent or zero. Treat that as documentation for the referenced API and Chromium default, not as a promise that every installed browser build or long-running capture will behave identically. If a trace does not contain the detail or duration you need, review the buffer setting and the categories being recorded.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteReturn trace bytes instead of writing a file
When you omit path, tracing.stop() can return the trace as a Uint8Array, which you can save, upload, or pass to another part of your application:
import { writeFile } from 'node:fs/promises';
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.tracing.start({ screenshots: false });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
const trace = await page.tracing.stop();
if (trace) {
await writeFile('trace.json', trace);
}
} finally {
await browser.close();
}The returned value is binary data, so write it as bytes rather than converting it to ordinary text. If you prefer Puppeteer to write the file directly, pass path to tracing.start() instead.
Inspect the trace in Chrome DevTools
The Puppeteer Tracing class documentation, version 25.9.0, says traces can be opened in Chrome DevTools or a timeline viewer. In Chrome, open DevTools and use the Performance panel’s load option to open the saved trace. DevTools can also record, save, and load performance traces independently of Puppeteer.
DevTools capture settings can affect capture overhead. Its documentation describes disabling JavaScript samples as one option to reduce overhead and enabling advanced paint instrumentation as an option that significantly hinders performance. Collect only the detail needed to answer the diagnostic question, and keep capture settings consistent when comparing runs; otherwise the recording setup itself changes between comparisons.
Concurrency, overhead, and reliability
- One trace per browser: The Puppeteer Tracing class reference says only one trace can be active at a time per browser. Do not start overlapping traces on separate pages in the same browser instance; finish the active trace before starting another.
- Limit capture scope: Start immediately before the navigation or interaction of interest and stop afterward. This avoids collecting unrelated activity and makes traces easier to interpret.
- Keep comparisons controlled: Use the same categories, screenshot setting, buffer configuration, workload, and DevTools capture settings across runs when comparing traces. This is practical guidance based on the documented controls and DevTools overhead tradeoffs, not a performance benchmark.
- Distinguish Puppeteer from protocol options: Chrome DevTools Protocol’s Tracing domain has its own start/end methods, transfer modes, and configuration. Those protocol-level fields are not necessarily surfaced by Puppeteer’s higher-level
TracingOptions.
Troubleshoot common tracing problems
No trace file appears
Check that you supplied a valid path in tracing.start() and that the process can write to its destination. Without path, Puppeteer does not write the trace to disk; capture and handle the bytes returned by tracing.stop() instead.
The trace does not include the expected visual frames
Trace screenshots are off by default. Set screenshots: true if screenshots inside the trace are needed. A separate call to page.screenshot() does not switch on trace screenshots.
A trace cannot be started while another is active
Only one trace can be active per browser according to the Tracing class documentation. Make sure the earlier capture has completed with tracing.stop() before starting another one in that browser.
The trace is missing useful events or is unwieldy
Review the categories supplied to categories, including any exclusions prefixed with -. Also check whether the chosen buffer setting fits the capture. The documented 200 MB default applies when bufferSize is absent or zero in the referenced API, but it is not a universal guarantee for all builds or workloads.
Recommended Free Tools
The API details do not match the installed package
The retrieved Puppeteer references are not version-aligned: the TracingOptions page reports version 25.12.0, while the Tracing class page reports 25.9.0. Confirm option behavior against the documentation for your installed Puppeteer version, especially if an upgrade or browser build change affects your workflow.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is a page screenshot rather than a performance trace, ScreenshotNeo is a website screenshot API with one GET request for a PNG, JPEG, WebP, or PDF. For example, using its documented API parameters:
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. It accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; these steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can Puppeteer capture screenshots as part of a trace?
Yes. Set screenshots: true in page.tracing.start(); the documented default is false.
What type does Puppeteer return when no trace path is set?
The TracingOptions reference says page.tracing.stop() can return the trace as a Uint8Array when no path is supplied.
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.
