ATrace: Android system and app trace events

On Android, native and managed apps can inject custom slices and counter trace points into the trace. This is possible through the following:

This API has been available since Android 4.3 (API level 18) and predates Perfetto. All these annotations, which internally are all routed through the internal libcutils API, are and will continue to be supported by Perfetto.

There are two types of atrace events: System and App events.

System events: are emitted only by Android internals using libcutils. These events are grouped in categories (also known as tags), e.g. "am" (ActivityManager), "pm" (PackageManager). For a full list of categories see the Record new trace page of the Perfetto UI.

Categories can be used to enable group of events across several processes, without having to worry about which particular system process emits them.

App events: have the same semantics of system events. Unlike system events, however, they don't have any tag-filtering capability (all app events share the same tag ATRACE_TAG_APP) but can be enabled on a per-app basis.

See the TraceConfig section below for instructions on how to enable both system and app events.

Instrumentation overhead

ATrace instrumentation a non-negligible cost of 1-10us per event. This is because each event involves a stringification, a JNI call if coming from a managed execution environment, and a user-space <-> kernel-space roundtrip to write the marker into /sys/kernel/debug/tracing/trace_marker (which is the most expensive part).

Our team is looking into a migration path for Android, in light of the newly introduced Tracing SDK. At the moment the advice is to keep using the existing ATrace API on Android.

UI

At the UI level, these functions create slices and counters within the scope of a process track group, as follows:

SQL

At the SQL level, ATrace events are available in the standard slice and counter tables, together with other counters and slices coming from other data sources.

Slices

select s.ts, t.name as thread_name, t.tid, s.name as slice_name, s.dur from slice as s left join thread_track as trk on s.track_id = trk.id left join thread as t on trk.utid = t.utid
ts thread_name tid slice_name dur
261190068051612 android.anim 1317 dequeueBuffer 623021
261190068636404 android.anim 1317 importBuffer 30312
261190068687289 android.anim 1317 lockAsync 2269428
261190068693852 android.anim 1317 LockBuffer 2255313
261190068696300 android.anim 1317 MapBuffer 36302
261190068734529 android.anim 1317 CleanBuffer 2211198

Counters

select ts, p.name as process_name, p.pid, t.name as counter_name, c.value from counter as c left join process_counter_track as t on c.track_id = t.id left join process as p on t.upid = p.upid
ts process_name pid counter_name value
261193227069635 com.android.systemui 1664 GPU completion 0
261193268649379 com.android.systemui 1664 GPU completion 1
261193269787139 com.android.systemui 1664 HWC release 1
261193270330890 com.android.systemui 1664 GPU completion 0
261193271282244 com.android.systemui 1664 GPU completion 1
261193277112817 com.android.systemui 1664 HWC release 0

TraceConfig

buffers { size_kb: 102400 fill_policy: RING_BUFFER } data_sources { config { name: "linux.ftrace" ftrace_config { # Enables specific system events tags. atrace_categories: "am" atrace_categories: "pm" # Enables events for a specific app. atrace_apps: "com.google.android.apps.docs" # Enables all events for all apps. atrace_apps: "*" } } }