1# ATrace: Android system and app trace events 2 3On Android, native and managed apps can inject custom slices and counter trace 4points into the trace. This is possible through the following: 5 6* Java/Kotlin apps (SDK): `android.os.Trace`. 7 See https://developer.android.com/reference/android/os/Trace. 8 9* Native processes (NDK): `ATrace_beginSection() / ATrace_setCounter()` defined 10 in `<trace.h>`. See https://developer.android.com/ndk/reference/group/tracing. 11 12* Android internal processes: `ATRACE_BEGIN()/ATRACE_INT()` defined in 13 [`libcutils/trace.h`][libcutils]. 14 15This API has been available since Android 4.3 (API level 18) and predates 16Perfetto. All these annotations, which internally are all routed through the 17internal libcutils API, are and will continue to be supported by Perfetto. 18 19There are two types of atrace events: System and App events. 20 21**System events**: are emitted only by Android internals using libcutils. 22These events are grouped in categories (also known as _tags_), e.g. 23"am" (ActivityManager), "pm" (PackageManager). 24For a full list of categories see the _Record new trace_ page of the 25[Perfetto UI](https://ui.perfetto.dev). 26 27Categories can be used to enable group of events across several processes, 28without having to worry about which particular system process emits them. 29 30**App events**: have the same semantics of system events. Unlike system events, 31however, they don't have any tag-filtering capability (all app events share the 32same tag `ATRACE_TAG_APP`) but can be enabled on a per-app basis. 33 34See the [TraceConfig](#traceconfig) section below for instructions on how to 35enable both system and app events. 36 37#### Instrumentation overhead 38 39ATrace instrumentation a non-negligible cost of 1-10us per event. 40This is because each event involves a stringification, a JNI call if coming from 41a managed execution environment, and a user-space <-> kernel-space roundtrip to 42write the marker into `/sys/kernel/debug/tracing/trace_marker` (which is the 43most expensive part). 44 45Our team is are looking into a migration path for Android, in light of the newly 46introduced [Tracing SDK](/docs/instrumentation/tracing-sdk.md). At the moment 47the advice is to keep using the existing ATrace API on Android. 48 49[libcutils]: https://cs.android.com/android/platform/superproject/+/master:system/core/libcutils/include/cutils/trace.h?q=f:trace%20libcutils 50 51## UI 52 53At the UI level, these functions create slices and counters within the scope of 54a process track group, as follows: 55 56 57 58## SQL 59 60At the SQL level, ATrace events are available in the standard `slice` and 61`counter` tables, together with other counters and slices coming from other 62data sources. 63 64### Slices 65 66```sql 67select s.ts, t.name as thread_name, t.tid, s.name as slice_name, s.dur 68from slice as s left join thread_track as trk on s.track_id = trk.id 69left join thread as t on trk.utid = t.utid 70``` 71 72ts | thread_name | tid | slice_name | dur 73---|-------------|-----|------------|---- 74261190068051612 | android.anim | 1317 | dequeueBuffer | 623021 75261190068636404 | android.anim | 1317 | importBuffer | 30312 76261190068687289 | android.anim | 1317 | lockAsync | 2269428 77261190068693852 | android.anim | 1317 | LockBuffer | 2255313 78261190068696300 | android.anim | 1317 | MapBuffer | 36302 79261190068734529 | android.anim | 1317 | CleanBuffer | 2211198 80 81### Counters 82 83```sql 84select ts, p.name as process_name, p.pid, t.name as counter_name, c.value 85from counter as c left join process_counter_track as t on c.track_id = t.id 86left join process as p on t.upid = p.upid 87``` 88 89ts | process_name | pid | counter_name | value 90---|--------------|-----|--------------|------ 91261193227069635 | com.android.systemui | 1664 | GPU completion | 0 92261193268649379 | com.android.systemui | 1664 | GPU completion | 1 93261193269787139 | com.android.systemui | 1664 | HWC release | 1 94261193270330890 | com.android.systemui | 1664 | GPU completion | 0 95261193271282244 | com.android.systemui | 1664 | GPU completion | 1 96261193277112817 | com.android.systemui | 1664 | HWC release | 0 97 98## TraceConfig 99 100```protobuf 101buffers { 102 size_kb: 102400 103 fill_policy: RING_BUFFER 104} 105 106data_sources { 107 config { 108 name: "linux.ftrace" 109 ftrace_config { 110 # Enables specific system events tags. 111 atrace_categories: "am" 112 atrace_categories: "pm" 113 114 # Enables events for a specific app. 115 atrace_apps: "com.google.android.apps.docs" 116 117 # Enables all events for all apps. 118 atrace_apps: "*" 119 } 120 } 121} 122``` 123
