Puppeteer Tracing Options: What They Do and How to Use Them

Puppeteer tracing records browser activity for a page so you can inspect what happened during navigation or another sequence of actions. Start a trace with page.tracing.start(options), perform the activity you want to investigate, then call page.tracing.stop(). The four documented options are bufferSize, categories, path, and screenshots. Only one trace can be active per browser.

1. What the Puppeteer tracing options do

Pass a TracingOptions object to page.tracing.start(). Each option controls what Chromium records or where Puppeteer returns the result.

Option	What it controls	When to use it
`bufferSize`	Trace buffer size in kilobytes. Omitted or zero uses Chromium’s documented default of 200 MB (200,000 KB).	Change it only when you have a specific reason to adjust the trace buffer. It does not set or guarantee the output file size.
`categories`	Array of tracing category strings to include or exclude.	Use it to shape the events captured for an investigation. Prefix a category with `-` to exclude it, such as `-toplevel`.
`path`	File path where Puppeteer writes trace output.	Set it when you want a trace file for later inspection or sharing. Omit it to retrieve the trace data from `stop()`.
`screenshots`	Whether screenshots are captured in the trace. Defaults to `false`.	Enable it when visual snapshots help explain what was on screen during the trace.

The documented 200 MB value is Chromium’s default trace-buffer size, not a recommended setting or an output-size estimate. The options reference documents no numeric performance cost for screenshots.

2. Record a trace to a file

This runnable Node.js example starts Chrome through Puppeteer, records navigation and an interaction, and writes trace.json in the current directory.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();

    await page.tracing.start({
      path: 'trace.json',
      screenshots: true,
    });

    await page.goto('https://example.com', {
      waitUntil: 'networkidle2',
    });
    await page.locator('a').click();

    await page.tracing.stop();
    console.log('Trace written to trace.json');
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Replace the navigation and interaction with the activity whose behavior you need to inspect. Start tracing before that activity and stop after it. Puppeteer’s documented workflow uses this start, page activity, and stop sequence. Open the resulting trace in Chrome DevTools or a compatible timeline viewer.

3. Retrieve trace data in memory

When you omit path, stop() can return the trace data as a Uint8Array. This is useful when another part of your program will store or process the data.

const puppeteer = require('puppeteer');
const fs = require('node:fs/promises');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();

    await page.tracing.start({ screenshots: false });
    await page.goto('https://example.com', { waitUntil: 'load' });

    const trace = await page.tracing.stop();
    if (!trace) {
      throw new Error('Puppeteer did not return trace data');
    }
    await fs.writeFile('trace.json', trace);
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The API return type is Promise<Uint8Array | undefined>. Handle the possibility that no data is returned, as in the example, instead of assuming a value is always present. If you provide path, use that file output path rather than relying on an in-memory result.

4. Choose categories and buffer settings

Categories let you control which tracing events are included or excluded. An excluded category uses a leading hyphen. For example:

await page.tracing.start({
  path: 'focused-trace.json',
  categories: ['-toplevel'],
});

That snippet demonstrates the exclusion syntax; choose categories that fit your investigation. If you omit categories, Puppeteer uses categories specified by its implementation. The exact defaults can depend on the Puppeteer version, so check the implementation for the version installed in your project rather than assuming a fixed list.

In most investigations, begin with the default buffer behavior. If you set bufferSize, its unit is kilobytes:

await page.tracing.start({
  path: 'trace.json',
  bufferSize: 50000, // kilobytes
});

Omitting the setting or using zero selects Chromium’s documented default of 200 MB (200,000 KB). A buffer is not a maximum trace-file size guarantee. Avoid choosing a value based on an assumed relationship between buffer size and file size.

5. Screenshots, output paths, and the one-trace limit

Trace screenshots: screenshots defaults to false. Turn it on when correlating visual changes with events matters. The reference does not quantify the resulting overhead or trace growth.
File output: Set path to write a trace to disk. Make sure the process can write to that location and that the parent directory exists.
In-memory output: Omit path, await page.tracing.stop(), and handle the returned Uint8Array or undefined.
One active trace: Only one trace can be active per browser, including when that browser has multiple pages. Coordinate tracing across pages or use separate browser instances for independent concurrent traces.

6. A practical tracing workflow

Decide which page behavior you need to inspect: navigation, an interaction, or a sequence of both.
Choose file output with path or in-memory output without it.
Start with default categories and buffer settings unless you have a reason to customize them. Enable trace screenshots only if visual context is useful.
Start tracing immediately before the relevant activity. Avoid including unrelated setup if it makes the trace harder to interpret.
Perform the representative page activity, then call stop() and await completion.
Open the trace in Chrome DevTools or a timeline viewer and inspect the captured sequence.
Keep the trace and the exact Puppeteer version together when sharing or comparing results, because the default categories may vary by implementation version.

7. Troubleshooting Puppeteer tracing

Symptom	Likely cause	Fix
Starting a trace fails while another page is tracing.	A trace is already active in the same browser. The limit applies across pages.	Stop the existing trace before starting another, coordinate trace ownership, or use another browser instance for a separate concurrent trace.
No trace file appears.	`path` was omitted, the path is wrong, or the process cannot write to the destination.	Set an explicit writable path and check that its parent directory exists. If you intentionally omitted `path`, capture the value returned by `stop()` and write it yourself.
The in-memory result is missing.	The stop result is allowed to be `undefined`, or file output was configured instead.	Check the result before using it; omit `path` when you want to retrieve trace data from `stop()`.
The trace does not contain the events expected.	The selected categories exclude the relevant events, or the assumed defaults differ from the installed version.	Review the category strings and exclusions, then check the Puppeteer implementation for the installed version’s defaults.
The trace has no visual snapshots.	`screenshots` defaults to `false`.	Set `screenshots: true` before starting the trace and repeat the relevant activity.
The trace file is unexpectedly large or truncated.	Captured activity and buffer behavior affect trace collection; `bufferSize` is not an output-file size control.	Narrow the recorded activity or categories as appropriate. Do not infer an output-size guarantee from the buffer setting.

8. Performance, reliability, and cost considerations

Tracing adds a recording step to the browser workflow, but the cited API references do not provide a quantified runtime overhead or a benchmark. Screenshot capture in the trace is optional and off by default; the documentation does not state a numeric overhead or size increase, so measure it in your own workload if those constraints matter.

For reliable capture, await both start and stop, keep the trace window limited to the behavior under investigation, and ensure the browser is closed even if navigation or an interaction throws. Use a writable output path or check the in-memory return before saving it. The buffer setting does not promise a particular trace-file size.

Puppeteer tracing itself has no per-trace price described by the cited documentation; operational costs depend on the browser environment and storage you use. If your goal is simply to obtain a screenshot rather than diagnose browser events, tracing is unnecessary.

9. Or skip the browser setup

If you need the screenshot rather than a Chromium trace, ScreenshotNeo returns an image or PDF from one API request. See the API documentation. For example, using cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

10. FAQ

Can I trace two pages in the same browser at once?

No. Puppeteer permits only one active trace per browser, even if the pages are different.

Does `bufferSize` limit the saved JSON file?

No. It configures the trace buffer in kilobytes; it is not an output-file size guarantee.

Are tracing screenshots enabled by default?

No. The screenshots option defaults to false.

Where can I inspect a trace?

Open the trace in Chrome DevTools or a timeline viewer.