| ### Understanding the javaagent instrumentation testing components |
| |
| Javaagent instrumentation tests are run using a fully shaded `-javaagent` in order to perform |
| the same bytecode instrumentation as when the agent is run against a normal app. |
| |
| There are a few key components that make this possible, described below. |
| |
| ### gradle/instrumentation.gradle |
| |
| * shades the instrumentation |
| * adds jvm args to the test configuration |
| * -javaagent:[agent for testing] |
| * -Dotel.javaagent.experimental.initializer.jar=[shaded instrumentation jar] |
| |
| The `otel.javaagent.experimental.initializer.jar` property is used to load the shaded instrumentation jar into the |
| `AgentClassLoader`, so that the javaagent jar doesn't need to be re-built each time. |
| |
| ### :testing:agent-exporter |
| |
| This contains the span and metric exporters that are used. |
| |
| These are in-memory exporters, so that the tests can verify the spans and metrics being exported. |
| |
| These exporters and the in-memory data live in the `AgentClassLoader`, so tests must access them |
| using reflection. To simplify this, they store the in-memory data using the OTLP protobuf objects, |
| so that they can be serialized into byte arrays inside the `AgentClassLoader`, then passed back |
| to the tests and deserialized inside their class loader where they can be verified. The |
| `:testing-common` module (described below) hides this complexity from instrumentation test authors. |
| |
| ### :agent-for-testing |
| |
| This is a custom distro of the javaagent that embeds the `:testing:agent-exporter`. |
| |
| ### :testing-common |
| |
| This module provides methods to help verify the span and metric data produced by the |
| instrumentation, hiding the complexity of accessing the in-memory exporters that live in the |
| `AgentClassLoader`. |
