From 42c9ee53a443de92b4c4df2fc75a9d80bdb0a415 Mon Sep 17 00:00:00 2001 From: Pavol Loffay Date: Sun, 27 Sep 2020 21:52:54 +0200 Subject: [PATCH] Add debugging docs (#1263) --- CONTRIBUTING.md | 4 ++++ docs/contributing/debugging.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 docs/contributing/debugging.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1edf43edcf..5cabc26318 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,6 +60,10 @@ See [Writing instrumentation](docs/contributing/writing-instrumentation.md) See [Understanding the javaagent components](docs/contributing/javaagent-jar-components.md) +### Debugging + +See [Debugging](docs/contributing/debugging.md) + ### Maintainers, Approvers and Triagers Maintainers: diff --git a/docs/contributing/debugging.md b/docs/contributing/debugging.md new file mode 100644 index 0000000000..d233a317ee --- /dev/null +++ b/docs/contributing/debugging.md @@ -0,0 +1,34 @@ +### 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.). + +#### Advice methods and agent initialization + +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. +The advice methods are annotated with: + +```java +@net.bytebuddy.asm.Advice.OnMethodEnter +@net.bytebuddy.asm.Advice.OnMethodExit +``` + +The best approach to debug advice methods and agent initialization is to use the following statements: + +```java +System.out.println() +Thread.dumpStack() +``` + +#### Enable debugger + +The following example shows remote debugger configuration. The breakpoints +should work in any code except ByteBuddy advice methods and agent initialization code. + +```bash +java -javaagent:opentelemetry-javaagent--all.jar -jar -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" app.jar +```