Trace Processor (Python)

The trace processor Python API is built on the trace procesor C++ library. By integrating with Python, the library allows using Python's rich data analysis ecosystem to process traces.

Setup

pip install perfetto

NOTE: The API is only compatible with Python3.

The main entry point to the API is the TraceProcessor class.

Example Usage

The following examples demonstrate basic usage of the Python API.

Querying Slices

This example shows how to query for slices and print their names.

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace.perfetto-trace')

qr_it = tp.query('SELECT name FROM slice')
for row in qr_it:
  print(row.name)

Output

eglSwapBuffersWithDamageKHR
onMessageReceived
queueBuffer
bufferLoad
query
...

Querying as a Pandas DataFrame

For more advanced analysis, you can convert query results to a Pandas DataFrame.

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace.perfetto-trace')

qr_it = tp.query('SELECT ts, name FROM slice')
qr_df = qr_it.as_pandas_dataframe()
print(qr_df.to_string())

Output

ts                   name
-------------------- ---------------------------
     261187017446933 eglSwapBuffersWithDamageKHR
     261187017518340 onMessageReceived
     261187020825163 queueBuffer
     261187021345235 bufferLoad
     261187121345235 query
     ...

Initialization

TraceProcessor can be initialized in a few ways depending on where the trace is and whether you want to connect to an existing trace_processor instance or start a new one.

1. With a trace file or object (starts a new trace_processor instance):

This is the most common use case. You can provide a trace in several ways:

  • A path to a trace file: TraceProcessor(trace='trace.perfetto-trace')
  • A file-like object (e.g., io.BytesIO): TraceProcessor(trace=file_obj)
  • A generator yielding bytes: TraceProcessor(trace=byte_generator)
  • A trace URI: TraceProcessor(trace='resolver_name:key=value')
from perfetto.trace_processor import TraceProcessor

# Initialise TraceProcessor with a trace file path
tp = TraceProcessor(trace='trace.perfetto-trace')

2. Connecting to a running trace_processor instance:

If you have a trace_processor instance already running (e.g. started from the command line), you can connect to it by providing its address.

# Connect to a running instance
tp = TraceProcessor(addr='localhost:9001')

# Connect to a running instance and load a new trace into it
tp = TraceProcessor(trace='trace.perfetto-trace', addr='localhost:9001')

Configuration

The TraceProcessor can be customized using the TraceProcessorConfig class.

from perfetto.trace_processor import TraceProcessor, TraceProcessorConfig

config = TraceProcessorConfig(
    bin_path='/path/to/trace_processor', # Path to custom binary
    verbose=True,
    add_sql_packages=['/path/to/my/sql/modules']
)
tp = TraceProcessor(trace='trace.perfetto-trace', config=config)

TraceProcessorConfig has many options for customizing the trace_processor instance. The most important are:

  • add_sql_packages: A list of paths to additional PerfettoSQL packages to load. All SQL modules inside these packages will be available to include using INCLUDE PERFETTO MODULE PerfettoSQL statements.
  • verbose: If True, trace_processor will print verbose output to stdout. This is useful for debugging and seeing more detailed error messages.
  • bin_path: Path to the trace_processor binary. If not given, the latest prebuilt version will be downloaded.

API

The TraceProcessor class provides various functions to interact with the loaded trace.

Query

The query() function takes an SQL query as input and returns an iterator over the result rows. For more information on how to write queries, see the Getting Started with PerfettoSQL guide.

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace.perfetto-trace')

qr_it = tp.query('SELECT ts, dur, name FROM slice')
for row in qr_it:
  print(row.ts, row.dur, row.name)

Output

261187017446933 358594 eglSwapBuffersWithDamageKHR
261187017518340 357 onMessageReceived
261187020825163 9948 queueBuffer
261187021345235 642 bufferLoad
261187121345235 153 query
...

The QueryResultIterator can also be converted to a Pandas DataFrame, which is useful for data analysis and visualization. This requires numpy and pandas to be installed.

