created_at2024-04-03 12:45:30.76656
updated_at2024-06-14 13:42:20.558698
descriptionSupport for Android NDK Tracing
Kaur Kuut (xStrom)



Tracing Android Trace

Write tracing spans to Android NDK Tracing

Latest published version. Documentation build status. Apache 2.0 or MIT license. tracing-subscriber version
Linebender Zulip chat. GitHub Actions CI status. Dependency staleness status.

⚠️ Tracing Android Trace only supports Android

Tracing Android Trace provides several tracing_subscriber::Layers for Android NDK Tracing, using ATrace_beginSection and ATrace_endSection. This allows viewing spans created using the tracing macros in Android GPU Inspector.

Note that this does not currently support tracing events, only spans. This limitation is due to the underlying Android platform APIs.

Screenshot showing a thread timeline including spans of a single thread.

Tracing spans for Vello shown in Android GPU Inspector

Significant changes are documented in the changelog.


Add a dependency on Android Trace (and on tracing_subscriber).

[target.'cfg(target_os = "android")'.dependencies]
android_trace = "0.1.0"

You can then add an Android Tracing layer to the registry subscriber:

use tracing_subscriber::prelude::*;

fn main(){ 

Available Layers

NDK Tracing supports three kinds of tracing, with different API level requirements.

Thread-Matched sections

The first API added, which is useful for tracking time spent in a thread, was ATrace_beginSection and ATrace_endSection. This has been available since Android API level 23.

AndroidTraceLayer uses this API, and is the preferred layer from this crate - it was used to produce the screenshot above.

Note that if entering and exiting of spans are interleaved, this layer will produce discontinuous traces. This is required to work around the limitations of the NDK API. See the documentation on the layer for more details.


This crate also includes an async layer AndroidTraceAsyncLayer, which uses ATrace_beginAsyncSection and ATrace_endAsyncSection. It is recommended to filter the use of this API to only your async tasks. See the documentation on the layer for an example of how to do so.

This is necessary because Android Tracing does not allow async tasks to be associated with each other. This means that each task will be shown in their own line in the trace, which is rarely a useful UI. It is also recommended to not associate any fields with these spans, as lines in the trace will not be re-used.


The underlying API also supports setting counter values, however this is not yet implemented. If you require this, please open an issue.

Android API levels

This crate uses android_trace to call the NDK functions. Therefore, this crate can support any Android API level on the target device, although by default it requires an API level of 23 (corresponding to Android 6, codename Marshmallow, released in 2015).

To support Android API versions less than 23, you should disable default features:

[target.'cfg(target_os = "android")'.dependencies]
tracing_android_trace = { version = "0.1.0", default-features = false }

Crate feature flags

The following feature flags are available:

  • api_level_23 (enabled by default): Require Android API level 23, to avoid some runtime symbol resolution
  • api_level_29: Require Android API level 29, disabling runtime symbol resolution entirely

Minimum supported Rust Version (MSRV)

This version of Tracing Android Trace has been verified to compile with Rust 1.77 and later.

Future versions of Tracing Android Trace might increase the Rust version requirement. It will not be treated as a breaking change and as such can even happen with small patch releases.

Click here if compiling fails.

As time has passed, some of Tracing Android Trace's dependencies could have released versions with a higher Rust requirement. If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.

# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1


Discussion of Android Trace development happens in the Linebender Zulip, specifically in #general > Android Tracing. All public content can be read without logging in.

Contributions are welcome by pull request. The Rust code of conduct applies.


Licensed under either of

at your option.

Commit count: 14

cargo fmt