[apm] Update content related to mobile APM agents for GA (#3507) (#3543)

* first pass at cleaning up apm agent mobile content * address feedback * clean up (cherry picked from commit 5853e1e) Co-authored-by: Colleen McGinnis <[email protected]>
elastic · Jan 12, 2024 · c69919b · c69919b
1 parent c71003e
commit c69919b
Show file tree

Hide file tree

Showing 17 changed files with 169 additions and 15 deletions.
diff --git a/docs/en/observability/apm/agent-server-compatibility.asciidoc b/docs/en/observability/apm/agent-server-compatibility.asciidoc
@@ -10,14 +10,18 @@ The chart below outlines the compatibility between different versions of Elastic
 .1+|**APM AWS Lambda extension**
 |`1.x` |≥ `8.2`
 
+// Android
+.1+|**Android agent**
+|`0.x` |≥ `8.12`
+
 // Go
 .2+|**Go agent**
 |`1.x` |≥ `6.5`
 |`2.x` |≥ `6.5`
 
 // iOS
 .1+|**iOS agent**
-|`0.x` |≥ `7.14`
+|`1.x` |≥ `8.12`
 
 // Java
 .1+|**Java agent**
@@ -48,4 +52,5 @@ The chart below outlines the compatibility between different versions of Elastic
 .2+|**JavaScript RUM agent**
 |`4.x` |≥ `6.5`
 |`5.x` |≥ `7.0`
+
 |====
diff --git a/docs/en/observability/apm/anonymous-auth.asciidoc b/docs/en/observability/apm/anonymous-auth.asciidoc
@@ -15,7 +15,7 @@ The APM Server's default response to these these requests depends on its configu
 In some cases, however, it makes sense to allow both authenticated and anonymous requests.
 For example, it isn't possible to authenticate requests from front-end services as
 the secret token or API key can't be protected. This is the case with the Real User Monitoring (RUM)
-agent running in a browser, or the iOS/Swift agent running in a user application.
+agent running in a browser, or the Android or iOS/Swift agent running in a user application.
 However, you still likely want to authenticate requests from back-end services.
 To solve this problem, you can enable anonymous authentication in the APM Server to allow the
 ingestion of unauthenticated client-side APM data while still requiring authentication for server-side services.

diff --git a/docs/en/observability/apm/api-keys.asciidoc b/docs/en/observability/apm/api-keys.asciidoc
@@ -98,9 +98,11 @@ image::images/apm-ui-api-key.png[{apm-app} API key]
 You can now apply your newly created API keys in the configuration of each of your APM agents.
 See the relevant agent documentation for additional information:
 
-// Not relevant for RUM and iOS
+// Not relevant for RUM
+* *Android*: {apm-android-ref}/configuration.html[`apiKey`]
 * *Go agent*: {apm-go-ref}/configuration.html#config-api-key[`ELASTIC_APM_API_KEY`]
 * *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-api-key[`ApiKey`]
+* *iOS*: {apm-ios-ref}/configuration.html#withApiKey[`withApiKey`]
 * *Java agent*: {apm-java-ref}/config-reporter.html#config-api-key[`api_key`]
 * *Node.js agent*: {apm-node-ref}/configuration.html#api-key[`apiKey`]
 * *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-api-key[`api_key`]

diff --git a/docs/en/observability/apm/apm-server-down.asciidoc b/docs/en/observability/apm/apm-server-down.asciidoc
@@ -14,6 +14,7 @@ Some agents have internal queues or buffers that will temporarily store data if
 As a general rule of thumb, queues fill up quickly. Assume data will be lost if APM Server goes down.
 Adjusting these queues/buffers can increase the agent's overhead, so use caution when updating default values.
 
+// * **Android agent** - ??
 * **Go agent** - Circular buffer with configurable size:
 {apm-go-ref}/configuration.html#config-api-buffer-size[`ELASTIC_APM_BUFFER_SIZE`].
 // * **iOS agent** - ??

diff --git a/docs/en/observability/apm/configure/anonymous-auth.asciidoc b/docs/en/observability/apm/configure/anonymous-auth.asciidoc
@@ -14,7 +14,7 @@ Most options on this page are supported by all APM Server deployment methods.
 Elastic APM agents can send unauthenticated (anonymous) events to the APM Server.
 An event is considered to be anonymous if no authentication token can be extracted from the incoming request.
 This is useful for agents that run on clients, like the Real User Monitoring (RUM)
-agent running in a browser, or the iOS/Swift agent running in a user application.
+agent running in a browser, or the Android or iOS/Swift agent running in a user application.
 
 Enable anonymous authentication in the APM Server to allow the
 ingestion of unauthenticated client-side APM data while still requiring authentication for server-side services.

diff --git a/docs/en/observability/apm/data-model.asciidoc b/docs/en/observability/apm/data-model.asciidoc
@@ -50,6 +50,7 @@ When this occurs, the {apm-app} will display the number of spans dropped.
 
 To configure the number of spans recorded per transaction, see the relevant Agent documentation:
 
+* Android: _Not yet supported_
 * Go: {apm-go-ref-v}/configuration.html#config-transaction-max-spans[`ELASTIC_APM_TRANSACTION_MAX_SPANS`]
 * iOS: _Not yet supported_
 * Java: {apm-java-ref-v}/config-core.html#config-transaction-max-spans[`transaction_max_spans`]

diff --git a/docs/en/observability/apm/getting-started-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm-server.asciidoc
@@ -453,6 +453,7 @@ See the <<directory-layout,deb & rpm default paths>> for a full directory layout
 // Use a tagged region to pull APM Agent information from the APM Overview
 If you haven't already, you can now install APM Agents in your services!
 
+* {apm-android-ref-v}/intro.html[Android agent]
 * {apm-go-ref-v}/introduction.html[Go agent]
 * {apm-ios-ref-v}/intro.html[iOS agent]
 * {apm-java-ref-v}/intro.html[Java agent]

diff --git a/docs/en/observability/apm/release-notes.asciidoc b/docs/en/observability/apm/release-notes.asciidoc
@@ -19,6 +19,7 @@ See the {kibana-ref}/release-notes.html[Kibana release notes].
 
 **APM agents**
 
+* {apm-android-ref-v}/release-notes.html[Android agent]
 * {apm-go-ref-v}/release-notes.html[Go agent]
 * {apm-ios-ref-v}/release-notes.html[iOS agent]
 * {apm-java-ref-v}/release-notes.html[Java agent]

diff --git a/docs/en/observability/apm/secret-token.asciidoc b/docs/en/observability/apm/secret-token.asciidoc
@@ -32,6 +32,7 @@ include::{apm-server-dir}/tab-widgets/secret-token-widget.asciidoc[]
 
 Each Elastic {apm-agent} has a configuration option to set the value of the secret token:
 
+* *Android agent*: {apm-android-ref-v}/configuration.html#secretToken[`secretToken`]
 * *Go agent*: {apm-go-ref}/configuration.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`]
 * *iOS agent*: {apm-ios-ref-v}/configuration.html#secretToken[`secretToken`]
 * *Java agent*: {apm-java-ref}/config-reporter.html#config-secret-token[`secret_token`]

diff --git a/docs/en/observability/apm/tab-widgets/distributed-trace-receive-widget.asciidoc b/docs/en/observability/apm/tab-widgets/distributed-trace-receive-widget.asciidoc
@@ -3,10 +3,17 @@
 ++++
 <div class="tabs" data-tab-group="apm-agent-distributed-trace">
   <div role="tablist" aria-label="dt">
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="android-tab-dt-r"
+            id="android-dt-r">
+      Android
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="go-tab-dt-r"
-            id="go-dt-r">
+            id="go-dt-r"
+            tabindex="-1">
       Go
     </button>
     <button role="tab"
@@ -59,6 +66,17 @@
       Ruby
     </button>
   </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="android-tab-dt-r"
+       aria-labelledby="android-dt-r"
+       hidden="">
+++++
+
+include::distributed-trace-receive.asciidoc[tag=android]
+
+++++
+  </div>
   <div tabindex="0"
        role="tabpanel"
        id="go-tab-dt-r"

diff --git a/docs/en/observability/apm/tab-widgets/distributed-trace-receive.asciidoc b/docs/en/observability/apm/tab-widgets/distributed-trace-receive.asciidoc
@@ -1,3 +1,9 @@
+// tag::android[]
+
+_Not applicable._
+
+// end::android[]
+
 // tag::go[]
 
 // Need help with this example
@@ -35,8 +41,6 @@ transaction := apm.DefaultTracer().StartTransactionOptions("GET /", "request", o
 
 // tag::ios[]
 
-experimental::[]
-
 _Not applicable._
 
 // end::ios[]

diff --git a/docs/en/observability/apm/tab-widgets/distributed-trace-send-widget.asciidoc b/docs/en/observability/apm/tab-widgets/distributed-trace-send-widget.asciidoc
@@ -3,10 +3,17 @@
 ++++
 <div class="tabs" data-tab-group="apm-agent-distributed-trace">
   <div role="tablist" aria-label="dt">
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="android-tab-dt"
+            id="android-dt">
+      Android
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="go-tab-dt"
-            id="go-dt">
+            id="go-dt"
+            tabindex="-1">
       Go
     </button>
     <button role="tab"
@@ -59,6 +66,17 @@
       Ruby
     </button>
   </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="android-tab-dt"
+       aria-labelledby="android-dt"
+       hidden="">
+++++
+
+include::distributed-trace-send.asciidoc[tag=android]
+
+++++
+  </div>
   <div tabindex="0"
        role="tabpanel"
        id="go-tab-dt"

diff --git a/docs/en/observability/apm/tab-widgets/distributed-trace-send.asciidoc b/docs/en/observability/apm/tab-widgets/distributed-trace-send.asciidoc
@@ -1,3 +1,10 @@
+// tag::android[]
+
+_Not applicable._
+
+// end::android[]
+
+
 // tag::go[]
 
 1. Start a transaction with
@@ -29,8 +36,6 @@ tracestate := traceContext.State.String()
 
 // tag::ios[]
 
-experimental::[]
-
 The agent will automatically inject trace headers into network requests using `URLSessions`, but if you're using a non-standard network library you may need to manually inject them. It will be done using the OpenTelemetry APIs:
 
 1. Create a `Setter`
@@ -39,7 +44,7 @@ The agent will automatically inject trace headers into network requests using `U
 
 3. Inject trace context to header dictionary
 
-4. Follow the procedure of your network library to complete the network request. Make sure to call `span.end()` when the request succeeds or fails.  
+4. Follow the procedure of your network library to complete the network request. Make sure to call `span.end()` when the request succeeds or fails.
 
 [source,swift]
 ----
@@ -52,7 +57,7 @@ struct BasicSetter: Setter { <1>
     }
 }
 
