This is the fourth article in the Perfetto series. It explains how to use trace_processor_shell to open large trace files (often exceeding 2GB). In practice, we frequently encounter massive traces that the browser-based ui.perfetto.dev cannot open due to browser memory constraints. To solve this, we use the official trace_processor_shell tool to power the analysis from your local machine.
Table of Contents
- Perfetto Series Catalog
- 0. Downloading trace_processor_shell
- 1. Using trace_processor_shell for Large Files
- 2. CLI Mode vs. Browser WASM Mode
- 3. Mac Permissions Issues
- Reference Documents
Paul Graham once said: “Either provide something most people want a little, or something a few people want a lot.“ Perfetto is exactly what a dedicated minority “wants a lot.” Let’s begin.
This series aims to provide a fresh perspective on Android system operation through Perfetto. It offers a unique angle to study App, Framework, and Linux internals. Through graphical tools like Perfetto, you may gain much deeper insights.
Perfetto Series Catalog
- Android Perfetto Series Catalog
- Android Perfetto Series 1: Introduction to Perfetto
- Android Perfetto Series 2: Capturing Perfetto Traces
- Android Perfetto Series 3: Familiarizing with the Perfetto View
- Android Perfetto Series 4: Opening Large Traces via Command Line
- Android Perfetto Series 5: Choreographer-based Rendering Flow
- Android Perfetto Series 6: Why 120Hz? Advantages and Challenges
- Android Perfetto Series 7: MainThread and RenderThread Deep Dive
- Android Perfetto Series 8: Understanding Vsync and Performance Analysis
- Android Perfetto Series 9: Interpreting CPU Information
- Video (Bilibili) - Android Perfetto Basics and Case Studies
0. Downloading trace_processor_shell
Official download link: Perfetto GitHub Releases. Find the latest release and download the binary corresponding to your platform.
Once downloaded, you will find the trace_processor_shell utility inside.
trace_processor_shell is the core engine of the Perfetto project. By starting it as an HTTP server with the --httpd flag, it enables:
- Native Hardware Acceleration: Bypasses the performance overhead of browser WebAssembly (WASM) by using a high-performance C++/Rust parsing engine locally. It supports streaming large files and parallel processing.
- Interactive Analysis: Deeply integrates with the Perfetto UI for dynamic queries and visualization.
- Offline & Private Debugging: No need to upload traces to the cloud; everything remains on your local machine.
Additional CLI Flags
| Flag | Description | Example |
|---|---|---|
--httpd |
Starts the HTTP server | --httpd |
--http-port |
Specifies the listening port | --http-port :8080 |
--preload |
Preloads common data tables | --preload sched |
--num-threads |
Sets parsing threads (defaults to CPU count) | --num-threads 8 |
1. Using trace_processor_shell for Large Files
Run the following command (adjust paths as necessary):
1 | ./trace_processor_shell --httpd ./my_huge_trace.perfetto-trace |
Now, when you open ui.perfetto.dev, you will see a prompt:
Prompt Options Explained:
YES, use loaded trace- Effect: Uses the trace file already loaded by your CLI command.
- Use Case: This is the fastest way to start analyzing the file you just specified in the command line. It reuses any existing SQL state or filters you’ve applied.
YES, but reset state- Effect: Forces the local engine to re-parse the file from scratch.
- Use Case: Use this if you want to clear temporary SQL tables or filters to start fresh, or if you’ve swapped files on the same port.
NO, Use builtin WASM- Effect: Completely bypasses the local engine and relies on the browser’s internal WASM engine.
- Use Case: Only use this if the local service is failing. For large files (>100MB), this will be significantly slower and may crash.
Note: When using the local engine (YES, use loaded trace), certain web-only features like “Share” or “Download” might be unavailable because the data is hosted locally.
2. CLI Mode vs. Browser UI Mode
CLI-Assisted Mode (trace_processor_shell --httpd)
- Mechanism: Local high-performance C++ server listening on
127.0.0.1:9001. - Pros:
- Blazing Fast: Native code is much faster than WASM for parsing large traces.
- Advanced Features: Full support for SQL queries and custom metric calculations.
- State Persistence: Parsing states can persist across browser sessions.
- Cons: Cannot easily share the resulting link with others.
Pure Browser Mode (ui.perfetto.dev)
- Mechanism: Relies entirely on the browser’s WebAssembly engine.
- Pros:
- Convenience: No installation required; great for quickly checking small traces.
- Collaboration: Supports sharing links and downloading edited traces.
- Cons: Often crashes with large files and lacks performance for heavy SQL analysis.
3. Mac Permissions Issues
On macOS, running ./trace_processor_shell for the first time often triggers an “unverified developer” warning.
Go to System Settings -> Privacy & Security, scroll down, and click “Allow Anyway” to permit the tool to run.
Summary
When dealing with large traces or requiring complex analysis, always prefer the trace_processor_shell --httpd method for better performance and reliability. For light, one-off checks, the browser’s built-in engine is sufficient.
“If you want to go fast, go alone. If you want to go far, go together.”
