Perfetto Documentation

Perfetto UI provides a stable command surface designed specifically for automation. Unlike internal UI commands, these stable commands have backwards compatibility guarantees and are intended for use in:

• Startup commands: Automatically configuring the UI state when a trace is loaded.
• Macros: Creating reusable workflows for complex analysis tasks.
• Deep linking: Sharing pre-configured views via URLs or postMessage.

Commands not listed in the automation reference are considered internal implementation details and may change without notice.

The Data Explorer is an interactive tool for exploring trace data using a visual pipeline approach instead of writing manual SQL. You build analysis by connecting nodes on a canvas, starting from a data source and chaining operations like filters, aggregations, and joins.

Key capabilities include:

• No SQL required: Use visual nodes to perform complex operations like joins or conditional expressions.
• Trace-specific operations: Specialized support for intersecting time intervals and pairing start/end events.
• Live results: See data updates in real-time in an interactive data grid.
• Visualizations: Attach Charts nodes to create graphs or dashboards.
• Persistence: Save and share query graphs as JSON files or via permalinks.

Bigtrace is a tool designed to process millions of traces by distributing TraceProcessor instances across a Kubernetes cluster. The architecture consists of four main components:

• Client: Interfaces for interacting with Bigtrace. Supported clients include a Python API (part of the Perfetto python library), clickhouse-client (CLI for SQL queries via gRPC), and Apache Superset (GUI for SQL and visualization).
• Orchestrator: The central component that shards traces to Worker pods and streams results back to the Client.
• Worker: Individual pods running an instance of TraceProcessor to execute queries on specific traces.
• Object Store (GCS): Stores the traces queried by the service. Currently supports Google Cloud Storage (GCS) or local traces for testing.

PerfettoSQL is a SQL dialect used to query trace contents as if they were a database. It is interpreted by the Trace Processor engine and allows for programmatic data extraction. You can use PerfettoSQL to:

• Extract performance data from traces.
• Create custom visualizations (Debug tracks) for complex analyses.
• Create derived metrics.
• Identify performance bottlenecks using data-driven logic.

The perfetto-sdk provides safe and ergonomic Rust bindings for the Perfetto tracing framework. Key capabilities include:

• Track events: Record events using categories, names, and typed arguments.
• Data sources: Implement custom trace data sources.
• Protozero encoding: Uses pure Rust encoding for minimal overhead.
• Tracing sessions: Programmatically manage trace collection sessions.

Perfetto's Protobuf definitions are organized into three distinct functional groups depending on whether they represent trace output, configuration input, or inter-process communication:

• trace/: Contains all Protobuf definitions that are output by Perfetto during trace capture.
• config/: Contains configuration definitions used as input, including:
  • The global trace configuration sent by a Consumer to the Perfetto trace daemon.
  • Per-data-source configurations relayed by the trace daemon to Producers.
  • Per-data-source descriptors advertised by Producers when registering with the trace daemon.
• ipc/: Defines the IPC (Inter-Process Communication) surface between Perfetto components (Producers, trace daemon, and Consumers). This is primarily relevant for specific build configurations, such as Android, and is not used in Chrome.

Native heap profiling intercepts malloc/free calls to track the callstack of memory that has been allocated but not yet freed. This allows you to identify the 'code origin' of memory usage.

Important Constraints:

• Platform Support: Only works on Android and Linux.
• Non-Retroactive: Profiling only reports allocations that occur after the trace has started. To capture startup allocations, you must begin tracing before the process is launched.
• Overhead Mitigation: Supports sampling to trade off accuracy for lower performance overhead.

The Perfetto Tracing Protocol ABI is a binary-stable interface that allows processes to contribute tracing data to the tracing service. It consists of three main components:

1. Socket protocol: A SOCK_STREAM UNIX socket interface for communication.
2. Shared memory layout (SMB): A high-performance staging area for asynchronous data writes.
3. Protobuf messages: The data contract used for all communication.

The ABI is designed for backward and forward compatibility and has remained stable since Android 9.