Android Perfetto Series 4: Opening Large Traces via Command Line

Word count: 1.9kReading time: 11 min

 2025/02/08

This is the fourth article in the Perfetto series, explaining how to use trace_processor_shell to open large files exceeding 2GB locally. In actual problem analysis, we often encounter very large Trace files (greater than 2GB) that may fail to open in ui.perfetto.dev because of browser memory limits. The limit applies to memory used while parsing, not directly to the trace file’s size. In this case, we can use the official trace_processor_shell tool to open large files locally.

When I started this series, Perfetto had largely replaced Systrace in my daily work, and the OPPO and vivo teams I encountered were also migrating. Newcomers found the interface overwhelming and asked me to explain the subjects of my Systrace articles through Perfetto.

Version note (reviewed October 2026): The original screenshots use v49’s trace_processor_shell. The official trace_processor wrapper currently selects v58.2; commands are checked against that release, with UI behavior checked against v58.3 source. server http is the current subcommand form; legacy --httpd remains supported. A binary named trace_processor_shell is not inherently obsolete. See both forms below and series 11 for more SQL usage.

Perfetto Series Catalog
0. trace_processor_shell Tool Download
1. Using trace_processor_shell to Open Large Trace Files
2. Difference Between Command Line Startup and Direct UI Opening
3. Mac Permission Issues
Reference Documents
About Me && Blog

Paul Graham said: “Either give a lot of people something they kind of want, or give a small number of people something they really want.“ Perfetto is actually something that a small number of people really want, so let’s start writing. Please join the discussion. If you spot an error or an unclear explanation, let me know so I can fix it before it misleads someone.

In this series, I want to use Perfetto to look at how apps, the Framework, and Linux work together. If you have read plenty of source code and performance articles but still find the flow hard to follow, try placing that code on a trace timeline.

Perfetto Series Catalog

If you haven’t seen the Systrace series yet, here is the portal:

Systrace Series Catalog: Systematically introduced the use of Systrace, the predecessor of Perfetto, and used Systrace to learn and understand the basic rules of Android performance optimization and Android system operation.
Personal Blog: Personal blog, mainly content related to Android, and also put some content related to life and work.

Welcome everyone to find ways to get in touch on the About Me page to discuss your problems, the parts about Perfetto you most want to see, and discuss all Android development related content with group friends.

0. trace_processor_shell Tool Download

Download a matching host OS/architecture package from official Releases, for example mac-arm64 on Apple Silicon. These are historical v49 screenshots; use the selected release’s actual assets. An Android device package is not a macOS/Linux host executable.

On macOS/Linux, the official Python 3 wrapper is another option and requires curl. It downloads and verifies the manifest-selected native binary on first use, then uses its cache. The wrapper pins a build rather than fetching an arbitrary new binary on every invocation; record --version. Run these commands in your tools directory:

1
2
3

curl -fLO https://get.perfetto.dev/trace_processor
chmod +x ./trace_processor
./trace_processor --version

The native Trace Processor parses the trace and the UI queries it over local RPC. This bypasses the browser engine’s memory ceiling, but not host RAM/address-space limits or query intermediates; streaming input does not make memory unlimited. Normal local opening does not upload the trace. Fully offline use also requires a prepared binary and an offline-ready or locally hosted UI.

Keep the v58.2 command forms separate:

Purpose	Subcommand form	Legacy flat flags
HTTP service	`server http --port 9001 "trace.pftrace"`	`--httpd --http-port 9001 "trace.pftrace"`
SQL file	`query -f query.sql "trace.pftrace"`	`-q query.sql "trace.pftrace"`
Full sorting	Global `--full-sort`	`--full-sort`

Prefix these with ./trace_processor or the native executable name. Do not copy legacy -q into query, which uses -f/--query-file. Full sorting may raise peak memory usage; it is not a general large-file acceleration switch. A custom port also requires matching UI rpc_port and connection policy. Default 9001 is the simplest path. See the large-trace guide and CLI reference.

1. Using trace_processor_shell to Open Large Trace Files

With the wrapper, use the current form below. Replace the quoted path with your trace and keep the server running while the browser queries it:

1	./trace_processor server http "../trace-file.perfetto-trace"

