| # 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. |
