From 1b4b47a5762bd52cf749778ed88b559a7856de9c Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Tue, 28 Mar 2023 09:42:45 -0700 Subject: [PATCH] Add `disableShadowRelocate` build setting (#8117) This is helpful for debugging. Fixes #4672 Add the following to enable locally `~/.gradle/gradle.properties` ``` disableShadowRelocate=true ``` --- ...rumentation.javaagent-shadowing.gradle.kts | 12 ++++---- docs/contributing/debugging.md | 28 ++++++++++++++++--- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-shadowing.gradle.kts b/conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-shadowing.gradle.kts index 65e3a29f14ae..dcbc8977a7e5 100644 --- a/conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-shadowing.gradle.kts +++ b/conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-shadowing.gradle.kts @@ -17,11 +17,13 @@ tasks.withType().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 diff --git a/docs/contributing/debugging.md b/docs/contributing/debugging.md index 4ffeb53d9560..3d9a76074a3e 100644 --- a/docs/contributing/debugging.md +++ b/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-.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 +```