Add disableShadowRelocate build setting

conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-shadowing.gradle.kts

@@ -17,11 +17,13 @@ tasks.withType<ShadowJar>().configureEach {
   // rewrite dependencies calling Logger.getLogger
   relocate("java.util.logging.Logger", "io.opentelemetry.javaagent.bootstrap.PatchLogger")
 
-  // prevents conflict with library instrumentation, since these classes live in the bootstrap class loader
-  relocate("io.opentelemetry.instrumentation", "io.opentelemetry.javaagent.shaded.instrumentation") {
-    // Exclude resource providers since they live in the agent class loader
-    exclude("io.opentelemetry.instrumentation.resources.*")
-    exclude("io.opentelemetry.instrumentation.spring.resources.*")
+  if (project.findProperty("disableShadowRelocate") != "true") {
+    // prevents conflict with library instrumentation, since these classes live in the bootstrap class loader
+    relocate("io.opentelemetry.instrumentation", "io.opentelemetry.javaagent.shaded.instrumentation") {
+      // Exclude resource providers since they live in the agent class loader
+      exclude("io.opentelemetry.instrumentation.resources.*")
+      exclude("io.opentelemetry.instrumentation.spring.resources.*")
+    }
   }
 
   // relocate(OpenTelemetry API) since these classes live in the bootstrap class loader

docs/contributing/debugging.md

@@ -1,6 +1,6 @@
 # Debugging
 
-Debugging java agent can be a challenging task since some instrumentation
+Debugging javaagent instrumentation can be a challenging task since instrumentation
 code is directly inlined into target classes.
 
 ## Advice methods
@@ -14,11 +14,20 @@ The advice methods are annotated with:
 @net.bytebuddy.asm.Advice.OnMethodExit
 ```
 
-The best approach to debug advice methods and agent initialization is to use the following statements:
+These annotations have an option to disable inlining which can allow breakpoints to work within
+advice methods. This should only be used for debugging and may break things. As such, it is best to
+first try debugging the methods that advice is calling rather than the advice method itself.
 
 ```java
-System.out.println()
-Thread.dumpStack()
+@Advice.OnMethodEnter(inline = false)
+```
+
+When inlined, the best approach to debug advice methods and agent initialization is to use the
+following statements:
+
+```java
+System.out.println();
+Thread.dumpStack();
 ```
 
 ## Agent initialization code
@@ -35,3 +44,14 @@ should work in any code except ByteBuddy advice methods.
 ```bash
 java -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" -javaagent:opentelemetry-javaagent-<version>.jar -jar app.jar
 ```
+
+## Shadow Renaming
+
+One additional thing that complicates debugging is that certain packages are renamed to avoid
+conflict with whatever might already be on the classpath. This results in classes that don't match
+what the IDE is expecting for debug breakpoints. You can disable the shadow renaming for local
+builds by adding the following to `~/.gradle/gradle.properties` before building.
+
+```properties
+disableShadowRelocate=true
+```