Tracing

• Types

• Commands

• Events

Types

Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands.

class MemoryDumpConfig

Configuration for memory dump. Used only when “memory-infra” category is enabled.

class TraceConfig(record_mode=None, trace_buffer_size_in_kb=None, enable_sampling=None, enable_systrace=None, enable_argument_filter=None, included_categories=None, excluded_categories=None, synthetic_delays=None, memory_dump_config=None)

record_mode: Optional[str] = None

Controls how the trace buffer stores data. The default is recordUntilFull.

trace_buffer_size_in_kb: Optional[float] = None

Size of the trace buffer in kilobytes. If not specified or zero is passed, a default value of 200 MB would be used.

enable_sampling: Optional[bool] = None

Turns on JavaScript stack sampling.

enable_systrace: Optional[bool] = None

Turns on system tracing.

enable_argument_filter: Optional[bool] = None

Turns on argument filter.

included_categories: Optional[List[str]] = None

Included category filters.

excluded_categories: Optional[List[str]] = None

Excluded category filters.

synthetic_delays: Optional[List[str]] = None

Configuration to synthesize the delays in tracing.

memory_dump_config: Optional[MemoryDumpConfig] = None

Configuration for memory dump triggers. Used only when “memory-infra” category is enabled.

class StreamFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Data format of a trace. Can be either the legacy JSON format or the protocol buffer format. Note that the JSON format will be deprecated soon.

JSON = 'json'

PROTO = 'proto'

class StreamCompression(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Compression type to use for traces returned via streams.

NONE = 'none'

GZIP = 'gzip'

class MemoryDumpLevelOfDetail(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Details exposed when memory request explicitly declared. Keep consistent with memory_dump_request_args.h and memory_instrumentation.mojom

BACKGROUND = 'background'

LIGHT = 'light'

DETAILED = 'detailed'

class TracingBackend(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Backend type to use for tracing. chrome uses the Chrome-integrated tracing service and is supported on all platforms. system is only supported on Chrome OS and uses the Perfetto system tracing service. auto chooses system when the perfettoConfig provided to Tracing.start specifies at least one non-Chrome data source; otherwise uses chrome.

AUTO = 'auto'

CHROME = 'chrome'

SYSTEM = 'system'

Commands

Each command is a generator function. The return type Generator[x, y, z] indicates that the generator yields arguments of type x, it must be resumed with an argument of type y, and it returns type z. In this library, types x and y are the same for all commands, and z is the return type you should pay attention to. For more information, see Getting Started: Commands.

end()

Stop trace events collection.

Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

get_categories()

Gets supported tracing categories.

EXPERIMENTAL

Return type:

Generator[Dict[str, Any], Dict[str, Any], List[str]]

Returns:

A list of supported tracing categories.

record_clock_sync_marker(sync_id)

Record a clock sync marker in the trace.

EXPERIMENTAL

Parameters:

sync_id (str) – The ID of this clock sync marker

Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

request_memory_dump(deterministic=None, level_of_detail=None)

Request a global memory dump.

EXPERIMENTAL

Parameters:

• deterministic (Optional[bool]) – (Optional) Enables more deterministic results by forcing garbage collection

• level_of_detail (Optional[MemoryDumpLevelOfDetail]) – (Optional) Specifies level of details in memory dump. Defaults to “detailed”.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[str, bool]]

Returns:

A tuple with the following items:

0. dumpGuid - GUID of the resulting global memory dump.

1. success - True iff the global memory dump succeeded.

start(categories=None, options=None, buffer_usage_reporting_interval=None, transfer_mode=None, stream_format=None, stream_compression=None, trace_config=None, perfetto_config=None, tracing_backend=None)

Start trace events collection.

Parameters:

• categories (Optional[str]) – (DEPRECATED) (EXPERIMENTAL) (Optional) Category/tag filter

• options (Optional[str]) – (DEPRECATED) (EXPERIMENTAL) (Optional) Tracing options

• buffer_usage_reporting_interval (Optional[float]) – (EXPERIMENTAL) (Optional) If set, the agent will issue bufferUsage events at this interval, specified in milliseconds

• transfer_mode (Optional[str]) – (Optional) Whether to report trace events as series of dataCollected events or to save trace to a stream (defaults to `ReportEvents``).

• stream_format (Optional[StreamFormat]) – (Optional) Trace data format to use. This only applies when using ``ReturnAsStream`` transfer mode (defaults to ``json``).

• stream_compression (Optional[StreamCompression]) – (EXPERIMENTAL) (Optional) Compression format to use. This only applies when using ``ReturnAsStream`` transfer mode (defaults to ``none``)

• trace_config (Optional[TraceConfig]) – (Optional)

• perfetto_config (Optional[str]) – (EXPERIMENTAL) (Optional) Base64-encoded serialized perfetto.protos.TraceConfig protobuf message When specified, the parameters ``categories``, ``options``, ``traceConfig`` are ignored. (Encoded as a base64 string when passed over JSON)

• tracing_backend (Optional[TracingBackend]) – (EXPERIMENTAL) (Optional) Backend type (defaults to ``auto`)

Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

Events

Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event’s attributes.

class BufferUsage(percent_full, event_count, value)

EXPERIMENTAL

percent_full: Optional[float]

A number in range [0..1] that indicates the used size of event buffer as a fraction of its total size.

event_count: Optional[float]

An approximate number of events in the trace log.

value: Optional[float]

A number in range [0..1] that indicates the used size of event buffer as a fraction of its total size.

class DataCollected(value)

EXPERIMENTAL

Contains a bucket of collected trace events. When tracing is stopped collected events will be sent as a sequence of dataCollected events followed by tracingComplete event.

value: List[dict]

class TracingComplete(data_loss_occurred, stream, trace_format, stream_compression)

Signals that tracing is stopped and there is no trace buffers pending flush, all data were delivered via dataCollected events.

data_loss_occurred: bool

Indicates whether some trace data is known to have been lost, e.g. because the trace ring buffer wrapped around.

stream: Optional[StreamHandle]

A handle of the stream that holds resulting trace data.

trace_format: Optional[StreamFormat]

Trace data format of returned stream.

stream_compression: Optional[StreamCompression]

Compression format of returned stream.