---
title: "Android Native Development Kit (NDK)"
description: "Learn how to configure the NDK integration."
url: https://docs.sentry.io/platforms/android/configuration/using-ndk/
---

# Android Native Development Kit (NDK) | Sentry for Android

The Android Native Development Kit (NDK) allows you to implement parts of your app in native code, using languages such as C and C++.

NDK integration is packed with the SDK. The package `sentry-android-ndk` works by bundling Sentry's native SDK, [`sentry-native`](https://docs.sentry.io/platforms/native.md). As a result, even if a native library in your app causes the crash, Sentry is able to capture it.

You can [disable the NDK integration](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#disable-ndk-integration), or use our Sentry Android SDK [without the NDK](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#using-the-sdk-without-the-ndk).

Starting with Sentry Android SDK version 8.32.0 you can enable the [Tombstone Integration](https://docs.sentry.io/platforms/android/configuration/tombstones.md) as a replacement or extension to the NDK integration.

## [Symbolicate Stack Traces](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#symbolicate-stack-traces)

To symbolicate the stack trace from native code, we need to have access to the debug symbols of your application.

Use the [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md) to upload the debug symbols and sources automatically.

Alternatively, in case you're not using Gradle, you can upload your `.so` files manually via `sentry-cli`. Please check the full documentation on [uploading files](https://docs.sentry.io/platforms/android/data-management/debug-files/upload.md) to learn more about the upload of the debug symbols.

## [Allowing the Compiler to Link Libraries](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#allowing-the-compiler-to-link-libraries)

To use the Android NDK in your native code, include the `sentry-native` NDK libraries so the compiler can link them during the build. Use Android prefab to consume Sentry's prebuilt packages and link them in your `CMakeLists.txt`.

Android prefab support can only be used with Sentry Android SDK version 8.0.0 and above.

Enable prefab and add the sentry-native ndk dependency directly to your module:

```kotlin
android {
    buildFeatures {
        prefab = true
    }
}

dependencies {
    // The version MUST match with the version the Sentry Android SDK is using.
    // See https://github.com/getsentry/sentry-java/blob/8.52.0/gradle/libs.versions.toml
    implementation("io.sentry:sentry-native-ndk:<version>")
}
```

Link the pre-built packages with your native code

```text
find_package(sentry-native-ndk REQUIRED CONFIG)

target_link_libraries(<app> PRIVATE
    sentry-native-ndk::sentry-android
    sentry-native-ndk::sentry
)
```

Now you can use the Sentry NDK API just by including the `sentry.h` in your code:

```c
#include <jni.h>
#include <android/log.h>
#include <sentry.h>

#define TAG "sentry-android-demo"
extern "C" JNIEXPORT jstring JNICALL

Java_io_sentry_demo_NativeDemo_crash(JNIEnv *env, jclass cls) {
    __android_log_print(ANDROID_LOG_WARN, "", "Capture a message.");
    sentry_value_t event = sentry_value_new_message_event(
            /*   level */ SENTRY_LEVEL_INFO,
            /*  logger */ "custom",
            /* message */ "Sample message!"
    );
    sentry_capture_event(event);
}
```

## [App Hang Detection](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#app-hang-detection)

The NDK integration can detect when a native or game thread stops responding, even when the app does not crash. Unlike Android ANR detection, which monitors the Android UI thread, app hang detection watches the thread that sends native heartbeats. This is useful for engines or native code with their own main loop.

##### Experimental

NDK app hang detection is experimental. It requires Sentry Android SDK version `8.48.0` or later and the NDK integration.

Enable detection when you initialize the SDK, then call `sentry_app_hang_heartbeat()` regularly from the thread you want to monitor:

```kotlin
SentryAndroid.init(this) { options ->
    options.isEnableNdkAppHangTracking = true
    options.ndkAppHangTimeoutIntervalMillis = 2_000
}
```

*Other available variations of the above snippet: Java, c*

The first heartbeat chooses the monitored thread. If it misses heartbeats for the configured timeout, the NDK integration captures an app hang event with that thread's stack trace. The timeout defaults to `5000` ms and has a minimum of `1000` ms.

Android ANR detection remains independent. If the same freeze blocks both the Android UI thread and your monitored native thread, Sentry can report both an ANR and an app hang.

You can also configure these options in `AndroidManifest.xml`, which is useful when the SDK initializes automatically:

```xml
<application>
    <meta-data
    android:name="io.sentry.ndk.app-hang.enable"
    android:value="true"
  />
    <meta-data
    android:name="io.sentry.ndk.app-hang.timeout-interval-millis"
    android:value="2000"
  />
</application>
```

For details about the native watchdog and heartbeat behavior, see the [Native SDK app hang documentation](https://docs.sentry.io/platforms/native/app-hangs.md).

## [Disable NDK Integration](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#disable-ndk-integration)

You can disable the NDK integration by adding the following to your `AndroidManifest.xml`:

```xml
<application>
    <meta-data android:name="io.sentry.ndk.enable" android:value="false" />
</application>
```

## [Using the SDK without the NDK](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#using-the-sdk-without-the-ndk)

You can use Sentry's Android SDK without the Android Native Development Kit (NDK) by either:

* [Disabling the NDK](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#disable-ndk-integration)
* Using `sentry-android-core`, which doesn't contain the NDK and can be used separately instead of `sentry-android`, when adding the dependency. The minimal required API level for `sentry-android-core` is 14.

If you're using our [Gradle plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md), it'll still pull the NDK integration in as part of the auto-installation feature. To disable it, remove the `sentry-android-ndk` dependency from the app configurations in `app/build.gradle`:

```groovy
configurations.configureEach {
  exclude group: "io.sentry", module: "sentry-android-ndk"
}
```

*Other available variations of the above snippet: kotlin*

## [Troubleshooting](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#troubleshooting)

### [Missing Debug Images or Unsymbolicated Stack Traces](https://docs.sentry.io/platforms/android/configuration/using-ndk.md#missing-debug-images-or-unsymbolicated-stack-traces)

Unsymbolicated stack traces may be caused by module-caching on the SDK side. Be sure to clear any existing module cache if your modules are loaded dynamically:

```cpp
// 1. Load a new module
load_my_module();

// 2. Clear the module cache
sentry_clear_modulecache();
```

*Other available variations of the above snippet: kotlin*