Skip to content

Commit

Permalink
Merge pull request #96 from DataDog/alai97/android-error-tracking-doc…
Browse files Browse the repository at this point in the history 
…-updates

DOCS-2578 Track Android Errors Edits
  • Loading branch information
@alai97
alai97 authored Jul 20, 2022
2 parents 07ce5a5 + 34b3895 commit fe4a389
Showing 1 changed file with 84 additions and 61 deletions.
145 changes: 84 additions & 61 deletions docs/upload_mapping_file.md
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,98 @@
## Overview

Error Tracking processes errors collected from the Android SDK. To quickly get started with error tracking download the latest version of [dd-sdk-android][1].
Error Tracking processes errors collected from the RUM Android SDK.

If your mobile Android source code is obfuscated, upload your Proguard/R8 mapping file to Datadog so that your different stack traces can be deobfuscated. For a given error, you can get access to the file path, the line number, as well as a code snippet for each frame of the related stack trace.
Enable Android Crash Reporting and Error Tracking to get comprehensive crash reports and error trends with Real User Monitoring. With this feature, you can access:

- Aggregated Android crash dashboards and attributes
- Deobfuscated Android crash reports
- Trend analysis with Android error tracking

Your crash reports appear in [**Error Tracking**][1].

## Setup

If you have not set up the Android SDK yet, follow the [in-app setup instructions][2] or see the [Android RUM setup documentation][3].

1. Add the latest version of the [RUM Android SDK][4] to your Gradle dependencies.
2. Configure your application's `env` and `variant` when [initializing the SDK][5].
3. Run the Gradle task to upload your Proguard/R8 mapping file to Datadog in order to access deobfuscated stack traces.

For any given error, you can access the file path, line number, and a code snippet for each frame of the related stack trace.

## Upload your mapping file

{{< tabs >}}
{{% tab "US" %}}

1. Add the [Gradle Plugin][1] to your Gradle project, using the following snippet.
1. Add the [Android Gradle Plugin][1] to your Gradle project using the following code snippet.

```groovy
// In your app's build.gradle script
plugins {
id("com.datadoghq.dd-sdk-android-gradle-plugin") version "x.y.z"
}
```
```groovy
// In your app's build.gradle script
plugins {
id("com.datadoghq.dd-sdk-android-gradle-plugin") version "x.y.z"
}
```

2. [Create a new and dedicated Datadog API key][2] and export it as an environment variable named `DD_API_KEY` (alternatively you can pass it as a task property).
3. (Optional) Configure the plugin to upload files to the EU region by exporting two additional environment variables: `export DATADOG_SITE="datadoghq.eu"` and `export DATADOG_API_HOST="api.datadoghq.eu"`.
4. Run the upload task after your obfuscated APK has been built:
```bash
./gradlew uploadMappingRelease
```
**Note**: If your project uses additional flavors, the plugin provides an upload task for each variant with obfuscation enabled. In this case, initialize SDK with a proper variant name (the necessary API is available since version `1.8.0`).
2. [Create a dedicated Datadog API key][2] and export it as an environment variable named `DD_API_KEY` (alternatively, pass it as a task property).
3. Optionally, configure the plugin to upload files to the EU region by configuring the plugin in your `build.gradle` script:

```
datadog {
site = "EU1"
}
```

4. Run the upload task after your obfuscated APK builds:

```bash
./gradlew uploadMappingRelease
```

**Note**: If your project uses additional flavors, the plugin provides an upload task for each variant with obfuscation enabled. In this case, initialize the RUM Android SDK with a proper variant name (the necessary API is available in versions `1.8.0` and later).

[1]: /~https://github.com/DataDog/dd-sdk-android-gradle-plugin
[2]: https://app.datadoghq.com/account/settings#api

{{% /tab %}}
{{% tab "EU" %}}
1. Add the [Gradle Plugin][1] to your Gradle project, using the following snippet.
1. Add the [Android Gradle Plugin][1] to your Gradle project using the following code snippet.

```groovy
// In your app's build.gradle script
plugins {
id("com.datadoghq.dd-sdk-android-gradle-plugin") version "x.y.z"
}
```
```groovy
// In your app's build.gradle script
plugins {
id("com.datadoghq.dd-sdk-android-gradle-plugin") version "x.y.z"
}
```

2. [Create a new and dedicated Datadog API key][2] and export it as an environment variable named `DD_API_KEY` (alternatively you can pass it as a task property).
2. [Create a dedicated Datadog API key][2] and export it as an environment variable named `DD_API_KEY` (alternatively, pass it as a task property).
3. Configure the plugin to use the EU region by adding the following snippet in your app's `build.gradle` script file:

