# Android Trace
**Support for Android NDK [Tracing](https://developer.android.com/ndk/reference/group/tracing)**
[](https://crates.io/crates/android_trace)
[](https://docs.rs/android_trace)
[](#license)
\
[](https://xi.zulipchat.com/#narrow/stream/147921-general/topic/Android.20Tracing)
[](https://github.com/linebender/android_trace/actions)
[](https://deps.rs/crate/android_trace)
⚠️ Android Trace only supports Android
Android Trace provides access to the Android NDK methods, such as `ATrace_beginSection` and `ATrace_endSection`.
This enables using [Android GPU Inspector](https://gpuinspector.dev/) for Rust code.
See [tracing_android_trace](https://crates.io/crates/tracing_android_trace)
for an integration of this with [`tracing`](https://docs.rs/tracing/latest/tracing/).
Significant changes are documented in [the changelog][].
## Quickstart
Add a dependency on Android Trace:
```toml
[target.'cfg(target_os = "android")'.dependencies]
android_trace = "0.1.0"
```
The main entry point to the library is [AndroidTrace][], which stores function pointers to each available NDK function:
```rust,no_run
use android_trace::AndroidTrace;
let trace = AndroidTrace::new();
// If the `is_enabled` method isn't available, we also shouldn't trace
let should_trace = trace.is_enabled().unwrap_or(false);
if should_trace {
trace.begin_section(c"My expensive calculation");
}
// ...performing an expensive calculation
if should_trace {
trace.end_section();
}
```
## Android API levels
The first level of the [tracing API](https://developer.android.com/ndk/reference/group/tracing) has been available since Android API level 23, and a more flexible API was added in Android API level 29.
To support devices with any Android API versions, we resolve these functions at runtime using [dlsym][].
This runtime access is used unless we know (through [features](#crate-feature-flags)) that a certain API level is available.
## 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, to improve efficiency, to avoid runtime symbol resolution entirely
To support Android API versions less than 23, you should disable default features:
```toml
[target.'cfg(target_os = "android")'.dependencies]
android_trace = { version = "0.1.0", default-features = false }
```
## Minimum supported Rust Version (MSRV)
This version of Android Trace has been verified to compile with **Rust 1.77** and later.
Future versions of 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 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.
[the changelog]: https://github.com/linebender/android_trace/blob/main/CHANGELOG.md
[rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct
[LICENSE-APACHE]: LICENSE-APACHE
[LICENSE-MIT]: LICENSE-MIT
[AndroidTrace]: https://docs.rs/android_trace/0.1.0/android_trace/struct.AndroidTrace.html
[dlsym]: https://man7.org/linux/man-pages/man3/dlsym.3.html