Merge pull request #3 from elastic/add-apm-agent-content

[work in progress] Add APM agent content

docs/apm-agents-android-api.mdx

@@ -0,0 +1,9 @@
+---
+id: serverlessObservabilityApmAgentsAndroidApi
+slug: /serverless/observability/apm-agents-android-api
+title: API
+# description: Description to be written
+tags: [ 'serverless', 'observability', 'overview' ]
+---
+
+No source content found.

docs/apm-agents-android-configure.mdx

@@ -0,0 +1,303 @@
+---
+id: serverlessObservabilityApmAgentsAndroidConfigure
+slug: /serverless/observability/apm-agents-android-configure
+title: Configure
+# description: Description to be written
+tags: [ 'serverless', 'observability', 'reference' ]
+---
+
+
+<div id="configuration"></div>
+
+## Gradle configuration
+
+Configure your application at compile time within your application's `build.gradle` file:
+
+```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 [Gradle plugin portal](https://plugins.gradle.org/plugin/co.elastic.apm.android).
+[^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 [here](((ref))/security-api-create-api-key.html).
+[^5]: Defaults to null.
+
+<DocCallOut title="Note">
+When both `secretToken` and `apiKey` are provided, apiKey has priority and secretToken is ignored.
+</DocCallOut>
+
+All of the values provided in the Gradle configuration can be overridden with the following environment variables:
+
+| Config | Associated Environment variable |
+|---|---|
+| serviceName | `ELASTIC_APM_SERVICE_NAME` |
+| serviceVersion | `ELASTIC_APM_SERVICE_VERSION` |
+| serverUrl | `ELASTIC_APM_SERVER_URL` |
+| apiKey | `ELASTIC_APM_API_KEY` |
+| secretToken | `ELASTIC_APM_SECRET_TOKEN` |
+
+## Runtime configuration
+
+The runtime configuration is provided within your [Application](https://developer.android.com/reference/android/app/Application) class when initializing the Elastic agent.
+This configuration overrides any previously-set compile time configuration.
+
+Runtime configuration works by providing your own instance of the `ElasticApmConfiguration` class as shown below:
+
+```java
+// Application class
+
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build());
+    }
+}
+```
+
+<div id="app-server-connectivity"></div>
+
+### APM Server connectivity
+
+The APM Server connectivity parameters can be provided at compile time, either by using the Gradle DSL configuration or by providing the APM Server connectivity-related environment variables as mentioned above.
+Later on, when the app is running, the connectivity parameters can be overridden by providing a custom `Connectivity` instance when initializing the Elastic agent.
+
+Once you've created your `Connectivity` instance, you can set it into the agent's initialization as show below:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        Connectivity myCustomConnectivity = Connectivity.simple(/*params*/);
+        ElasticApmAgent.initialize(this, myCustomConnectivity);
+
+        // Optionally if you also define a custom configuration:
+        // ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build(), myCustomConnectivity);
+    }
+}
+```
+
+<div id="app-id-configuration"></div>
+
+### Application ID configuration
+
+You can provide your application name, version, and environment dynamically when building your `ElasticApmConfiguration` instance as shown below:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
+                .setServiceName("my-custom-name")
+                .setServiceVersion("1.0.0")
+                .setDeploymentEnvironment("debug")
+                .build();
+        ElasticApmAgent.initialize(this, configuration);
+    }
+}
+```
+
+### Signal filtering
+
+You can provide your own filters to specify which spans, logs, and metrics are allowed to be exported to the backend.
+With this tool, you could essentially turn some of these signals (or all) on and off at runtime depending on your own business logic.
+
+In order to do so, you need to provide your own filters for each signal in the agent configuration as shown below:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
+                .addLogFilter(new LogFilter(){/*...*/})
+                .addMetricFilter(new MetricFilter(){/*...*/})
+//                .addMetricFilter(new MetricFilter(){/*...*/}) You can add multiple filters per signal.
+                .addSpanFilter(new SpanFilter() {
+                    @Override
+                    public boolean shouldInclude(ReadableSpan readableSpan) {
+                        if (thisSpanIsAllowedToContinue(readableSpan)) {
+                            return true;
+                        }
+                        return false;
+                    }
+                })
+                .build();
+        ElasticApmAgent.initialize(this, configuration);
+    }
+}
+```
+
+Each filter will contain a `shouldInclude` function which provides the signal item to be evaluated.
+This function must return a boolean value--`true` when the provided item is allowed to continue or `false` when it must be discarded.
+
+You can add multiple filters per signal which will be iterated over (in the order they were added) until all the filters are checked or until one of them decides to discard the signal item provided.
+
+### Automatic instrumentation enabling/disabling
+
+The agent provides automatic instrumentation for its <DocLink id="serverlessObservabilityApmAgentsAndroidSupportedTechnologies">Supported technologies</DocLink> which are all enabled by default.
+You can choose which ones to keep enabled, as well as and disabling those you don't need, at runtime, like so:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+
+        // When building an InstrumentationConfiguration object using `InstrumentationConfiguration.builder()`
+        // all of the instrumentations are disabled by default, so you only need to enable the ones you need.
+        InstrumentationConfiguration instrumentations = InstrumentationConfiguration.builder()
+            .enableHttpTracing(true)
+            .build();
+        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
+                .setInstrumentationConfiguration(instrumentations)
+                .build();
+        ElasticApmAgent.initialize(this, configuration);
+    }
+}
+```
+
+<DocCallOut title="Note">
+When building an InstrumentationConfiguration object using `InstrumentationConfiguration.builder()`, all instrumentations are disabled by default.
+Only enable the instrumentations you need using the builder setter methods.
+</DocCallOut>
+
+### HTTP Configuration
+
+The agent provides a configuration object for HTTP-related spans named `HttpTraceConfiguration`.
+You can pass an instance of it to the `ElasticApmConfiguration` object when initializing the agent in order to customize how the HTTP spans should be handled.
+
+#### Filtering HTTP requests from getting traced
+
+By default, all of your app's HTTP requests will get traced.
+You can avoid some requests from getting traced by creating your own `HttpExclusionRule`.
+For example, this is an exclusion rule that prevents all requests with the host `127.0.0.1` from getting traced:
+
+```java
+class MyHttpExclusionRule extends HttpExclusionRule {
+
+    @Override
+    public boolean exclude(HttpRequest request) {
+        return request.url.getHost().equals("127.0.0.1");
+    }
+}
+```
+
+Then you'd need to add it to Elastic's Agent config through its `HttpTraceConfiguration`, like so:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder()
+            .addExclusionRule(new MyHttpExclusionRule())
+            .build();
+        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
+                .setHttpTraceConfiguration(httpConfig)
+                .build();
+        ElasticApmAgent.initialize(this, configuration);
+    }
+}
+```
+
+#### Adding extra attributes to your HTTP requests' spans
+
+If the HTTP span attributes [provided by default](https://github.com/elastic/apm/tree/main/specs/agents/mobile) aren't enough, you can attach your own `HttpAttributesVisitor` to add extra params to each HTTP request being traced.
+For example:
+
+```java
+class MyHttpAttributesVisitor implements HttpAttributesVisitor {
+
+    public void visit(AttributesBuilder attrsBuilder, HttpRequest request) {
+        attrsBuilder.put("my_custom_attr_key", "my_custom_attr_value");
+    }
+}
+```
+
+Then you'd need to add it to Elastic's Agent config through its `HttpTraceConfiguration`, like so:
+
+```java
+class MyApp extends android.app.Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder()
+        .addHttpAttributesVisitor(new MyHttpAttributesVisitor())
+        .build();
+        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
+                .setHttpTraceConfiguration(httpConfig)
+                .build();
+        ElasticApmAgent.initialize(this, configuration);
+    }
+}
+```
+
+### Trace spans attributes notes
+
+There are [common attributes](https://github.com/elastic/apm/tree/main/specs/agents/mobile) that the Elastic APM agent gathers for every Span.
+However, due to the nature of Android's OS, to collect some device-related data some of the above-mentioned resources require the Host app (your app) to have specific runtime permissions granted.
+If the corresponding permissions aren't granted, then the device data won't be collected, and nothing will be sent for those attributes.
+This table outlines the attributes and their corresponding permissions:
+
+| Attribute | Used in | Requires permission |
+|---|---|---|
+| `net.host.connection.subtype` | All Spans | [READ_PHONE_STATE](https://developer.android.com/reference/android/Manifest.permission#READ_PHONE_STATE) |
+
+### Advanced configurable options
+
+The configurable parameters provided by the Elastic APM agent aim to help configuring common use cases in an easy way, in most of the cases it means to act as a facade between your application and the OpenTelemetry Java SDK that this agent is built on top.
+If your project requires to configure more advanced aspects of the overall APM processes, you could directly apply that configuration using the [OpenTelemetry SDK](https://opentelemetry.io/docs/instrumentation/java/getting-started/), which becomes available for you to use within your project by adding the Elastic agent plugin, as explained in <DocLink id="serverlessObservabilityApmAgentsAndroidGetStarted">the agent setup guide</DocLink>.
+Said configuration will be used by the Elastic agent for the [signals](https://opentelemetry.io/docs/concepts/signals/) it sends out of the box.
+
+<div id="configuration-dynamic"></div>
+
+## Dynamic configuration <DocBadge>Dynamic</DocBadge>
+
+Configuration options marked with Dynamic true can be changed at runtime when set from Kibana's [central configuration](((kibana-ref))/agent-configuration.html).
+
+## Option reference
+
+This is a list of all configuration options.
+
+<div id="config-recording"></div>
+
+### `recording` (<DocBadgeAdded tipContent="Added in 0.4.0">0.4.0</DocBadgeAdded>)
+
+A boolean specifying if the agent should be recording or not.
+When recording, the agent instruments incoming HTTP requests, tracks errors and collects and sends metrics.
+When not recording, the agent works as a noop, not collecting data and not communicating with the APM sever, except for polling the central configuration endpoint.
+As this is a reversible switch, agent threads are not being killed when inactivated, but they will be mostly idle in this state, so the overhead should be negligible.
+
+You can use this setting to dynamically disable Elastic APM at runtime.
+
+<DocLink id="serverlessObservabilityApmAgentsAndroidConfigure" section="dynamic-configuration-imageimagesdynamic-configsvg[]"><DocBadge>Dynamic</DocBadge> </DocLink>
+
+| Default | Type | Dynamic |
+|---|---|---|
+| `true` | Boolean | true |