Implementation:Puppeteer Puppeteer Cdp Tracing

Property	Value
sources	packages/puppeteer-core/src/cdp/Tracing.ts
domains	CDP, Performance, Tracing
last_updated	2026-02-12 00:00 GMT

Overview

Description

The Tracing class exposes Chrome's tracing audit interface through the Chrome DevTools Protocol. It provides start() and stop() methods to capture performance traces that can be opened in Chrome DevTools or the Timeline Viewer.

Key behaviors:

• start() -- Begins a trace with configurable categories. By default, it enables a comprehensive set of tracing categories including devtools.timeline, v8.execute, blink.console, latencyInfo, and CPU profiler categories. Optionally captures screenshots via disabled-by-default-devtools.screenshot. Categories prefixed with - are treated as exclusions. Only one trace can be active per browser at a time.
• stop() -- Ends the trace and retrieves the trace data as a stream via the Tracing.tracingComplete event. The stream is read using getReadableFromProtocolStream and converted to a Uint8Array. If a file path was specified in the start options, the data is also written to disk.
• updateClient() -- Allows updating the CDP session reference, used when sessions are swapped (e.g., during OOPIF adoption).

Usage

The Tracing class is accessible via page.tracing and is used for performance profiling during automated testing or analysis.

Code Reference

Source Location

packages/puppeteer-core/src/cdp/Tracing.ts (140 lines)

Signature

export interface TracingOptions {
  path?: string;
  screenshots?: boolean;
  categories?: string[];
}

export class Tracing {
  constructor(client: CDPSession);
  updateClient(client: CDPSession): void;
  async start(options?: TracingOptions): Promise<void>;
  async stop(): Promise<Uint8Array | undefined>;
}

Import

import { Tracing } from '../cdp/Tracing.js';
import type { TracingOptions } from '../cdp/Tracing.js';

I/O Contract

start

Direction	Name	Type	Description
Input	options.path	undefined	File path to save the trace data to
Input	options.screenshots	undefined	If true, captures screenshots during the trace (default: false)
Input	options.categories	undefined	Trace categories to enable; categories prefixed with - are excluded
Output	result	Promise<void>	Resolves when tracing has started
Error	AssertionError	Error	Thrown if a trace is already recording

stop

Direction	Name	Type	Description
Output	result	undefined>	The trace data as a binary buffer, or undefined if no data

Default trace categories

Category	Description
-*	Exclude all categories by default
devtools.timeline	DevTools timeline events
v8.execute	V8 script execution
disabled-by-default-devtools.timeline	Extended timeline data
disabled-by-default-devtools.timeline.frame	Frame timing data
toplevel	Top-level task scheduling
blink.console	Console API calls
blink.user_timing	User Timing API marks and measures
latencyInfo	Input latency information
disabled-by-default-devtools.timeline.stack	Stack traces in timeline
disabled-by-default-v8.cpu_profiler	CPU profiler data

Usage Examples

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Basic tracing with file output
await page.tracing.start({ path: 'trace.json' });
await page.goto('https://www.example.com');
await page.tracing.stop();

// Tracing with screenshots
await page.tracing.start({
  path: 'trace-with-screenshots.json',
  screenshots: true,
});
await page.goto('https://www.example.com');
await page.tracing.stop();

// Tracing with custom categories
await page.tracing.start({
  categories: ['devtools.timeline', 'v8.execute'],
});
await page.goto('https://www.example.com');
const traceBuffer = await page.tracing.stop();
// traceBuffer is a Uint8Array containing the trace data

// Get trace data as a string
if (traceBuffer) {
  const traceJson = new TextDecoder().decode(traceBuffer);
  const traceData = JSON.parse(traceJson);
  console.log('Trace events:', traceData.traceEvents.length);
}

await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime