Instrumenting Android apps/platform with atrace

In this guide, you'll learn how to:

• Add ATrace instrumentation to your Android application or platform code.
• Record and visualize ATrace events in the Perfetto UI.
• Understand the difference between ATrace and the Perfetto Tracing SDK.

This page is mainly intended for:

• Android platform engineers for instrumenting their platform services.
• System integrators / Android partners for instrumenting their native HALs and Java/Kt services.
• Native and Java/Kt app developers for instrumenting their apps (although you should consider using androidx.tracing, more below)

Atrace is an API introduced in Android 4.3 that predates that allows you to add instrumentation to your code. It is still supported and in use, and interoperates well with Perfetto.

Under the hoods, Atrace forwards events up to the kernel ftrace ring-buffer and gets fetched together with the rest of scheduling data and other system-level trace data. Atrace is both:

1. A public API, exposed both to Java/Kt code via the Android SDK and C/C++ code via the NDK, that developers can use to enrich traces annotating their apps.
2. A private platform API used to annotate several framework functions and the implementation of core system services. It provides developers with insights about what the framework is doing under the hoods.

The main difference between the two is that the private platform API allows specifying a tag (also known as category), while the SDK/NDK interface implicitly uses TRACE_TAG_APP.

In both cases, Atrace allows you to manually add instrumentation around code wall timing and numeric values, e.g. to annotate the beginning or end of functions, logical user journeys, state changes.

Thread-scoped synchronous slices

Slices are used to create rectangles around the execution of code and visually form a pseudo-callstack.

Semantic and constraints:

• API: Slices are emitted with begin/end APIs.
• Balancing: Begin/end MUST be balanced and must happen on the same thread.
• Visualization: Slices are visualized in a thread-scoped track (as in the picture above).
• Cross-thread: See Cross-thread async slices below for cross-thread use-cases.

Counters

Semantic and constraints:

• Threading: Counters can be emitted from any thread.
• Visualization: Counters are visualized in a process-scoped track named after the counter name (the string argument). Each new counter name automatically yields a new track in the UI. Counter events from different threads within a process are folded into the same process-scoped track.

Cross-thread async slices

Async slices allow to trace logical operations that might begin and end on different threads. They are the same concept of track events in the Perfetto SDK.

Because begin/end can happen on different thread, you need to pass a cookie to each begin/end function. The cookie is just an integer number used to match begin/end pairs. The cookie is usually derived from a pointer or a unique ID that represents the logical operation being traced (e.g. a job id).

Semantic and constraints:

• Overlapping: Because of their async nature, slices can overlap temporally: one operation might begin before the previous one has ended.
• Cookies: Cookies must be unique within a process. You cannot have a begin event for the same cookie before having emitted an end event for it. In other words, cookies are a shared integer namespace within the process. Using a monotonic counter is probably a bad idea unless you have full control of all the code in the process.
• Nesting and Tracks: Unlike thread-scoped slices, nesting/stacking is only possible when using the private platform API. The ...ForTrack functions allow you to specify a track name, and all events with the same track name will be grouped in the same process-scoped track in the UI. Within a track, nesting is controlled by the cookie parameter. The SDK/NDK API does not support nesting, and the track is derived from the event name.
• Stacking: Visually, the UI lays slice within each track using a greedy stacking algorithm. Each slice is placed in the uppermost lane that doesn’t overlap with any other slice. This sometimes generates confusion amongst users as it creates a false sense of “parent/child” relationship. However, unlike sync slices, the relationship is purely temporal and not causal and you cannot control it (other than grouping events into tracks, if you have access to the private platform API).

Should I use Atrace or the Perfetto Tracing SDK?

At the time of writing, there isn't a clear-cut answer to this question. Our team is working on providing a replacement SDK that can subsume all the atrace use cases, but we are not there yet. So the answer is: depends.

When to prefer Atrace	When to prefer the Tracing SDK
You need something simple that just works.	You need more advanced features (e.g. flows).
You are okay with one on/off toggle for the whole app. (If you are in the Android system you can only se a limited set of tags)	You need fine-grained control over tracing categories.
You are okay with events being multiplexed in the main ftace buffer.	You want control over muxing vents in different buffers.
Instrumentation overhead is not a big concern, your trace points are hit sporadically.	You want ininmal overhead for your instrumentation points. Your trace points are frequent (every 10ms or less)

If you are an unbundled app

You should consider using androidx.tracing from Jetpack. We work closely with the Jetpack project. Using androidx.tracing is going to lead to a smoother migration path once we improve our SDK.

Recording the trace

In order to record atrace you must enable the linux.ftrace data source and add in the ftrace_config:

• For platform private system services: atrace_categories: tag_name
• For apps: atrace_apps: "com.myapp" or atrace_apps: "*" for all apps.

You can see the full list of atrace categories here.

Next Steps

Now that you've learned how to instrument your code with ATrace, here are some other documents you might find useful:

Recording traces

• Recording system traces: Learn more about recording traces on Android.

Other Android data sources

• Scheduling data: See which threads are running on which CPU.
• CPU frequency: See how fast each CPU is running.

Analyzing traces

• Perfetto UI: Learn about all the features of the trace viewer.