{"id":6025,"library":"perfetto","title":"Perfetto Python API","description":"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.","status":"active","version":"0.16.0","language":"en","source_language":"en","source_url":"https://github.com/google/perfetto","tags":["tracing","profiling","trace-analysis","performance","android","debug"],"install":[{"cmd":"pip install perfetto","lang":"bash","label":"Install core library"},{"cmd":"pip install \"perfetto[polars]\"","lang":"bash","label":"Install with Polars support (optional)"},{"cmd":"pip install pandas perfetto","lang":"bash","label":"Install with Pandas support (prerequisite for BatchTraceProcessor)"}],"dependencies":[{"reason":"Required for `BatchTraceProcessor` and converting `QueryResultIterator` to Pandas DataFrames.","package":"pandas","optional":true},{"reason":"Often implicitly required by `pandas` for DataFrame operations.","package":"numpy","optional":true},{"reason":"Optional dependency for converting `QueryResultIterator` to Polars DataFrames using `as_polars_dataframe()`.","package":"polars","optional":true}],"imports":[{"symbol":"TraceProcessor","correct":"from perfetto.trace_processor import TraceProcessor"},{"symbol":"BatchTraceProcessor","correct":"from perfetto.batch_trace_processor.api import BatchTraceProcessor"}],"quickstart":{"code":"import os\nfrom perfetto.trace_processor import TraceProcessor\n\n# NOTE: Replace 'path/to/your/trace.perfetto-trace' with an actual trace file path.\n# You can generate a sample trace using the Perfetto UI (ui.perfetto.dev) or Android systrace.\ntrace_file = os.environ.get('PERFETTO_TRACE_FILE', 'path/to/your/trace.perfetto-trace')\n\ntry:\n    # Initialize TraceProcessor with a trace file\n    with TraceProcessor(trace=trace_file) as tp:\n        print(f\"Successfully loaded trace from {trace_file}\")\n\n        # Query for slices (a common trace event type)\n        qr_it = tp.query('SELECT ts, dur, name FROM slice LIMIT 5')\n\n        print(\"\\nFirst 5 slices:\")\n        for row in qr_it:\n            print(f\"  Timestamp: {row.ts}, Duration: {row.dur}, Name: {row.name}\")\n\nexcept Exception as e:\n    print(f\"Error processing trace: {e}\")\n    print(\"Please ensure 'path/to/your/trace.perfetto-trace' exists and is a valid Perfetto trace.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=0.16.0 (Perfetto v52.0+ backend)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.16.0 (Perfetto v54.0+ backend)"},{"fix":"Adjust parsing logic for `TrackEvent` log messages to access the message under the `.message` sub-field.","message":"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.","severity":"breaking","affected_versions":">=0.16.0 (Perfetto v54.0+ backend)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure Python 3.9.1 or a later version is installed and used on ARM-based macOS systems.","message":"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.","severity":"gotcha","affected_versions":"<3.9.1 on ARM Macs"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}