--- title: Kotlin Multiplatform Crash Reporting and Error Tracking description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Error Tracking > Frontend Error Tracking > Mobile Crash Reporting > Kotlin Multiplatform Crash Reporting and Error Tracking --- # Kotlin Multiplatform Crash Reporting and Error Tracking ## Overview{% #overview %} Error Tracking processes errors collected from the Kotlin Multiplatform SDK. Enable Kotlin Multiplatform Crash Reporting and Error Tracking to get comprehensive crash reports and error trends. With this feature, you can access: - Aggregated Kotlin Multiplatform crash dashboards and attributes - Deobfuscated Kotlin Multiplatform (iOS and Android) crash reports - Trend analysis with Kotlin Multiplatform error tracking Your crash reports appear in [**Error Tracking**](https://app.datadoghq.com/rum/error-tracking). ## Setup{% #setup %} If you have not set up the Kotlin Multiplatform SDK yet, follow the [in-app setup instructions](https://app.datadoghq.com/rum/application/create) or see the [Kotlin Multiplatform setup documentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/kotlin_multiplatform/setup.md). Then, follow the steps on this page to enable Kotlin Multiplatform Crash Reporting and Error Tracking. **Note**: For any given error, you can access the file path, line number, and a code snippet for each frame of the related stack trace. ### Step 1 - Declare the Kotlin Multiplatform SDK as a dependency{% #step-1---declare-the-kotlin-multiplatform-sdk-as-a-dependency %} Declare [`dd-sdk-kotlin-multiplatform-rum`](https://github.com/DataDog/dd-sdk-kotlin-multiplatform/tree/develop/features/rum) as a common source set dependency in your Kotlin Multiplatform module's `build.gradle.kts` file. ```kotlin kotlin { // declare targets // ... sourceSets { // ... commonMain.dependencies { implementation("com.datadoghq:dd-sdk-kotlin-multiplatform-rum:") } } } ``` ### Step 2 - Add native dependencies{% #step-2---add-native-dependencies %} {% tab title="Android" %} All uncaught exceptions and ANRs resulting in a crash are reported by the Kotlin Multiplatform SDK (see limitations). On top of these crashes, you can configure the SDK to report NDK crashes, and control the reporting of non-fatal ANRs. #### Add NDK crash reporting{% #add-ndk-crash-reporting %} Your Android application may be running native code (C/C++) for performance or code reusability. To enable NDK crash reporting, use the Datadog NDK library. 1. Add the Gradle dependency to your Android source set by declaring the library as a dependency in your `build.gradle.kts` file: ```kotlin kotlin { sourceSets { androidMain.dependencies { implementation("com.datadoghq:dd-sdk-android-ndk:x.x.x") } } } ``` Enable NDK crash collection after initializing the SDK. ```kotlin // in Android source set NdkCrashReports.enable() ``` An "Application Not Responding" ([ANR](https://developer.android.com/topic/performance/vitals/anr)) is an Android-specific type of error that gets triggered when the application is unresponsive for too long. For any Android version, you can override the default setting for reporting non-fatal ANRs by setting `trackNonFatalAnrs` (available from Android source set only) to `true` or `false` when initializing the SDK. For more information, see [Android Crash Reporting and Error Tracking - Add ANR Reporting](https://docs.datadoghq.com/error_tracking/frontend/mobile/android.md?tab=kotlin#step-5---add-anr-reporting). {% /tab %} {% tab title="iOS" %} Kotlin 2.0.20 or higher is required if crash tracking is enabled on iOS. Otherwise, due to the compatibility with `PLCrashReporter`, the application may hang if crash tracking is enabled. All uncaught exceptions resulting in a crash are reported by the Kotlin Multiplatform SDK. Add the following Datadog iOS SDK dependencies, which are needed for the linking step: - `DatadogObjc` - `DatadogCrashReporting` **Note**: Versions of these dependencies should be aligned with the version used by the Datadog Kotlin Multiplatform SDK itself. You can find the complete mapping of iOS SDK versions for each Kotlin Multiplatform SDK release in the [version compatibility guide](https://github.com/DataDog/dd-sdk-kotlin-multiplatform/blob/develop/NATIVE_SDK_VERSIONS.md). #### Adding native iOS dependencies using the CocoaPods plugin{% #adding-native-ios-dependencies-using-the-cocoapods-plugin %} If you are using Kotlin Multiplatform library as a CocoaPods dependency for your iOS application, you can add dependencies as follows: ```kotlin cocoapods { // ... framework { baseName = "sharedLib" } pod("DatadogObjc") { linkOnly = true version = "x.x.x" } pod("DatadogCrashReporting") { linkOnly = true version = "x.x.x" } } ``` #### Adding native iOS dependencies using Xcode{% #adding-native-ios-dependencies-using-xcode %} If you are integrating Kotlin Multiplatform library as a framework with an `embedAndSignAppleFrameworkForXcode` Gradle task as a part of your Xcode build, you can add the necessary dependencies directly in Xcode as follows: 1. Click on your project in Xcode and go to the **Package Dependencies** tab. 1. Add the iOS SDK package dependency by adding `https://github.com/DataDog/dd-sdk-ios.git` as a package URL. 1. Select the version that matches the Kotlin Multiplatform SDK version you're using (see the [version compatibility guide](https://github.com/DataDog/dd-sdk-kotlin-multiplatform/blob/develop/NATIVE_SDK_VERSIONS.md)). 1. Click on the necessary application target and open the **General** tab. 1. Scroll down to the **Frameworks, Libraries, and Embedded Content** section and add the dependencies (`DatadogObjc` and `DatadogCrashReporting`). #### Add app hang reporting{% #add-app-hang-reporting %} App hangs are an iOS-specific type of error that happens when the application is unresponsive for too long. By default, app hang reporting is **disabled**, but you can enable it and set your own threshold to monitor app hangs that last for more than a specified duration by using the `setAppHangThreshold` (available from iOS source set only) initialization method. For more information, see [iOS Crash Reporting and Error Tracking - Add App Hang Reporting](https://docs.datadoghq.com/real_user_monitoring/error_tracking/mobile/ios.md#add-app-hang-reporting). {% /tab %} ### Step 3 - Specify application details in the UI{% #step-3---specify-application-details-in-the-ui %} 1. Navigate to [**Error Tracking** > **Settings** > **Browser and Mobile**](https://app.datadoghq.com/error-tracking/settings/setup/client) and select **Set Up Manually**. 1. Select **Kotlin Multiplatform** as the application type, and enter an **Application Name** to generate a unique Datadog application ID and client token. 1. To disable automatic user data collection for either client IP or geolocation data, uncheck the boxes for those settings. For more information, see [Kotlin Multiplatform Data Collected](https://docs.datadoghq.com/real_user_monitoring/kotlin_multiplatform/data_collected.md). To ensure the safety of your data, you must use a client token. For more information about setting up a client token, see the [Client Token documentation](https://docs.datadoghq.com/account_management/api-app-keys.md#client-tokens). ### Step 4 - Initialize the Datadog SDK{% #step-4---initialize-the-datadog-sdk %} In the initialization snippet, set an environment name. For Android, set a variant name if it exists. For more information, see [Using Tags](https://docs.datadoghq.com/getting_started/tagging/using_tags.md). During initialization, you can also set the tracking consent for GDPR compliance, as described in Advanced Error Tracking Features. {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.eu ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.EU1) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: us3.datadoghq.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.US3) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: us5.datadoghq.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.US5) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.US1_FED) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: us2.ddog-gov.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.US2_FED) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: ap1.datadoghq.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.AP1) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: ap2.datadoghq.com ```kotlin // in common source set fun initializeDatadog(context: Any? = null) { // context should be application context on Android and can be null on iOS val appClientToken = val appEnvironment = val appVariantName = val configuration = Configuration.Builder( clientToken = appClientToken, env = appEnvironment, variant = appVariantName ) .useSite(DatadogSite.AP2) .trackCrashes(true) .build() Datadog.initialize(context, configuration, trackingConsent) } ``` {% /callout %} ## Get deobfuscated stack traces{% #get-deobfuscated-stack-traces %} Mapping files are used to deobfuscate stack traces, which helps in debugging errors. Using a unique build ID that gets generated, Datadog automatically matches the correct stack traces with the corresponding mapping files. This ensures that regardless of when the mapping file was uploaded (either during pre-production or production builds), the correct information is available for efficient QA processes when reviewing crashes and errors reported in Datadog. Use the following guides to see how you can upload mapping files (Android) or dSYMs (iOS) to Datadog: [Android](https://docs.datadoghq.com/real_user_monitoring/error_tracking/mobile/android.md#get-deobfuscated-stack-traces), [iOS](https://docs.datadoghq.com/real_user_monitoring/error_tracking/mobile/ios.md#get-deobfuscated-stack-traces). ## Limitations{% #limitations %} ### File sizing{% #file-sizing %} Mapping files are limited in size to **500 MB** each, while dSYM files are limited to **2 GB**. ### Collection{% #collection %} The SDK handles crash reporting with the following behaviors: - The crash can only be detected after the SDK is initialized. Because of this, Datadog recommends that you initialize the SDK as soon as possible in your application. - Because the Kotlin Multiplatform SDK uses the RUM module to collect crashes, each crash must be attached to a session view. If a crash occurs before a view is visible, or after the app is sent to the background by the end user navigating away from it, the crash is muted and isn't reported for collection. To mitigate this, use the `trackBackgroundEvents()` [method](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/kotlin_multiplatform/advanced_configuration.md#track-background-events) in your `RumConfiguration` builder. - Only crashes that occur in sampled sessions are kept. ## Test your implementation{% #test-your-implementation %} To verify your Kotlin Multiplatform Crash Reporting and Error Tracking configuration, you need to trigger a crash in your application and confirm that the error appears in Datadog. To test your implementation: 1. Run your application on a Kotlin Multiplatform emulator or a real device. 1. Execute some code containing an error or crash. For example: ```kotlin fun onEvent() { throw RuntimeException("Crash the app") } ``` 1. After the crash happens, restart your application and wait for the Kotlin Multiplatform SDK to upload the crash report in [**Error Tracking**](https://app.datadoghq.com/rum/error-tracking). ## Advanced Error Tracking Features{% #advanced-error-tracking-features %} {% collapsible-section %} #### Sending data when device is offline The Datadog SDK ensures availability of data when your user device is offline. In case of low-network areas, or when the device battery is too low, all events are first stored on the local device in batches. Each batch follows the intake specification. They are sent as soon as the network is available, and the battery is high enough to ensure the Datadog SDK does not impact the end user's experience. If the network is not available while your application is in the foreground, or if an upload of data fails, the batch is kept until it can be sent successfully. This means that even if users open your application while offline, no data is lost. To ensure the SDK does not use too much disk space, the data on the disk is automatically discarded if it gets too old. {% /collapsible-section %} {% collapsible-section %} #### Set tracking consent (GDPR compliance) To be compliant with GDPR, the SDK requires the tracking consent value at initialization. Tracking consent can be one of the following values: - `TrackingConsent.PENDING`: (Default) The SDK starts collecting and batching the data but does not send it to the collection endpoint. The SDK waits for the new tracking consent value to decide what to do with the batched data. - `TrackingConsent.GRANTED`: The SDK starts collecting the data and sends it to the data collection endpoint. - `TrackingConsent.NOT_GRANTED`: The SDK does not collect any data. You are not able to manually send any logs, traces, or events. To update the tracking consent value after the SDK is initialized, call `Datadog.setTrackingConsent()`. The SDK changes its behavior according to the new consent. For example, if the current tracking consent value is `TrackingConsent.PENDING` and you update it to: - `TrackingConsent.GRANTED`: The SDK sends all current batched data and future data directly to the data collection endpoint. - `TrackingConsent.NOT_GRANTED`: The SDK wipes all batched data and does not collect any future data. {% /collapsible-section %} ## Further Reading{% #further-reading %} - [Get started with Error Tracking](https://docs.datadoghq.com/real_user_monitoring/error_tracking.md) - [Visualize Error Tracking data in the Explorer](https://docs.datadoghq.com/real_user_monitoring/error_tracking/explorer.md)