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:
Java/Kotlin apps (SDK):
android.os.Trace
. See https://developer.android.com/reference/android/os/Trace.Native processes (NDK):
ATrace_beginSection() / ATrace_setCounter()
defined in<trace.h>
. See https://developer.android.com/ndk/reference/group/tracing.Android internal processes:
ATRACE_BEGIN()/ATRACE_INT()
defined inlibcutils/trace.h
.
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: "*"
}
}
}