1# Quickstart: Record traces on Linux 2 3Perfetto can capture system traces on Linux. All ftrace-based data sources 4and most other procfs / sysfs-based data sources are supported. 5 6Currently there are no packages or prebuilts for Linux. In order to run Perfetto 7on Linux you need to build it from source. 8 9## Building from source 10 111. Check out the code: 12```bash 13git clone https://android.googlesource.com/platform/external/perfetto/ && cd perfetto 14``` 15 162. Download and extract build dependencies: 17```bash 18tools/install-build-deps 19``` 20_If the script fails with SSL errors, try upgrading your openssl package._ 21 223. Generate the build configuration 23```bash 24tools/gn gen --args='is_debug=false' out/linux 25# Or use `tools/setup_all_configs.py` to generate more build configs. 26``` 27 284. Build the Linux tracing binaries (On Linux it uses a hermetic clang toolchain, downloaded as part of step 2): 29```bash 30tools/ninja -C out/linux tracebox traced traced_probes perfetto 31``` 32 33## Capturing a trace 34 35Due to Perfetto's [service-based architecture](/docs/concepts/service-model.md), 36in order to capture a trace, the `traced` (session daemon) and `traced_probes` 37(probes and ftrace-interop daemon) need to be running. 38As per Perfetto v16, the `tracebox` binary bundles together all the binaries you 39need in a single executable (a bit like `toybox` or `busybox`). 40 41#### Capturing a trace with ftrace and /proc pollers, no SDK 42 43If you are interested in overall system tracing and are not interested in 44testing the SDK, you can use `tracebox` in autostart mode as follows: 45 46```bash 47out/linux/tracebox -o trace_file.perfetto-trace --txt -c test/configs/scheduling.cfg 48``` 49 50#### Testing the SDK integration in out-of-process tracing mode (system mode) 51 52If you are using the Perfetto [tracing SDK](/docs/instrumentation/tracing-sdk) 53and want to capture a fused trace that contains both system traces events and 54your custom app trace events, you need to start the `traced` and `traced_probes` 55services ahead of time and then use the `perfetto` cmdline client. 56 57For a quick start, the [tools/tmux](/tools/tmux) script takes care of building, 58setting up and running everything. 59As an example, let's look at the process scheduling data, which will be obtained 60from the Linux kernel via the [ftrace] interface. 61 62[ftrace]: https://www.kernel.org/doc/Documentation/trace/ftrace.txt 63 641. Run the convenience script with an example tracing config (10s duration): 65```bash 66tools/tmux -c test/configs/scheduling.cfg -C out/linux -n 67``` 68This will open a tmux window with three panes, one per the binary involved in 69tracing: `traced`, `traced_probes` and the `perfetto` client cmdline. 70 712. Start the tracing session by running the pre-filled `perfetto` command in 72 the down-most [consumer] pane. 73 743. Detach from the tmux session with `Ctrl-B D`,or shut it down with 75 `tmux kill-session -t demo`. The script will then copy the trace to 76 `/tmp/trace.perfetto-trace`, as a binary-encoded protobuf (see 77 [TracePacket reference](/docs/reference/trace-packet-proto.autogen)). 78 79## Visualizing the trace 80 81We can now explore the captured trace visually by using a dedicated web-based UI. 82 83NOTE: The UI runs in-browser using JavaScript + Web Assembly. The trace 84 file is **not** uploaded anywhere by default, unless you explicitly click 85 on the 'Share' link. The 'Share' link is available only to Googlers. 86 871. Navigate to [ui.perfetto.dev](https://ui.perfetto.dev) in a browser. 88 892. Click the **Open trace file** on the left-hand menu, and load the captured 90 trace (by default at `/tmp/trace.perfetto-trace`). 91 923. Explore the trace by zooming/panning using WASD, and mouse for expanding 93 process tracks (rows) into their constituent thread tracks. 94 Press "?" for further navigation controls. 95 96Alternatively, you can explore the trace contents issuing SQL queries through 97the [trace processor](/docs/analysis/trace-processor). 98