README.md

Runtime attachment

If you can't update the JVM arguments to attach the OpenTelemetry Java agent (-javaagent:path/to/opentelemetry-javaagent.jar), this project allows you to do attachment programmatically.

Quick start

Add a dependency

Replace OPENTELEMETRY_CONTRIB_VERSION with the latest release version.

For Maven, add to your pom.xml the following dependency:

<dependency>
  <groupId>io.opentelemetry.contrib</groupId>
  <artifactId>opentelemetry-runtime-attach</artifactId>
  <version>OPENTELEMETRY_CONTRIB_VERSION</version>
</dependency>

For Gradle, add to your dependencies:

implementation("io.opentelemetry.contrib:opentelemetry-runtime-attach:OPENTELEMETRY_CONTRIB_VERSION")

This dependency embeds the OpenTelemetry agent JAR.

Call runtime attach method

The io.opentelemetry.contrib.attach.RuntimeAttach class has an attachJavaagentToCurrentJVM method allowing to trigger the attachment of the OTel agent for Java.

You have to call this method at the beginning of your application's main method.

We give below an example for Spring Boot applications:

@SpringBootApplication
public class SpringBootApp {

    public static void main(String[] args) {
        RuntimeAttach.attachJavaagentToCurrentJVM();
        SpringApplication.run(SpringBootApp.class, args);
    }

}

Limitations

The attachment will not be initiated in the following cases:

• The otel.javaagent.enabled property is set to false
• The OTEL_JAVAAGENT_ENABLED environment variable is set to false
• The attachment is not requested from the main thread
• The attachment is not requested from the public static void main(String[] args) method
• The agent is already attached
• The application is running on a JRE (a JDK is necessary, see this issue)
• The temporary directory should be writable

Component owners

• Jean Bisutti, Microsoft

Learn more about component owners in component_owners.yml.