xref: /aosp_15_r20/external/perfetto/docs/quickstart/traceconv.md (revision 6dbdd20afdafa5e3ca9b8809fa73465d530080dc) 
1# Quickstart: Trace conversion
2
3_This quickstart demonstrates how Perfetto traces can be converted into other trace formats using the `traceconv` tool._
4
5![](/docs/images/traceconv-summary.png)
6
7## Prerequisites
8
9- A host running Linux or MacOS
10- A Perfetto protobuf trace file
11
12The supported output formats are:
13
14- `text` - protobuf text format: a text based representation of protos
15- `json` - Chrome JSON format: the format used by chrome://tracing
16- `systrace`: the ftrace text format used by Android systrace
17- `profile` : pprof-like format. Either for traces with with
18  [native heap profiler](/docs/data-sources/native-heap-profiler.md) dumps or
19  [callstack sampling](/docs/quickstart/callstack-sampling.md) (note however
20  callstacks requires the `--perf` flag).
21
22## Setup
23
24To use the latest binaries:
25
26```bash
27curl -LO https://get.perfetto.dev/traceconv
28chmod +x traceconv
29./traceconv [text|json|systrace|profile] [input proto file] [output file]
30```
31
32For versioned downloads, replace `<tag>` with the required git tag:
33
34```bash
35curl -LO https://raw.githubusercontent.com/google/perfetto/<tag>/tools/traceconv
36chmod +x traceconv
37./traceconv [text|json|systrace|profile] [input proto file] [output file]
38```
39
40## Converting to systrace text format
41
42`./traceconv systrace [input proto file] [output systrace file]`
43
44## Converting to Chrome Tracing JSON format
45
46`./traceconv json [input proto file] [output json file]`
47
48## Converting to pprof profile.
49
50This extract all samples from the trace, and outputs a proto that is compatible
51with pprof.
52
53If you are extracting heaps profiles like heapprofd you can use the following:
54
55`~/traceconv profile [input proto file] [output file]`
56
57However if you are using callstack sampling like traced_perf then use the
58following instead:
59
60`~/traceconv profile [input proto file] [output file] --perf`
61
62Note for `--perf` the output is one pprof file per process sampled in the trace.
63You can use pprof to merge them together if desired.
64
65## Opening in the legacy systrace UI
66
67If you just want to open a Perfetto trace with the legacy (Catapult) trace
68viewer, you can just navigate to [ui.perfetto.dev](https://ui.perfetto.dev),
69and use the _"Open with legacy UI"_ link. This runs `traceconv` within
70the browser using WebAssembly and passes the converted trace seamlessly to
71chrome://tracing.
72