For the historical v49 package, use the legacy form below. Choose one invocation; do not start both on the default port:

1	./trace_processor_shell --httpd "../trace-file.perfetto-trace"

The original terminal screenshot actually shows Address already in use for both IPv4 and IPv6 on port 9001. It does not prove that this process started successfully. If your existing processor is intentional, connect and verify its loaded trace; otherwise stop only your unneeded instance before retrying.

Once loading and listening succeed, open Perfetto UI. It probes local port 9001 and queries over WebSocket RPC. A version mismatch may first prompt a matching UI or a tool update. If detection fails, check server errors, port selection, and browser local-network access restrictions. The preloaded-trace dialog below is historical and will not appear in every situation:

Pop-up Options

1. `YES, use loaded trace`

Reuse the trace already parsed by the server, avoiding another file import. This does not restore all previous filters, selections, notes, or SQL objects. The v58.3 UI preload path calls restoreInitialTables() to restore the initial SQL environment before UI initialization. Parsed data is reused, not a complete prior analysis session.

2. `YES, but reset state`

Keep the local accelerator and open another trace through the UI; this does not automatically reload the original command-line file. In v58.3, choosing the button does not restart the process. Importing new data after the previous trace’s EOF resets the parser. A different trace does not inherently require a new process or port, but replaces the old parsed state.

Use one active trace/UI client per service to avoid another tab’s reset or queries interfering with your analysis.

3. `NO, Use builtin WASM`

This tab uses the built-in WASM engine and needs a file/source supplied through the UI. It neither transfers the server’s parsed state into the browser nor stops the server. Both engines support SQL.

The historical screenshot below shows download/conversion limits for a preloaded RPC trace. In v58.3, availability depends on whether the UI has a downloadable original source: pure HTTP_RPC preload has no file bytes, whereas a UI-opened file is a different source. The restriction is not universal to every native-engine use. Downloading the original trace also does not write filters or SQL results into a “modified trace.” Sharing depends on source/deployment and may upload data or state; choosing WASM does not guarantee every collaboration feature. See the loading implementation.

2. Difference Between Command Line Startup and Direct UI Opening

Startup via Command Line (`trace_processor_shell --httpd`)

The native process performs parsing and SQL, listening on localhost:9001 by default (the UI probes 127.0.0.1:9001). The browser still renders the interface and consumes memory. Native processing is often a better fit for large traces, but duration depends on the data, host resources, and queries.

Loaded data can be reused while the server lives. Process exit, another import, or UI SQL initialization changes what remains available. Save important SQL scripts and original files instead of relying on temporary tables surviving across pages. A preloaded RPC source has the download/conversion limits described above.

Directly Open UI Web Page (`ui.perfetto.dev`)

This means opening a file with the built-in WASM engine. The same webpage can connect to a native server, so webpage access and command-line startup are not separate, mutually exclusive UIs.

WASM needs no additional server process and also supports PerfettoSQL and visualization. Normal local opening does not require uploading. Download/sharing capabilities depend on source and deployment. Runtime memory differs from file size: 2 GB is a historical reference for common limits, not a universal browser file threshold. Parsed data, query results, and the UI all consume memory. Without a same-trace measurement, do not assume WASM is always slower.

Summary and Suggestions

Try native processing when browser-engine memory limits block a large import. WASM is convenient for routine analysis. If the native process also runs out of memory, investigate import/query costs or narrow future recording scope and duration; a different command does not make every trace fit.

3. Mac Permission Issues

A downloaded executable may trigger Gatekeeper. This is a historical v49-era alert, not an error every Mac must show. Distinguish unidentified/unnotarized software from damage/malware alerts, missing executable permission, and an architecture mismatch.

For a verified official file you trust, Apple’s instructions are to attempt opening it, then use System Settings → Privacy & Security → Open Anyway and confirm the next prompt. Older screenshots may use different wording. This is a per-file exception, not a requirement to disable system protection. Damage or malware alerts require checking the official source instead of applying this step indiscriminately.

Reference Documents

About Me && Blog

Here is a personal introduction and related links. I hope to communicate more with my peers. When three people walk together, there must be one who can be my teacher!