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