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.

Javaagent Instrumentation测试使用完全遮蔽的 -javaagent 运行，以便执行与Agent针对正常应用程序运行时相同的字节码仪表。

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.