# Requires pandas and numpy
# pip install pandas numpy
import numpy as np

qr_it = tp.query('SELECT ts, dur, name FROM slice')
qr_df = qr_it.as_pandas_dataframe()
print(qr_df.to_string())

Output

ts                   dur                  name
-------------------- -------------------- ---------------------------
     261187017446933               358594 eglSwapBuffersWithDamageKHR
     261187017518340                  357 onMessageReceived
     261187020825163                 9948 queueBuffer
     261187021345235                  642 bufferLoad
     261187121345235                  153 query
     ...

You can use Pandas DataFrames to easily create visualizations from trace data.

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace.perfetto-trace')

qr_it = tp.query('SELECT ts, value FROM counter WHERE track_id=50')
qr_df = qr_it.as_pandas_dataframe()
qr_df = qr_df.replace(np.nan,0)
qr_df = qr_df.set_index('ts')['value'].plot()

Output

Graph made from the query results

Trace Summary

The trace_summary() function computes a structured summary of the trace. This is useful for creating structured protobuf messages for consumption by other tools. This function is the replacement for the deprecated metric() function.

See the Trace Summarization docs for a deep dive into this feature.

from perfetto.trace_processor import TraceProcessor

spec = """
metric_spec {
  id: "memory_per_process"
  dimensions: "process_name"
  value: "avg_rss_and_swap"
  query: {
    table: {
      table_name: "memory_rss_and_swap_per_process"
      module_name: "linux.memory.process"
    }
    group_by: {
      column_names: "process_name"
      aggregates: {
        column_name: "rss_and_swap"
        op: DURATION_WEIGHTED_MEAN
        result_column_name: "avg_rss_and_swap"
      }
    }
  }
}
"""
with TraceProcessor(trace='trace.perfetto-trace') as tp:
    summary = tp.trace_summary(specs=[spec])
    print(summary)

Metatracing

Metatracing allows you to trace the performance of trace_processor itself.

# Enable metatracing
tp.enable_metatrace()

# Run some queries
tp.query('select * from slice')
tp.query('select * from slice')

# Disable and read the metatrace
metatrace_bytes = tp.disable_and_read_metatrace()

# You can now load this into another TraceProcessor instance
with open('tp_metatrace.pftrace', 'wb') as f:
    f.write(metatrace_bytes)
tp_meta = TraceProcessor(trace='tp_metatrace.pftrace')
tp_meta.query('select * from slice')

Metric (Deprecated)

The metric() function takes in a list of trace metrics and returns the results as a Protobuf.

Note: this function is deprecated but there are no plans to remove it. Consider using trace_summary() instead, which is an indirect replacement, providing much of the same functionality but in a more flexible way.

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace.perfetto-trace')

ad_cpu_metrics = tp.metric(['android_cpu'])
print(ad_cpu_metrics)

Output

metrics {
  android_cpu {
    process_info {
      name: "/system/bin/init"
      threads {
        name: "init"
        core {
          id: 1
          metrics {
            mcycles: 1
            runtime_ns: 570365
            min_freq_khz: 1900800
            max_freq_khz: 1900800
            avg_freq_khz: 1902017
          }
        }
        core {
          id: 3
          metrics {
            mcycles: 0
            runtime_ns: 366406
            min_freq_khz: 1900800
            max_freq_khz: 1900800
            avg_freq_khz: 1902908
          }
        }
        ...
      }
      ...
    }
    process_info {
      name: "/system/bin/logd"
      threads {
        name: "logd.writer"
        core {
          id: 0
          metrics {
            mcycles: 8
            runtime_ns: 33842357
            min_freq_khz: 595200
            max_freq_khz: 1900800
            avg_freq_khz: 1891825
          }
        }
        core {
          id: 1
          metrics {
            mcycles: 9
            runtime_ns: 36019300
            min_freq_khz: 1171200
            max_freq_khz: 1900800
            avg_freq_khz: 1887969
          }
        }
        ...
      }
      ...
    }
    ...
  }
}