From c8c8eb8c0b5f89223636fc0a6d54cf4944449eb3 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Oct 2020 11:13:31 -0700 Subject: [PATCH] Update debugging doc (#1296) --- docs/contributing/debugging.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/contributing/debugging.md b/docs/contributing/debugging.md index d233a317ee..8bc98d87e9 100644 --- a/docs/contributing/debugging.md +++ b/docs/contributing/debugging.md @@ -1,12 +1,9 @@ ### Debugging Debugging java agent can be a challenging task since some instrumentation -code is directly inlined into target classes and debugger is -usually not attached early enough to activate breakpoints -in agent initialization code (`OpenTelemetryAgent`, `AgentInitializer`, `AgentInstaller`, -`TracerInstaller`, etc.). +code is directly inlined into target classes. -#### Advice methods and agent initialization +#### Advice methods Breakpoints do not work in advice methods, because their code is directly inlined by ByteBuddy into the target class. It is good to keep these methods as small as possible. @@ -24,11 +21,17 @@ System.out.println() Thread.dumpStack() ``` -#### Enable debugger +#### Agent initialization code + +If you want to debug agent initialization code (e.g. `OpenTelemetryAgent`, `AgentInitializer`, +`AgentInstaller`, `TracerInstaller`, etc.) then it's important to specify the `-agentlib:` JVM arg +before the `-javaagent:` JVM arg and use `suspend=y` (see full example below). + +#### Enabling debugging The following example shows remote debugger configuration. The breakpoints -should work in any code except ByteBuddy advice methods and agent initialization code. +should work in any code except ByteBuddy advice methods. ```bash -java -javaagent:opentelemetry-javaagent--all.jar -jar -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" app.jar +java -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" -javaagent:opentelemetry-javaagent--all.jar -jar app.jar ```