| # Converting from Perfetto to other trace formats | |
| Perfetto's native protobuf trace format can be converted to other formats using | |
| the `traceconv` utility. `traceconv` also doubles as a toolkit for | |
| symbolizing/deobfuscating traces and for a handful of smaller trace-editing | |
| utilities. | |
|  | |
| ## Prerequisites | |
| - A host running Linux, macOS or Windows | |
| - Python 3 (only required if using the `traceconv` wrapper script below; on | |
| Windows this also requires `curl`, which ships with Windows 10 and later) | |
| - A Perfetto protobuf trace file | |
| `traceconv` has three groups of modes: | |
| - **Format conversion** — convert a Perfetto protobuf trace into another | |
| trace format (Chrome JSON, systrace, pprof, Firefox profiler, etc.). | |
| - **Symbolization and deobfuscation** — attach native symbols and | |
| ProGuard/R8 mappings to a trace. **In almost all cases you should use | |
| `bundle`** (see below), which packages the trace and all its debug | |
| artifacts into a single self-contained TAR — this is the recommended way | |
| to share or archive a trace. | |
| - **Utilities** — smaller helpers (protobuf-text ↔ binary conversion, | |
| packet decompression). | |
| ## Usage | |
| To use the latest binaries: | |
| <?tabs> | |
| TAB: Linux / macOS | |
| ```bash | |
| curl -LO https://get.perfetto.dev/traceconv | |
| chmod +x traceconv | |
| ./traceconv MODE [OPTIONS] [input_file] [output_file] | |
| ``` | |
| TAB: Windows | |
| ```powershell | |
| curl.exe -LO https://get.perfetto.dev/traceconv | |
| python traceconv MODE [OPTIONS] [input_file] [output_file] | |
| ``` | |
| </tabs?> | |
| The `traceconv` script is a thin Python wrapper that downloads and caches | |
| the correct native binary for your platform (including `traceconv.exe` on | |
| Windows) under `~/.local/share/perfetto/prebuilts` on first use. | |
| `traceconv` reads from stdin and writes to stdout when the input or output | |
| paths are omitted (or passed as `-`). Run `./traceconv` with no arguments | |
| to print the full list of modes and options supported by your version. | |
| ## Format conversion | |
| | Mode | 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 | |
| ./traceconv json trace.perfetto-trace trace.json | |
| ./traceconv systrace trace.perfetto-trace trace.html | |
| ./traceconv 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 | |
| ./traceconv profile --output-dir ./profiles trace.perfetto-trace | |
| ./traceconv profile --java-heap --pid 1234 --output-dir ./profiles trace.perfetto-trace | |
| ./traceconv 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. | |
| ## Symbolization and deobfuscation | |
| These modes enrich a trace with native symbols and/or ProGuard/R8 | |
| deobfuscation mappings. For background on how Perfetto discovers symbol | |
| files and mapping files, see the | |
| [Symbolization](https://perfetto.dev/docs/learning-more/symbolization) | |
| reference. | |
| ### `bundle` (recommended) | |
| **`bundle` is the recommended entry point for symbolization and | |
| deobfuscation.** It packages the trace together with its native symbols | |
| and ProGuard/R8 mappings into a single self-contained TAR, which is the | |
| right artifact to share with teammates, attach to bugs, or archive for | |
| later analysis. Prefer `bundle` over `symbolize`/`deobfuscate` unless you | |
| have a specific reason not to. | |
| ```bash | |
| ./traceconv bundle trace.perfetto-trace trace.bundle.tar | |
| # Provide extra symbol search paths or explicit ProGuard maps: | |
| ./traceconv bundle \ | |
| --symbol-paths /path/to/symbols1,/path/to/symbols2 \ | |
| --proguard-map com.example.app=/path/to/mapping.txt \ | |
| trace.perfetto-trace trace.bundle.tar | |
| ``` | |
| `bundle`-specific options: | |
| - `--symbol-paths PATH1,PATH2,...` — additional paths to search for | |
| symbols (on top of the automatic discovery). | |
| - `--no-auto-symbol-paths` — disable automatic symbol path discovery. | |
| - `--proguard-map [pkg=]PATH` — ProGuard/R8 `mapping.txt` for Java/Kotlin | |
| deobfuscation. May be repeated; the `pkg=` prefix scopes the map to a | |
| specific package. | |
| - `--no-auto-proguard-maps` — disable automatic ProGuard/R8 mapping | |
| discovery (e.g. Gradle project layout). | |
| - `--verbose` — print more detailed output. | |
| Note: `bundle` requires real file paths for both the input and the output | |
| — it does not accept stdin/stdout. | |
| ### `symbolize` / `deobfuscate` (advanced) | |
| Lower-level building blocks for pipelines that cannot use `bundle`. Each | |
| emits a stream of packets (symbols or deobfuscation mappings) to a | |
| separate output file: | |
| ```bash | |
| ./traceconv symbolize trace.perfetto-trace symbols.pb | |
| ./traceconv deobfuscate trace.perfetto-trace mappings.pb | |
| ``` | |
| Prefer `bundle` — it produces a single self-contained TAR instead of | |
| leaving you with loose side-car files to manage. | |
| ## Utilities | |
| | Mode | What it does | | |
| | -------------------- | ----------------------------------------------------------- | | |
| | `binary` | Convert a protobuf text-format trace back into binary form. | | |
| | `decompress_packets` | Decompress compressed `TracePacket`s inside a trace. | | |
| ```bash | |
| ./traceconv binary trace.textproto trace.perfetto-trace | |
| ./traceconv decompress_packets trace.perfetto-trace trace.decompressed | |
| ``` | |
| ## 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 `traceconv` within the browser | |
| using WebAssembly and passes the converted trace seamlessly to chrome://tracing. |