From bae49b3ddd05e6ad57fe0394e082f4ed3683b09c Mon Sep 17 00:00:00 2001
From: Xavier Gouchet <xavier.gouchet@gmail.com>
Date: Mon, 30 Mar 2020 10:12:39 +0200
Subject: [PATCH] :pencil: (RUMM-306): Create Troublshooting document

---
 README.md               |  6 ++++++
 docs/TROUBLESHOOTING.md | 47 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 docs/TROUBLESHOOTING.md

diff --git a/README.md b/README.md
index 6afecc82d0..ecf0734495 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,12 @@ When you open your console in Datadog, navigate to the Logs section. In the sear
 
 ![Datadog Mobile Logs](docs/images/screenshot.png)
 
+## Troubleshooting
+
+If you encounter any issue when using the Datadog SDK for Android, please take a look at 
+the [troubleshooting checklist](docs/TROUBLESHOOTING.md), or at 
+the existing [issues](https://github.com/DataDog/dd-sdk-android/issues?q=is%3Aissue).
+
 ## Contributing
 
 Pull requests are welcome. First, open an issue to discuss what you would like to change. For more information, read the [Contributing Guide](CONTRIBUTING.md).
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..cf0592ba85
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,47 @@
+# Troubleshooting
+
+## Compilation issues
+
+### Manifest merger failed
+
+> Manifest merger failed : Attribute application@appComponentFactory value=(android.support.v4.app.CoreComponentFactory) from [com.android.support:support-compat:28.0.0] AndroidManifest.xml:22:18-91 is also present at [androidx.core:core:1.0.0] AndroidManifest.xml:22:18-86 value=(androidx.core.app.CoreComponentFactory).
+> Suggestion: add 'tools:replace="android:appComponentFactory"' to <application> element at AndroidManifest.xml:7:5-14:19 to override.
+
+The Datadog SDK for Android uses some AndroidX artifacts. Make sure you’re using AndroidX dependencies too (you can easily migrate your code to AndroidX using the `Refactor > Migrate to AndroidX` menu in Android Studio).
+
+You also need to set the `android.useAndroidX` and `android.enableJetifier` properties to `true` in your project’s `gradle.properties` file.
+
+### Duplicate class com.google.common.util.concurrent.ListenableFuture
+
+
+> Duplicate class com.google.common.util.concurrent.ListenableFuture found in modules jetified-guava-jdk5-17.0.jar (com.google.guava:guava-jdk5:17.0) and jetified-listenablefuture-1.0.jar (com.google.guava:listenablefuture:1.0)
+
+The Datadog SDK for Android uses AndroidX's WorkManager, which depends on a specific Guava dependency. If your own dependencies rely on different Guava artifacts, this issue can occur. It can easily be solved by excluding the conflicting module from your dependency, eg: 
+
+```
+implementation ("com.datadoghq:dd-sdk-android:1.3.0") {
+    exclude group: 'com.google.guava', module: 'listenablefuture'
+}
+```
+
+### Other
+
+If you encounter another issue when building your application with the Datadog SDK for Android, you can [open an issue](https://github.com/DataDog/dd-sdk-android/issues/new?assignees=&labels=bug&template=bug_report.md&title=), and give us as many details as you can.
+
+
+## Feature issues
+
+### Foreword
+
+If you think the SDK does not behave as it should, make sure you set the library's verbosity before running your application, as follow. It'll print relevant error messages in the Logcat that can help you locate the source of the problem.
+
+```kotlin
+    Datadog.setVerbosity(Log.VERBOSE)
+```
+
+### Logs/Traces are not appearing in your dashboard.
+
+Make sure that you initialize the SDK using a valid Client Token. 
+When the library's logs are enabled, you'll see the following message in the logcat :
+ 
+> Unable to send batch because your token is invalid. Make sure that the provided token still exists.