Adding troubleshooting.md

docs/reference/how-tos.md

@@ -188,19 +188,19 @@ fun myMethod() {
 
 1. There might be multiple `BuildConfig` types available to use in your code. The one that belongs to your app has a package name equal to your [app's namespace](https://developer.android.com/build/configure-app-module#set-namespace) value. So, for example, if your app's namespace is set to `com.my.app`, then the `BuildConfig` type you must use would be `com.my.app.BuildType`.
 
-## How to configure SSL/TLS? [faq-ssl]
+## How to configure SSL/TLS? [how-ssl]
 
 Note that the Elastic Agent does not handle SSL/TLS configs internally. Therefore, you should manage these types of configurations as part of your app’s network security configurations, as explained in Android’s official [security guidelines](https://developer.android.com/privacy-and-security/security-ssl). Below we show a set of common use cases and quick tips on what could be done on each one. However, each case might be different, so please refer to Android’s [official docs](https://developer.android.com/privacy-and-security/security-config) on this topic if you need more details.
 
-### Connecting to Elastic Cloud [faq-ssl-elastic-cloud]
+### Connecting to Elastic Cloud [how-ssl-elastic-cloud]
 
 If your {{stack}} is hosted in {{ecloud}}, you shouldn’t need to add any SSL/TLS config changes in your app. It should work out of the box.
 
-### Connecting to an on-prem server [faq-ssl-on-prem]
+### Connecting to an on-prem server [how-ssl-on-prem]
 
 If your {{stack}} is hosted on-prem, then it depends on the type of CA your host uses to sign its certificates. If it’s a commonly trusted CA, you shouldn’t have to worry about changing your app’s SSL/TLS configuration as it all should work well out of the box. However, if your CAs are unknown/private or your server uses a self-signed certificate, then you would need to configure your app to trust custom CAs by following [Android’s guide](https://developer.android.com/privacy-and-security/security-config).
 
-### Debugging purposes [faq-ssl-debug]
+### Debugging purposes [how-ssl-debug]
 
 If you’re running a local server and need to connect to it without using https in order to run a quick test, then you could temporarily [enable cleartext traffic](https://developer.android.com/guide/topics/manifest/application-element#usesCleartextTraffic) within your `AndroidManifest.xml` file, inside the `<application>` tag. As shown below:
 

docs/reference/toc.yml

@@ -6,3 +6,4 @@ toc:
   - file: automatic-instrumentation.md
   - file: faq.md
   - file: how-tos.md
+  - file: troubleshooting.md

docs/reference/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+## General
+
+The agent creates logs that enable you to see what it is working on and what might have failed at some point. You can find those in [logcat](https://developer.android.com/studio/debug/logcat), filtered by the tag `ELASTIC_AGENT`.
+
+For more information about the agent's internal logs, as well as how to configure them, refer to the [internal logging policy](configuration.md#internal-logging-policy) configuration.
+
+## Connectivity to the {{stack}}
+
+If after following the [getting started](getting-started.md) guide and configuring your {{stack}} [endpoint parameters](configuration.md#export-connectivity), you can't see your application's data in {{kib}}, you can follow the following tips to try and figure out what could be wrong.
+
+### Checking out logs
+
+The agent prints debug logs, which can be seen in [logcat](https://developer.android.com/studio/debug/logcat), using the tag `ELASTIC_AGENT`, where you can have a look at your endpoint configuration parameters with a log that reads: _"Initializing connectivity with config [your endpoint configuration]"_. Take a look at those and make sure that the provided configuration matches your {{stack}} endpoint parameters.
+
+### Inspecting network traffic
+
+You can take a look at your app's outgoing network requests via Android Studio's [network inspector tool](http://developer.android.com/studio/debug/network-profiler). This tool can show you the agent's export requests, where you can see if they were successful or not, as well as the request body and the {{stack}} response body for when you need more details of the whole process. Apart from that, this tool also provides a way to export a file with the information of all of your app's HTTP requests, which you could share with our support team if needed.
+
+### SSL/TLS error
+
+Sometimes the request to the {{stack}} endpoint won't show up in the [network inspector](#inspecting-network-traffic). A common issue when this happens is that there is an SSL/TLS error that occurs when the agent tries to contact your {{stack}} endpoint. This is often the case when you work with an on-prem {{stack}} that doesn't have trusted CAs, for which you'd need to add custom security configurations to your app to make the export work. Take a look at [how to configure SSL/TLS](how-tos.md#how-ssl) for more information.