⚠️ 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.

Significant changes are documented in the changelog.

Quickstart

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(){ 
  tracing_subscriber::registry()
    .with(tracing_android_trace::AndroidTraceLayer::new())
    .try_init()
    .unwrap();
}

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.

Async

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.

Counters

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.

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