-let span : Span = ... <2> 
+let span : Span = ... <2>
 let setter = BasicSetter()
 let propagator = W3CTraceContextPropagator()
 var headers = [String:String]()

diff --git a/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc b/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc
@@ -3,10 +3,17 @@
 ++++
 <div class="tabs" data-tab-group="apm-agent">
   <div role="tablist" aria-label="Install">
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="android-tab-install"
+            id="android-install">
+      Android
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="go-tab-install"
-            id="go-install">
+            id="go-install"
+            tabindex="-1">
       Go
     </button>
     <button role="tab"
@@ -73,6 +80,17 @@
       OpenTelemetry
     </button>
   </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="android-tab-install"
+       aria-labelledby="android-install"
+       hidden="">
+++++
+
+include::install-agents.asciidoc[tag=android]
+
+++++
+  </div>
   <div tabindex="0"
        role="tabpanel"
        id="go-tab-install"

diff --git a/docs/en/observability/apm/tab-widgets/install-agents.asciidoc b/docs/en/observability/apm/tab-widgets/install-agents.asciidoc
@@ -1,3 +1,79 @@
+// tag::android[]
+*Add the agent to your project*
+
+First, add the https://plugins.gradle.org/plugin/co.elastic.apm.android[Elastic APM agent plugin] to your application's `build.gradle` file as shown below:
+
+[source,groovy]
+----
+// Android app's build.gradle file
+plugins {
+    id "com.android.application"
+    id "co.elastic.apm.android" version "[latest_version]" <1>
+}
+----
+<1> The Elastic plugin declaration must be added below the Android app plugin declaration (`com.android.application`) and below the Kotlin plugin declaration (if used).
+
+*Configure the agent*
+
+After adding the agent plugin, configure it.
+A minimal configuration sets the Elastic APM Server endpoint as shown below:
+
+[source,groovy]
+----
+// Android app's build.gradle file
+plugins {
+    //...
+    id "co.elastic.apm.android" version "[latest_version]" <1>
+}
+
+elasticApm {
+    // Minimal configuration
+    serverUrl = "https://your.elastic.server"
+
+    // Optional
+    serviceName = "your app name" <2>
+    serviceVersion = "0.0.0" <3>
+    apiKey = "your server api key" <4>
+    secretToken = "your server auth token" <5>
+}
+----
+<1> You can find the latest version in the https://plugins.gradle.org/plugin/co.elastic.apm.android[Gradle plugin portal].
+<2> Defaults to your `android.defaultConfig.applicationId` value.
+<3> Defaults to your `android.defaultConfig.versionName` value.
+<4> Defaults to null.
+More info on API Keys {ref}/security-api-create-api-key.html[here].
+<5> Defaults to null.
+
+NOTE: When both `secretToken` and `apiKey` are provided, apiKey has priority and secretToken is ignored.
+
+*Initialize the agent*
+
+After syncing your project with the Gradle changes above, the Elastic APM agent needs to be initialized within your https://developer.android.com/reference/android/app/Application[Application class].
+This example shows the simplest way to configure the agent:
+
+[source,java]
+----
+// Your Application class
+
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        ElasticApmAgent.initialize(this); <1>
+    }
+}
+----
+<1> Initialize the Elastic APM agent once.
+
+All that's left is to compile and run your application.
+That's it!
+
+*Learn more in the agent reference*
+
+Read more in the {apm-android-ref}/intro.html[APM Android Agent Reference].
+// end::android[]
+
 // tag::go[]
 *Install the agent*
 
