**Write [`tracing`][] spans to Android [NDK Tracing][]**
[](https://crates.io/crates/tracing_android_trace)
[](https://docs.rs/tracing_android_trace)
[](#license)
[](https://crates.io/crates/tracing-subscriber)
\
[](https://xi.zulipchat.com/#narrow/stream/147921-general/topic/Android.20Tracing)
[](https://github.com/linebender/android_trace/actions)
[](https://deps.rs/crate/tracing_android_trace)
⚠️ Tracing Android Trace only supports Android
Tracing Android Trace provides several [`tracing_subscriber::Layer`][]s for Android NDK Tracing, using `ATrace_beginSection` and `ATrace_endSection`.
This allows viewing spans created using the [`tracing`][] macros in [Android GPU Inspector](https://gpuinspector.dev/).
Note that this does not currently support `tracing` *events*, only spans.
This limitation is due to the underlying Android platform APIs.
Tracing spans for [Vello](https://github.com/linebender/vello) shown in Android GPU Inspector
Significant changes are documented in [the changelog][].
## Quickstart
Add a dependency on Android Trace (and on [`tracing_subscriber`][]).
```toml
[target.'cfg(target_os = "android")'.dependencies]
android_trace = "0.1.0"
```
You can then add an Android Tracing layer to the registry subscriber:
```rust,no_run
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][tracing_subscriber::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:
```toml
[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.
```sh
# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1
```
## Community
Discussion of Android Trace development happens in the [Linebender Zulip](https://xi.zulipchat.com/), specifically in
[#general > Android Tracing](https://xi.zulipchat.com/#narrow/stream/147921-general/topic/Android.20Tracing).
All public content can be read without logging in.
Contributions are welcome by pull request. The [Rust code of conduct][] applies.
## License
Licensed under either of
* Apache License, Version 2.0
([LICENSE-APACHE][] or )
* MIT license
([LICENSE-MIT][] or )
at your option.