1# Perfetto SDK example project 2 3This directory contains an example project using the [Perfetto 4SDK](https://perfetto.dev/docs/instrumentation/tracing-sdk). It demonstrates 5how to instrument your application with track events to give more context in 6developing, debugging and performance analysis. 7 8Dependencies: 9 10- [CMake](https://cmake.org/) 11- C++11 12 13## Building 14 15First, check out the latest Perfetto release: 16 17```bash 18git clone https://android.googlesource.com/platform/external/perfetto -b v4.1 19``` 20 21Then, build using CMake: 22 23```bash 24cd perfetto/examples/sdk 25cmake -B build 26cmake --build build 27``` 28 29## Track event example 30 31The [basic example](example.cc) shows how to instrument an app with track 32events. Run it with: 33 34```bash 35build/example 36``` 37 38The program will create a trace file in `example.pftrace`, which can be 39directly opened in the [Perfetto UI](https://ui.perfetto.dev). The result 40should look like this: 41 42 44 45## System-wide example 46 47While the above example only records events from the program itself, with 48Perfetto it's also possible to combine app trace events with system-wide 49profiling data (e.g., ftrace on Linux). The repository has a [second 50example](example_system_wide.cc) which demonstrates this on Android. 51 52Requirements: 53- [Android NDK](https://developer.android.com/ndk) 54- A device running Android Pie or newer 55 56> Tip: It's also possible to sideload Perfetto on pre-Pie Android devices. 57> See the [build 58> instructions](https://perfetto.dev/docs/contributing/build-instructions). 59 60To build: 61 62```bash 63export NDK=/path/to/ndk 64cmake -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \ 65 -B build_android 66cmake --build build_android 67``` 68 69Next, plug in an Android device into a USB port, download the example and run 70it while simultaneously recording a trace using the `perfetto` command line 71tool: 72 73```bash 74adb push build_android/example_system_wide ../system_wide_trace_cfg.pbtxt \ 75 /data/local/tmp/ 76adb shell "\ 77 cd /data/local/tmp; \ 78 rm -f /data/misc/perfetto-traces/example_system_wide.pftrace; \ 79 cat system_wide_trace_cfg.pbtxt | \ 80 perfetto --config - --txt --background \ 81 -o /data/misc/perfetto-traces/example_system_wide.pftrace; \ 82 ./example_system_wide" 83``` 84 85Finally, retrieve the resulting trace: 86 87```bash 88adb pull /data/misc/perfetto-traces/example_system_wide.pftrace 89``` 90 91When opened in the Perfetto UI, the trace now shows additional contextual 92information such as CPU frequencies and kernel scheduler information. 93 94 96 97> Tip: You can generate a new trace config with additional data sources using 98> the [Perfetto UI](https://ui.perfetto.dev/#!/record) and replace 99> `system_wide_trace_cfg.pbtxt` with the [generated config]( 100> https://ui.perfetto.dev/#!/record?p=instructions). 101 102## Custom data source example 103 104The [final example](example_custom_data_source.cc) shows how to use an 105application defined data source to emit custom, strongly typed data into a 106trace. Run it with: 107 108```bash 109build/example_custom_data_source 110``` 111 112The program generates a trace file in `example_custom_data_source.pftrace`, 113which we can examine using Perfetto's `trace_to_text` tool to show the trace 114packet written by the custom data source: 115 116```bash 117trace_to_text text example_custom_data_source.pftrace 118... 119packet { 120 trusted_uid: 0 121 timestamp: 42 122 trusted_packet_sequence_id: 2 123 previous_packet_dropped: true 124 for_testing { 125 str: "Hello world!" 126 } 127} 128... 129```