```groovy
datadog {
site = "EU"
}
```
4. Run the upload task after your obfuscated APK has been built:
```bash
./gradlew uploadMappingRelease
```
**Note**: If your project uses additional flavors, the plugin provides an upload task for each variant with obfuscation enabled. In this case, initialize SDK with a proper variant name (the necessary API is available since version `1.8.0`).
```groovy
datadog {
site = "EU1"
}
```

4. Run the upload task after your obfuscated APK builds:

```bash
./gradlew uploadMappingRelease
```

**Note**: If your project uses additional flavors, the plugin provides an upload task for each variant with obfuscation enabled. In this case, initialize the RUM Android SDK with a proper variant name (the necessary API is available in versions `1.8.0` and later).

[1]: /~https://github.com/DataDog/dd-sdk-android-gradle-plugin
[2]: https://app.datadoghq.com/account/settings#api

{{% /tab %}}
{{< /tabs >}}

### Plugin Configuration Options

There are several plugin properties that can be configured through the plugin extension. In case you are using multiple variants you can set a property value for a specific flavour in the variant.
There are several plugin properties that can be configured through the plugin extension. In case you are using multiple variants, you can set a property value for a specific flavor in the variant.

**Example:**

For a variant `fooBarRelease` you could have the following configuration:
For example, for a `fooBarRelease` variant, you can use the following configuration:

```groovy
datadog {
Expand All @@ -81,19 +108,23 @@ datadog {
}
```

The task config for this variant will be merged from all the 3 provided flavours configs in the
following order: `bar` -> `foo` -> `fooBar` which will resolve the final value for the `versionName`
property as : `fooBar`
The task configuration for this variant is merged from all three flavor configurations provided in the following order:

1. `bar`
2. `foo`
3. `fooBar`

This resolves the final value for the `versionName` property as `fooBar`.

| Property name | Description |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `versionName` | The version name of the application. |
| `serviceName` | The service name of the application. |
| `site` | The Datadog site to upload your data to (one of "US", "EU", "GOV"). |
| `remoteRepositoryUrl` | The url of the remote repository where the source code was deployed. If not provided this value will be resolved from your current GIT configuration during the task execution time. |
| `checkProjectDependencies` | This property controls if plugin should check if Datadog SDK is included in the dependencies and if it is not: "none" - ignore, "warn" - log a warning, "fail" - fail the build with an error (default). |
| `versionName` | The version name of the application (by default, the version declared in the `android` block of your `build.gradle` script). |
| `serviceName` | The service name of the application (by default, the package name of your application as declared in the `android` block of your `build.gradle` script). |
| `site` | The Datadog site to upload your data to (US1, US3, US5, EU1, or US1_FED). |
| `remoteRepositoryUrl` | The URL of the remote repository where the source code was deployed. If this is not provided, this value is resolved from your Git configuration during the task execution time. |
| `checkProjectDependencies` | This property controls if the plugin should check if the Datadog Android SDK is included in the dependencies. If not, "none" is ignored, "warn" logs a warning, and "fail" fails the build with an error (default). |

### Integration with CI/CD pipeline
### Integrate with a CI/CD pipeline

By default, the upload mapping task is independent from other tasks in the build graph. Run the task manually when you need to upload mapping.

Expand All @@ -105,20 +136,12 @@ For example:
tasks["minify${variant}WithR8"].finalizedBy { tasks["uploadMapping${variant}"] }
```

## Troubleshoot errors

An obfuscated stack trace is not helpful as you don't have access to the class name, file path and the line number. It's hard to know where something is happening in your code base. In addition, the code snippet is still minified (one long line of transformed code) which makes the troubleshooting process even harder. See below an example of an minified stack trace:

![image_obfuscated][2]

On the contrary, a deobfuscated stack trace gives you all the context you need for troubleshooting:

![image_deobfuscated][3]

[1]: /~https://github.com/DataDog/dd-sdk-android
[2]: https://raw.githubusercontent.com/DataDog/dd-sdk-android-gradle-plugin/main/docs/images/obfuscated_stacktrace.png
[3]: https://raw.githubusercontent.com/DataDog/dd-sdk-android-gradle-plugin/main/docs/images/deobfuscated_stacktrace.png

## Further Reading

{{< partial name="whats-next/whats-next.html" >}}

[1]: https://app.datadoghq.com/rum/error-tracking
[2]: https://app.datadoghq.com/rum/application/create
[3]: https://docs.datadoghq.com/real_user_monitoring/android/#setup
[4]: /~https://github.com/DataDog/dd-sdk-android
[5]: https://docs.datadoghq.com/real_user_monitoring/android/advanced_configuration/?tabs=kotlin#initialization-parameters

0 comments on commit fe4a389

Please sign in to comment.