| # Converting from Perfetto to other trace formats | |
| Perfetto's native protobuf trace format can be converted to other formats using | |
| the `convert` subcommand of `trace_processor`. | |
| > NOTE: This functionality used to live in a separate `traceconv` tool. That | |
| > tool has been folded into `trace_processor`. The `traceconv` download still | |
| > works as a back-compatible alias (it now fetches `trace_processor` and runs | |
| > it in this mode), but new scripts and docs should use `trace_processor`. | |
|  | |
| > To attach native symbols or ProGuard/R8 deobfuscation mappings to a trace, | |
| > see [Symbolization and deobfuscation](/docs/learning-more/symbolization.md) | |
| > instead (the `bundle` and `util` subcommands). This page covers only format | |
| > conversion. | |
| > | |
| > To dump trace processor's parsed *tables* (rather than the trace itself) as | |
| > SQLite, Arrow or a reloadable Perfetto archive, use the `export` subcommand | |
| > instead: see | |
| > [Export trace data](/docs/getting-started/command-line-analysis.md#export-trace-data). | |
| ## Prerequisites | |
| - A host running Linux, macOS or Windows | |
| - Python 3 (only required if using the `trace_processor` wrapper script below; on | |
| Windows this also requires `curl`, which ships with Windows 10 and later) | |
| - A Perfetto protobuf trace file | |
| ## Usage | |
| To use the latest binaries: | |
| <?tabs> | |
| TAB: Linux / macOS | |
| ```bash | |
| curl -LO https://get.perfetto.dev/trace_processor | |
| chmod +x trace_processor | |
| ./trace_processor convert <format> [OPTIONS] [input_file] [output_file] | |
| ``` | |
| TAB: Windows | |
| ```powershell | |
| curl.exe -LO https://get.perfetto.dev/trace_processor | |
| python trace_processor convert <format> [OPTIONS] [input_file] [output_file] | |
| ``` | |
| </tabs?> | |
| The `trace_processor` script is a thin Python wrapper that downloads and caches | |
| the correct native binary for your platform under | |
| `~/.local/share/perfetto/prebuilts` on first use. | |
| `convert` reads from stdin and writes to stdout when the input or output paths | |
| are omitted (or passed as `-`). Run `./trace_processor help convert` to print | |
| the full list of formats and options supported by your version. | |
| ## Format conversion | |
| | Format | Output | | |
| | ---------- | ------------------------------------------------------------ | | |
| | `text` | protobuf text format — a text representation of the protos | | |
| | `json` | Chrome JSON format, viewable in `chrome://tracing` | | |
| | `systrace` | ftrace text/HTML format used by Android systrace | | |
| | `ctrace` | compressed systrace format | | |
| | `profile` | aggregated pprof profile (heapprofd, perf, Java heap graphs) | | |
| | `firefox` | Firefox profiler format | | |
| Examples: | |
| ```bash | |
| ./trace_processor convert json trace.perfetto-trace trace.json | |
| ./trace_processor convert systrace trace.perfetto-trace trace.html | |
| ./trace_processor convert text trace.perfetto-trace trace.textproto | |
| ``` | |
| `profile` writes one or more `.pb` files into a directory (a random tmp | |
| directory by default) rather than a single output file, so use | |
| `--output-dir` instead of a positional output path: | |
| ```bash | |
| ./trace_processor convert profile --output-dir ./profiles trace.perfetto-trace | |
| ./trace_processor convert profile --java-heap --pid 1234 --output-dir ./profiles trace.perfetto-trace | |
| ./trace_processor convert profile --perf --timestamps 1000000,2000000 --output-dir ./profiles trace.perfetto-trace | |
| ``` | |
| Common options: | |
| - `--truncate start|end` (for `systrace`, `json`, `ctrace`): keep only the | |
| start or end of the trace. | |
| - `--full-sort` (for `systrace`, `json`, `ctrace`): force full trace | |
| sorting. | |
| - `--skip-unknown` (for `text`): skip unknown proto fields. | |
| - `--alloc | --perf | --java-heap` (for `profile`): restrict to a single | |
| profile type (default: auto-detect). | |
| - `--no-annotations` (for `profile`): do not add derived annotations to | |
| frames. | |
| - `--pid` / `--timestamps` (for `profile`): filter by process or specific | |
| sample timestamps. | |
| - `--output-dir DIR` (for `profile`): output directory for the generated | |
| pprof files. | |
| For the inverse of `convert text` (turning a text-format trace back into | |
| binary) and other low-level trace helpers, see `trace_processor help util`. | |
| ## Opening in the legacy systrace UI | |
| If you just want to open a Perfetto trace with the legacy (Catapult) trace | |
| viewer, you can just navigate to [ui.perfetto.dev](https://ui.perfetto.dev), and | |
| use the _"Open with legacy UI"_ link. This runs the trace conversion within the | |
| browser using WebAssembly and passes the converted trace seamlessly to | |
| chrome://tracing. |