Docs
menu Home Community Trace Viewer GitHub

Trace Processor command-line reference

trace_processor loads, queries, converts, enriches, and serves traces. The native executable is built as trace_processor_shell; the downloadable trace_processor wrapper runs it with the same command-line arguments.

For installation and your first queries, see Analyzing traces from the command line. For the C++ library, see Trace Processor.

Synopsis

trace_processor <command> [flags] [positional args] trace_processor <trace_file> trace_processor help <command>

With a trace file and no command, the tool opens an interactive SQL shell. --help prints top-level help; <command> --help and help <command> print command-specific help, including the flags supported by that build.

The classic flat-flag interface (-q, -Q, --httpd, --summary, --run-metrics, -e, --stdiod) remains supported. Use --help-classic for its flags.

Global flags (apply to every subcommand)

These flags are accepted in addition to the subcommand-specific flags below and behave the same across all subcommands:

Commands

Command Purpose
query Run SQL and print results.
interactive Open a SQL prompt.
server Serve traces over RPC or manage a session.
summarize Compute trace summaries.
export Export parsed trace data.
convert Convert a trace to another format.
bundle Package a trace with symbols and deobfuscation data.
util Run low-level trace utilities.
metrics Run legacy v1 metrics.

query: run SQL

query loads a trace, runs one or more ;-separated SQL statements, prints the results to stdout, and exits. SQL can be passed as an argument, read from a file, or piped on stdin:

# Pass SQL as an argument. trace_processor query trace.pftrace "SELECT ts, dur, name FROM slice LIMIT 5" # Read SQL from a file. trace_processor query -f queries.sql trace.pftrace # Pipe SQL on stdin. cat queries.sql | trace_processor query trace.pftrace

Each statement's result set is printed as CSV, and consecutive result sets are separated by a single blank line. The separator is unambiguous because every string value is quoted.

Flags:

interactive: REPL

interactive opens the same interactive PerfettoSQL prompt described in the shell guide. It is the default subcommand, so trace_processor trace.pftrace and trace_processor interactive trace.pftrace are equivalent. The only subcommand-specific flag is -W, --wide.

server: HTTP, stdio, or unix RPC

server exposes trace processor over a remote-procedure-call protocol:

# HTTP server, used by ui.perfetto.dev. Listens on port 9001 by default. trace_processor server http # Pre-load a trace and serve it over HTTP. trace_processor server http trace.pftrace # stdio server: length-prefixed RPC for tooling that embeds # trace_processor as a subprocess. trace_processor server stdio # Named unix-socket session: keeps the trace warm for repeated # `query --remote <name>` calls (see the shell guide). trace_processor server unix --name mysession --daemonize trace.pftrace # Stop a unix session by name or socket path. trace_processor server kill mysession

Flags:

The trace file is optional in http and unix modes; clients can also load traces remotely. The most common client is the Perfetto UI, which auto-detects a local server and offloads trace parsing to it. See Visualising large traces for the end-user flow, or trace_processor.proto for the RPC wire schema.

summarize: compute trace summaries

summarize computes a trace summary. Pass the trace file first, then any spec files; select built-in v2 metrics with --metrics-v2:

# Run every available v2 metric. trace_processor summarize --metrics-v2 all trace.pftrace # Run two specific metrics defined in spec.textproto. trace_processor summarize \ --metrics-v2 startup_metric,memory_metric \ trace.pftrace spec.textproto

Flags:

Spec files are detected as binary or text by extension (.pb for binary, .textproto for text), with content sniffing as a fallback.

export: write trace data to a file

export writes the parsed trace data to a file. The format is the first positional argument, the output path is given with -o:

# Version-coupled archive, loadable by the same version of trace processor. trace_processor export perfetto -o archive.tar trace.pftrace # Static tables as standard Arrow files in a tar. trace_processor export arrow_tar -o tables.tar trace.pftrace # Static tables and views as a SQLite database. trace_processor export sqlite -o trace.db trace.pftrace

Formats:

Flags:

All three formats export the statically registered tables; only sqlite also includes views. Runtime tables created during the session (e.g. CREATE PERFETTO TABLE) are not exported. Exports stream to disk, so memory use stays bounded for large traces. For task-oriented recipes, see Export trace data.

convert: change trace format

trace_processor convert <format> [flags] [input] [output]

Formats are systrace, json, ctrace, text, profile, and firefox. Omitted input and output paths use stdin and stdout. For profile, use --output-dir instead of an output-file argument. Run help convert for format-specific options.

util: low-level trace utilities

trace_processor util <utility> [flags] [positional args]

Utilities are merge, symbolize, deobfuscate, decompress_packets, and text_to_binary. Run help util for their arguments. See the merging guide and symbolization guide for workflows.

metrics: legacy v1 metrics

Runs v1 metrics. For new workflows, use summarize --metrics-v2. Run help metrics for supported flags, and see Trace-based metrics for the legacy workflow.

bundle: enrich a trace

Synopsis

trace_processor bundle [options] <input> <output>

Produces an enriched trace containing the input trace, native symbol packets, and Java/Kotlin deobfuscation packets in a TAR archive. The Perfetto UI and Trace Processor can open this archive directly.

For prerequisites and worked examples, see the symbolization guide. Run trace_processor help bundle for the complete list of accepted flags, including common Trace Processor options.

Arguments

Argument Meaning
input Input trace file path. Stdin is not supported.
output Destination file path. Stdout is not supported. Its parent directory must exist and be writable.

Options

Native symbol paths

A symbol path is a directory containing native binaries with symbols, separate native debug files, or Breakpad symbol files. It is not a source-code directory or a ProGuard/R8 mapping file. Native binaries must match the build IDs recorded in the trace; rebuilding the same source does not necessarily produce a match.

bundle recursively indexes native binaries under the configured directories and matches them by build ID. Their directory layout and filenames need not match the paths recorded in the trace. For Breakpad, each configured directory is searched for <build-id>.breakpad (the build ID encoded as lowercase hex).

The directory list is assembled from:

  1. The comma-separated --symbol-paths argument.
  2. PERFETTO_BINARY_PATH, separated by : on POSIX or ; on Windows.
  3. Automatically discovered directories, unless --no-auto-symbol-paths is set.

Automatic directories are added in this order, when they exist:

Directory Source
/usr/lib/debug System debug files.
$HOME/.debug Per-user debug files.
$ANDROID_PRODUCT_OUT/symbols AOSP build output.
./app/build/intermediates/cmake Gradle CMake output, relative to the working directory.
./app/build/intermediates/merged_native_libs Gradle native libraries, relative to the working directory.
./.build-id Local build-ID directory, relative to the working directory.

With automatic discovery enabled, absolute Unix-style binary paths recorded in stack_profile_mapping are also considered as individual files on the host. --no-auto-symbol-paths disables both these files and the automatic directories; it does not disable PERFETTO_BINARY_PATH.

The order above describes how paths are collected, not a guaranteed preference between duplicate copies of the same build ID during recursive indexing. Prefer directories containing the matching unstripped or debug binaries rather than mixing stripped and unstripped copies. Use --verbose to inspect lookup details.

Exit status

A successfully written bundle exits with status 0, including when some symbols are unavailable. The symbolization summary reports missing symbols. Invalid arguments and failures to produce the bundle exit with a nonzero status.