Skip to content

Commit 4b00fc4

Browse files
alexandra5000alexandra5000
authored
Move Android troubleshooting into docs-content (#2325)
1 parent 1a616f0 commit 4b00fc4

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎troubleshoot/ingest/opentelemetry/edot-sdks/android/index.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
navigation_title: EDOT Android
3+
description: Use the information in this section to troubleshoot common problems affecting the Elastic Distribution of OpenTelemetry Android.
4+
applies_to:
5+
stack:
6+
serverless:
7+
observability:
8+
product:
9+
edot_android: ga
10+
products:
11+
- id: cloud-serverless
12+
- id: observability
13+
- id: edot-sdk
14+
mapped_pages:
15+
- https://www.elastic.co/guide/en/apm/SDK/android/current/faq.html
16+
---
17+
18+
# Troubleshooting the EDOT Android SDK
19+
20+
Use the information in this section to troubleshoot common problems. As a first step, make sure your stack is compatible with the [supported technologies](opentelemetry://reference/edot-sdks/android/getting-started.md#requirements) for EDOT Android and the OpenTelemetry SDK.
21+
22+
If you have an Elastic support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). If you don't, post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/apm-agent-android/issues).
23+
24+
## General troubleshooting
25+
26+
The SDK creates logs that allow you to see what it's working on and what might have failed at some point. You can find the logs in [logcat](https://developer.android.com/studio/debug/logcat), filtered by the tag `ELASTIC_AGENT`.
27+
28+
For more information about the SDK's internal logs, as well as how to configure them, refer to the [internal logging policy](opentelemetry://reference/edot-sdks/android/configuration.md#internal-logging-policy) configuration.
29+
30+
## Connectivity to the {{stack}}
31+
32+
If after following the [getting started](opentelemetry://reference/edot-sdks/android/getting-started.md) guide and configuring your {{stack}} [endpoint parameters](opentelemetry://reference/edot-sdks/android/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.
33+
34+
### Check out the logs
35+
36+
The SDK 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.
37+
38+
### Inspect network traffic
39+
40+
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 SDK'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.
41+
42+
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.
43+
44+
### SSL/TLS error
45+
46+
Sometimes the request to the {{stack}} endpoint won't show up in the [network inspector](#inspect-network-traffic). A common issue when this happens is that there is an SSL/TLS error that occurs when the SDK 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-ssl) for more information.
47+
48+
## How to configure SSL/TLS? [how-ssl]
49+
50+
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.
51+
52+
### Connecting to Elastic Cloud [how-ssl-elastic-cloud]
53+
54+
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.
55+
56+
### Connecting to an on-prem server [how-ssl-on-prem]
57+
58+
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).
59+
60+
### Debugging purposes [how-ssl-debug]
61+
62+
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:
63+
64+
```xml
65+
<application
66+
...
67+
android:usesCleartextTraffic="true">
68+
...
69+
</application>
70+
```
71+
72+
::::{note}
73+
You should only enable cleartext traffic for debugging purposes and not for production code.
74+
::::
75+
76+
If enabling cleartext traffic isn’t a valid option for your debugging use case, you should refer to Android’s guide on [configuring CAs for debugging](https://developer.android.com/privacy-and-security/security-config#TrustingDebugCa).
77+
78+
For more information on how Android handles network security, please refer to the official [Android docs](https://developer.android.com/privacy-and-security/security-ssl).
79+
80+
## Desugaring support [why-desugaring]
81+
82+
Android devices with an API level below 26 (older than [Android 8.0](https://developer.android.com/about/versions/oreo/android-8.0)) have limited support for Java 8 features and types, which can cause your app to crash when using those types while running on those older-than-8.0 devices.
83+
84+
For example, if one of your app's dependencies uses the [Base64](https://docs.oracle.com/javase/8/docs/api/java/util/Base64.html) type ([added in API level 26](https://developer.android.com/reference/java/util/Base64)), and your app is installed on an Android device with OS version 7.0 ([API level 24](https://developer.android.com/about/versions/nougat/android-7.0)), a crash will happen when the code that uses said type is executed due to a "class not found" error.
85+
86+
To prevent these kinds of issues on devices using Android OS older than 8.0, you must add [Java 8 desugaring support](https://developer.android.com/studio/write/java8-support#library-desugaring) to your app. This requirement is inherited from the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#language-version-compatibility), which this project is built upon, where several of the unsupported types for Android versions older than 8.0 are used.
87+
88+
## App referred to as service [why-service]
89+
90+
For historic reasons, `service` has been the default way of referring to "an entity that produces telemetry". This term made its way into OpenTelemetry to a point where it was marked as one of the first "stable" resource names, meaning that it was no longer possible/feasible to make a change to another name that would better represent any kind of telemetry source. This has been debated several times within the community. A recent discussion attempts to [explain the `service` description](https://github.com/open-telemetry/semantic-conventions/pull/630) and what it should represent in an effort to reduce confusion. However, there doesn't seem to be a consensus.
91+
92+
## Get your Android application instance [get-application]
93+
94+
Your [Application](https://developer.android.com/reference/android/app/Application) instance is needed to initialize the agent. There are a couple of ways you can get yours.
95+
96+
#### From within your custom Application implementation (Recommended)
97+
98+
The agent should get initialized as soon as your application is launched to make sure that it can start collecting telemetry from the very beginning.
99+
100+
An ideal place to do so is from within your own custom [Application.onCreate](https://developer.android.com/reference/android/app/Application#onCreate()) method implementation, as shown in the following snippet:
101+
102+
```kotlin
103+
package my.app
104+
105+
class MyApp : Application() {
106+
override fun onCreate() {
107+
super.onCreate()
108+
val agent = ElasticApmAgent.builder(this) // <1>
109+
//...
110+
.build()
111+
}
112+
}
113+
```
114+
1. `this` is your application.
115+
116+
:::{important}
117+
You must register your custom application in your `AndroidManifest.xml` file, like so:
118+
119+
```xml
120+
<?xml version="1.0" encoding="utf-8"?>
121+
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
122+
<application
123+
android:name="my.app.MyApp"
124+
...
125+
</application>
126+
</manifest>
127+
```
128+
:::
129+
130+
### From an Activity
131+
132+
You can get your application from an [Activity](https://developer.android.com/reference/android/app/Activity) by calling its [getApplication()](https://developer.android.com/reference/android/app/Activity#getApplication()) method.
133+
134+
### From a Fragment
135+
136+
From a [Fragment](https://developer.android.com/reference/androidx/fragment/app/Fragment.html) instance, you can get the [Activity](https://developer.android.com/reference/android/app/Activity) that it is associated to by calling its [requireActivity()](https://developer.android.com/reference/androidx/fragment/app/Fragment.html#requireActivity()) method. After you get the Activity object, you can get your application from it as [explained above](#from-an-activity).
137+
138+
## Get your {{stack}} export endpoint [get-export-endpoint]
139+
140+
The export endpoint is where your app's telemetry is sent. The endpoint is required to initialize the agent. The way to find the endpoint in your {{stack}} depends on the type of deployment you use.
141+
142+
### Serverless deployments
143+
144+
On a [Serverless deployment](https://www.elastic.co/guide/en/serverless/current/intro.html), follow these steps:
145+
146+
1. Open {{kib}} and find **Add data** in the main menu. Alternatively, you can use the [global search field](../../../../../explore-analyze/find-and-organize/find-apps-and-objects.md) and search for `Observability Onboarding`.
147+
2. Select **Application**, **OpenTelemetry**.
148+
3. Select the **OpenTelemetry** tab, followed by **Managed OTLP Endpoint** under **Configure the OpenTelemetry SDK**.
149+
150+
Your export endpoint URL is the value for the `OTEL_EXPORTER_OTLP_ENDPOINT` configuration setting.
151+
152+
### Cloud hosted and self-managed deployments
153+
154+
For Elastic Cloud Hosted (ECH) and self-managed deployments, the export endpoint, also known as [EDOT Collector](opentelemetry://reference/edot-collector/index.md), is not available out of the box at the moment. You can still create your own service by [downloading](opentelemetry://reference/edot-collector/download.md) and [configuring an EDOT Collector](opentelemetry://reference/edot-collector/config/default-config-standalone.md#gateway-mode).
155+
156+
## Create an API key [create-api-key]
157+
158+
API keys are the recommended way of authenticating the agent with your {{stack}}. There's a couple of ways you can create one.
159+
160+
### Use {{kib}}'s Applications UI
161+
162+
Follow [this quick guide](../../../../../solutions/observability/apm/api-keys.md#apm-create-an-api-key) and leave all the settings with their default values.
163+
164+
### Use REST APIs
165+
166+
Follow [this guide](https://www.elastic.co/docs/api/doc/kibana/operation/operation-createagentkey) to create an API Key with a set of privileges that are scoped for the APM Agent use case only.
167+

‎troubleshoot/ingest/opentelemetry/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ toc:
88
- file: edot-collector/metadata.md
99
- file: edot-sdks/index.md
1010
children:
11+
- file: edot-sdks/android/index.md
1112
- file: edot-sdks/dotnet/index.md
1213
- file: edot-sdks/java/index.md
1314
children:

0 commit comments

Comments
 (0)