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
tsthread_nametidslice_namedur
261190068051612android.anim1317dequeueBuffer623021
261190068636404android.anim1317importBuffer30312
261190068687289android.anim1317lockAsync2269428
261190068693852android.anim1317LockBuffer2255313
261190068696300android.anim1317MapBuffer36302
261190068734529android.anim1317CleanBuffer2211198

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
tsprocess_namepidcounter_namevalue
261193227069635com.android.systemui1664GPU completion0
261193268649379com.android.systemui1664GPU completion1
261193269787139com.android.systemui1664HWC release1
261193270330890com.android.systemui1664GPU completion0
261193271282244com.android.systemui1664GPU completion1
261193277112817com.android.systemui1664HWC release0

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: "*"
    }
  }
}