opentelemetry-java-instrumentation/docs/contributing/javaagent-test-infra.md

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.