Updating legacy doc

docs/automatic-instrumentation.asciidoc

@@ -0,0 +1,113 @@
+[[automatic-instrumentation]]
+== Automatic instrumentation
+
+The agent has an opt-in functionality that automatically generates
+telemetry on your behalf. This allows you to get telemetry data for
+supported targets without having to write
+<<manual-instrumentation,manual instrumentation>>.
+
+[discrete]
+=== How it works
+
+[discrete]
+==== Installation
+
+Install the automatic instrumentations you'd like to use.
+
+Specific targets are supported for automatic instrumentation, each with
+its own Gradle plugin for installation. To install a supported automatic
+instrumentation, follow these steps:
+
+[arabic]
+. Choose a <<supported-instrumentations,supported instrumentation>>.
+. Add its Gradle plugin to your project in the same location where the
+<<gradle-setup,agent>> is added.
+. <<agent-setup,Initialize the agent>> the same way
+you would without using automatic instrumentation. Automatic
+instrumentations will get installed during the agent initialization
+without having to write extra code.
+
+[discrete]
+[[compilation-behavior]]
+==== Compilation behavior
+
+Some automatic instrumentations perform "byte code instrumentation"
+(also called byte code weaving), where your application's code
+(including code from the libraries it uses) is modified *at
+compile-time*. This automates code changes that you would otherwise need
+to make manually.
+
+Byte code instrumentation is a common technique which may already be
+used in your project for use cases such as
+https://developer.android.com/build/shrink-code#optimization[code
+optimization] through R8. While useful, code instrumentation can make
+compilation take longer to complete. Because of this, the agent provides
+<<automatic-build-configuration,a way to exclude>> specific build types in your app
+from byte code changes, similar to what
+https://developer.android.com/build/shrink-code#enable[isMinifyEnabled]
+does with R8 functionalities.
+
+[discrete]
+[[automatic-build-configuration]]
+==== Configuration
+
+For some large projects (including dependencies), you can avoid the
+added compilation time caused by the
+<<compilation-behavior,compilation behavior>> by excluding build
+types that don't need the functionality. Use the following configuration
+to do so:
+
+[source,kotlin]
+----
+// Your app's build.gradle.kts file
+plugins {
+    // ...
+    id("co.elastic.otel.android.agent")
+}
+
+// ...
+
+elasticAgent {
+    bytecodeInstrumentation.disableForBuildTypes.set(listOf("debug")) // <1>
+}
+----
+
+[arabic]
+. By default, the `disableForBuildTypes` list is empty. Add any
+https://developer.android.com/build/build-variants#build-types[build
+type] names for which you want to disable byte code instrumentation.
+
+[NOTE]
+====
+Disabling byte code instrumentation will cause the
+<<supported-instrumentations,automatic instrumentations>> that need
+it to not work properly on the affected build type. This shouldn't cause
+issues to your app's functionality in general, it will only affect the
+agent's ability to automatically collect telemetry.
+====
+
+[discrete]
+[[supported-instrumentations]]
+=== Supported instrumentations
+
+[discrete]
+==== OkHttp
+
+Creates spans for outgoing HTTP requests that are made using the
+https://square.github.io/okhttp/[OkHttp] library. This also includes
+tools that rely on OkHttp to work, such as
+https://square.github.io/retrofit/[Retrofit].
+
+[discrete]
+===== Gradle plugin
+
+[source,kotlin]
+----
+plugins {
+    id("co.elastic.otel.android.instrumentation.okhttp") version "[latest_version]" // <1>
+}
+----
+
+[arabic]
+. You can find the latest version
+https://plugins.gradle.org/plugin/co.elastic.otel.android.instrumentation.okhttp[here].