@@ -59,8 +135,6 @@ func main() {
 
 // tag::ios[]
 
-experimental::[]
-
 *Add the agent dependency to your project*
 
 Add the Elastic APM iOS Agent as a
@@ -139,6 +213,9 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 <3> Enable TLS for Open telemetry exporters
 <4> Set secret token for APM server connection
 
+*Learn more in the agent reference*
+
+Read more in the {apm-ios-ref}/intro.html[APM iOS Agent Reference].
 // end::ios[]
 
 // ***************************************************

diff --git a/docs/en/observability/apm/troubleshoot-apm.asciidoc b/docs/en/observability/apm/troubleshoot-apm.asciidoc
@@ -20,6 +20,7 @@ For additional help with other APM components, see the links below.
 
 * {fleet-guide}/troubleshooting-intro.html[*{fleet} and {agent}* troubleshooting]
 * {kibana-ref}/troubleshooting.html[*{apm-app}* troubleshooting]
+* {apm-android-ref-v}/troubleshooting.html[*Android agent* troubleshooting]
 * {apm-dotnet-ref-v}/troubleshooting.html[*.NET agent* troubleshooting]
 * {apm-go-ref-v}/troubleshooting.html[*Go agent* troubleshooting]
 * {apm-ios-ref-v}/troubleshooting.html[*iOS agent* troubleshooting]

diff --git a/docs/en/observability/apm/version.asciidoc b/docs/en/observability/apm/version.asciidoc
@@ -9,6 +9,7 @@ include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[]
 
 // Agent link attributes
 // Used in conjunction with the stack attributes found here: https://github.com/elastic/docs/tree/7d62a6b66d6e9c96e4dd9a96c3dc7c75ceba0288/shared/versions/stack
+:apm-android-ref-v:    https://www.elastic.co/guide/en/apm/agent/android/{apm-android-branch}
 :apm-dotnet-ref-v:     https://www.elastic.co/guide/en/apm/agent/dotnet/{apm-dotnet-branch}
 :apm-go-ref-v:         https://www.elastic.co/guide/en/apm/agent/go/{apm-go-branch}
 :apm-ios-ref-v:        https://www.elastic.co/guide/en/apm/agent/swift/{apm-ios-branch}