indy advice docs & migration procedure

docs/contributing/writing-instrumentation-module.md

@@ -360,3 +360,129 @@ For example:
 ```
 
 [suppress]: https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/#suppressing-specific-auto-instrumentation
+
+## Use non-inlined advice code with `invokedynamic`
+
+Using non-inlined advice code is possible thanks to the `invokedynamic` instruction, this strategy
+is referred as "indy" in reference to this, by extension "indy modules" are the instrumentation
+modules using this instrumentation strategy.
+
+The most common way to instrument code with bytebuddy relies on inlining, this strategy will be
+referred as "inlined" strategy in opposition to "indy".
+
+### Indy modules and transition
+
+Having all instrumentation rely on native "indy" instrumentation is a tedious task and can't be
+achieved in a "big bang" step, we thus have to use intermediate steps.
+
+Instrumentation modules that are "indy native" must have their `InstrumentationModule#isIndyModule`
+implementation return `true`. Also, all the instrumentation advice methods annotated with
+`@Advice.OnMethodEnter` or `@Advice.OnMethodExit` must have the `inlined = false` explicitly set.
+
+The `otel.javaagent.experimental.indy` (default `false`) configuration option allows to opt-in for
+using "indy". When set to `true`, the `io.opentelemetry.javaagent.tooling.instrumentation.indy.AdviceTransformer`
+will transform advices automatically to make them "indy native".
+
+This configuration is automatically enabled in CI when `test indy` label is added to a pull-request
+or when the `-PtestIndy=true` parameter is added to gradle.
+
+In order to preserve compatibility with both instrumentation strategies, we have to omit the `inlined = false`
+from the advice method annotations.
+
+We have two sets of instrumentation modules:
+- "indy compatible": compatible with both "indy" and "inlined", do not override `isIndyModule`
+- "inlined only": only compatible with "inlined", `isIndyModule` returns `false`.
+
+The first step of the migration is to move all the "inlined only" to the "indy compatible" category
+by refactoring them with the limitations described below.
+
+Once everything is "indy compatible", we can evaluate changing the default value of `otel.javaagent.experimental.indy`
+to `true` and make it non-experimental.
+
+### shared classes and common classloader
+
+By default, all the advices of an instrumentation module will be loaded into isolated classloaders,
+one per instrumentation module. Some instrumentations require to use a common classloader in order
+to preserve the semantics of `static` fields and to share classes.
+
+In order to load multiple `InstrumentationModule` implementations in the same classloader, you need to
+override the `ExperimentalInstrumentationModule#getModuleGroup` to return an identical value.
+
+### advice local variables
+
+With inlined advices, declaring an advice method argument with `@Advice.Local` allows to define
+a variable that is local to the advice execution for communication between the enter and exit advices.
+
+When advices are not inlined, usage of `@Advice.Local` is not possible. It is however possible to
+return a value from the enter advice and get the value in the exit advice with a parameter annotated
+with `@Advice.Enter`, for example:
+
+```java
+@Advice.OnMethodEnter(suppress = Throwable.class)
+public static Object onEnter(@Advice.Argument(1) Object request) {
+  return "enterValue";
+}
+
+@Advice.OnMethodExit(suppress = Throwable.class, onThrowable = Throwable.class)
+public static void onExit(@Advice.Argument(1) Object request,
+                          @Advice.Enter Object enterValue) {
+  // do something with enterValue
+}
+```
+
+### modifying method arguments
+
+With inlined advices, using the `@Advice.Argument` annotation on method parameter with `readOnly = false`
+allows to modify instrumented method arguments.
+
+When using non-inlined advices, reading the argument values is still done with `@Advice.Argument`
+annotated parameters, however modifying the values is done through the advice method return value 
+and `@Advice.AssignReturned.ToArguments` annotation:
+
+```java
+@Advice.OnMethodEnter(suppress = Throwable.class)
+@Advice.AssignReturned.ToArguments(@ToArgument(1))
+public static Object onEnter(@Advice.Argument(1) Object request) {
+  return "hello";
+}
+```
+
+It is possible to modify multiple arguments at once by using an array, see usages of
+`@Advice.AssignReturned.ToArguments` for detailed examples.
+
+### modifying method return value
+
+With inlined advices, using the `@Advice.Return` annotation on method parameter with `readOnly = false`
+allows to modify instrumented method return value on exit advice.
+
+When using non-inlined advices, reading the original return value is still done with `@Advice.Return`
+annotated parameter, however modifying the value is done through the advice method return value
+and `@Advice.AssignReturned.ToReturned`
+
+```java
+@Advice.OnMethodExit(suppress = Throwable.class)
+@Advice.AssignReturned.ToReturned
+public static Object onEnter(@Advice.Return Object returnValue) {
+  return "hello";
+}
+```
+
+### writing to internal class fields
+
+With inlined advices, using the `@Advice.FieldValue(value = "fieldName", readOnly = false)` annotation
+on advice method parameter allows to modify the `fieldName` field of the instrumented class.
+
+When using non-inlined advices, reading the original field value is still done with `@Advice.FieldValue`
+annotated parameter, however modifying the value is done through the advice method return value
+and `@Advice.AssignReturned.ToFields` annotation:
+
+```java
+@Advice.OnMethodExit(suppress = Throwable.class)
+@Advice.AssignReturned.ToFields(@ToField(value = "fieldName"))
+public static Object onEnter(@Advice.FieldValue("fieldName") Object originalFieldValue) {
+  return "newFieldValue";
+}
+```
+
+It is possible to modify multiple fields at once by using an array, see usages of
+`@Advice.AssignReturned.ToFields` for detailed examples.