Perfetto Python API

Warnings

• breaking Breaking 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.
• breaking Breaking 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.
• breaking Breaking 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.
• gotcha Alpha 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.
• gotcha Python 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.
• gotcha Potential 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.

Install

• pip install perfetto Install core library
• pip install "perfetto[polars]" Install with Polars support (optional)
• pip install pandas perfetto Install with Pandas support (prerequisite for BatchTraceProcessor)

Imports

• TraceProcessor

  from perfetto.trace_processor import TraceProcessor

• BatchTraceProcessor

  from perfetto.batch_trace_processor.api import BatchTraceProcessor

Quickstart

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.")