perfetto

library0.56.0pypypi✓ verified 87d ago

The `perfetto` Python library provides APIs and bindings for Perfetto (perfetto.dev), an open-source system profiling, app tracing, and trace analysis platform. It allows users to interact with the Perfetto Trace Processor, enabling the use of Python's rich data analysis ecosystem for processing traces. Currently, the library is in an 'Alpha' development stage (v0.16.0), indicating ongoing development and potential API changes. Releases are made periodically to introduce new features and address issues.

observability devops data

pip install perfetto

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PERFETTO

perfetto

observabilitypythonv0.56.0

Install

4.3s avg

Import

664ms

Disk

137MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.56.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 4.26s

py 3.11

✓ —

✓ 4.05s

py 3.12

✓ —

✓ 3.97s

py 3.13

✓ —

✓ 4.09s

py 3.9

10/12 runs

✓ 4.96s

137MB installed

● package 137MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TraceProcessor

✓ from perfetto.trace_processor import TraceProcessor

BatchTraceProcessor

✓ from perfetto.batch_trace_processor.api import BatchTraceProcessor

This quickstart demonstrates how to initialize the `TraceProcessor` with a Perfetto trace file and query for basic slice events. It uses a `with` statement for proper resource management. Ensure you replace the placeholder trace file path with a valid Perfetto trace.

import os from perfetto.trace_processor import TraceProcessor # NOTE: Replace 'path/to/your/trace.perfetto-trace' with an actual trace file path. # You can generate a sample trace using the Perfetto UI (ui.perfetto.dev) or Android systrace. trace_file = os.environ.get('PERFETTO_TRACE_FILE', 'path/to/your/trace.perfetto-trace') try: # Initialize TraceProcessor with a trace file with TraceProcessor(trace=trace_file) as tp: print(f"Successfully loaded trace from {trace_file}") # Query for slices (a common trace event type) qr_it = tp.query('SELECT ts, dur, name FROM slice LIMIT 5') print("\nFirst 5 slices:") for row in qr_it: print(f" Timestamp: {row.ts}, Duration: {row.dur}, Name: {row.name}") except Exception as e: print(f"Error processing trace: {e}") print("Please ensure 'path/to/your/trace.perfetto-trace' exists and is a valid Perfetto trace.")

Debug

Known issues

breakingBreaking Changes in SQL Query Columns (v52.0 and v54.0): In v52.0, the `arg_set_id` column in the `thread` table may now require qualification (e.g., `thread.arg_set_id`) in queries to avoid ambiguity. In v54.0, `stack_id` and `parent_stack_id` columns were removed from the `slice` table, and related functions (`ancestor_slice_by_stack`, `descendant_slice_by_stack`) were moved to the `slices.stack` standard library module. Queries dependent on these columns will break. Additionally, `machine_id` became a non-nullable column, with the host machine consistently represented by `0` instead of `NULL`.

fix

Review SQL queries involving `thread`, `slice`, and `TrackEvent` tables. For `thread.arg_set_id`, qualify the column name. For stack IDs, migrate to functions in `slices.stack` stdlib module. Adjust queries for `machine_id` nullability. Refer to the Perfetto SQL backcompat documentation for migration guidance.

affects: >=0.16.0 (Perfetto v52.0+ backend)

breakingBreaking Changes in TraceConfig and `traced_relay` (v54.0): The `TraceConfig.no_flush_before_write_into_file` field has been removed and replaced by the `TraceConfig.write_flush_mode` enum for more granular control. For `traced_relay` users, data sources no longer match remote machine producers by default; `TraceConfig.trace_all_machines` must be explicitly set to `True` to restore previous behavior.

fix

Update `TraceConfig` usage to use `write_flush_mode`. For `traced_relay`, explicitly set `TraceConfig.trace_all_machines = True` if remote producer matching is desired.

affects: >=0.16.0 (Perfetto v54.0+ backend)

breakingBreaking Change in TrackEvent Log Message Parsing (v54.0): TrackEvent log messages are now parsed into `track_event.log_message.message` argument instead of `track_event.log_message`. This ensures `arg_set` can be converted into valid JSON.

fix

Adjust parsing logic for `TrackEvent` log messages to access the message under the `.message` sub-field.

affects: >=0.16.0 (Perfetto v54.0+ backend)

gotchaAlpha Development Status: The `perfetto` Python library is currently in 'Alpha' development status. This means its API surface, functionality, and stability are subject to change without strict backward compatibility guarantees.

fix

Be prepared for API changes and regularly check the official documentation and GitHub changelog for updates. Pin your dependency to a specific minor version if stability is critical.

affects: <1.0.0

gotchaPython Version Requirement for ARM Macs: Users on Apple Silicon (M1 or later ARM Macs) are advised to use Python 3.9.1 or higher to work around a known Python bug that can affect Perfetto's build or runtime environment.

fix

Ensure Python 3.9.1 or a later version is installed and used on ARM-based macOS systems.

affects: <3.9.1 on ARM Macs

gotchaPotential Out-of-Memory Issues with BatchTraceProcessor: When using `BatchTraceProcessor` to load multiple trace files, especially large ones, it is possible to encounter out-of-memory errors if too many traces are loaded simultaneously.

fix

Process traces in smaller batches or utilize systems with ample RAM when working with a large number of traces. Consult the documentation on managing trace loading for details.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'perfetto'

This error occurs when the 'perfetto' Python library is not installed in the environment where the Python script is being executed, or if the Python interpreter cannot locate the installed package.

fix

Install the perfetto library using pip: `pip install perfetto`

perfetto.common.exceptions.PerfettoException: Trace processor failed to start.

This error typically occurs when the Perfetto trace processor binary, which the Python library relies on, fails to initialize or start up. Common reasons include the binary taking too long to download or start, or encountering an 'exec format error' on certain systems.

fix

Increase the startup timeout for the trace processor by setting `load_timeout` in `TraceProcessorConfig` (e.g., `TraceProcessor(trace='trace.perfetto-trace', config=TraceProcessorConfig(load_timeout=10))`). Ensure there are no connectivity issues preventing the download of the pre-built binary, or specify a local `bin_path` if you have a custom-built trace processor.

TypeError: 'QueryResultIterator' object is not callable

This error happens when a user attempts to call a `QueryResultIterator` object (which is iterable, yielding rows) as if it were a function, typically by adding parentheses after retrieving it from `tp.query()`.

fix

Iterate directly over the `QueryResultIterator` or convert it to a different data structure (like a Pandas DataFrame) instead of trying to call it. Example: `for row in qr_it: print(row.ts)` or `df = qr_it.as_pandas_dataframe()`.

Upgrade

Version history

0.56.0latest on PyPI · released Jun 4, 2026

Audit

Dependencies

pandasoptionalRequired for `BatchTraceProcessor` and converting `QueryResultIterator` to Pandas DataFrames.

numpyoptionalOften implicitly required by `pandas` for DataFrame operations.

polarsoptionalOptional dependency for converting `QueryResultIterator` to Polars DataFrames using `as_polars_dataframe()`.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/google/perfetto ↗

packagehttps://pypi.org/project/perfetto/ ↗

homepagehttps://perfetto.dev/ ↗