---

Getting Started   •   Getting Involved   •   Getting In Touch

Contributing   •   Scope

---

OpenTelemetry Instrumentation for Java

• About
• Getting Started
• Configuring the Agent
• Supported libraries, frameworks, and application servers
• Creating agent extensions
• Manually instrumenting
• Logger MDC auto-instrumentation
• Troubleshooting
• Contributing
• [OSHI Jar Setup with Special Configuration](#OSHI Jar Setup with Special Configuration)

About

This project provides a Java agent JAR that can be attached to any Java 8+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks. You can export the telemetry data in a variety of formats. You can also configure the agent and exporter via command line arguments or environment variables. The net result is the ability to gather telemetry data from a Java application without code changes.

This repository also publishes standalone instrumentation for several libraries (and growing) that can be used if you prefer that over using the Java agent. Please see the standalone library instrumentation column on Supported Libraries. If you are looking for documentation on using those.

Getting Started

Download the latest version.

This package includes the instrumentation agent as well as instrumentations for all supported libraries and all available data exporters. The package provides a completely automatic, out-of-the-box experience.

Enable the instrumentation agent using the -javaagent flag to the JVM.

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar

By default, the OpenTelemetry Java agent uses OTLP exporter configured to send data to OpenTelemetry collector at http://localhost:4317.

Configuration parameters are passed as Java system properties (-D flags) or as environment variables. See the configuration documentation for the full list of configuration items. For example:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.resource.attributes=service.name=your-service-name \
     -Dotel.traces.exporter=zipkin \
     -jar myapp.jar

Configuring the Agent

The agent is highly configurable! Many aspects of the agent's behavior can be configured for your needs, such as exporter choice, exporter config (like where data is sent), trace context propagation headers, and much more.

Click here to see the detailed list of configuration environment variables and system properties.

Note: Config parameter names are very likely to change over time, so please check back here when trying out a new version! Please report any bugs or unexpected behavior you find.

Supported libraries, frameworks, and application servers

We support an impressively huge number of libraries and frameworks and a majority of the most popular application servers...right out of the box! Click here to see the full list and to learn more about disabled instrumentation and how to suppress unwanted instrumentation.

Creating agent extensions

Extensions add new features and capabilities to the agent without having to create a separate distribution or to fork this repository. For example, you can create custom samplers or span exporters, set new defaults, and embed it all in the agent to obtain a single jar file.

Manually instrumenting

For most users, the out-of-the-box instrumentation is completely sufficient and nothing more has to be done. Sometimes, however, users wish to add attributes to the otherwise automatic spans, or they might want to manually create spans for their own custom code.

For detailed instructions, see Manual instrumentation.

Logger MDC (Mapped Diagnostic Context) auto-instrumentation

It is possible to inject trace information like trace IDs and span IDs into your custom application logs. For details, see Logger MDC auto-instrumentation.

Troubleshooting

To turn on the agent's internal debug logging:

-Dotel.javaagent.debug=true

Note: These logs are extremely verbose. Enable debug logging only when needed. Debug logging negatively impacts the performance of your application.

Contributing

See CONTRIBUTING.md.

Approvers (@open-telemetry/java-instrumentation-approvers):

• Gregor Zietlinger, Grafana
• Jack Berg, New Relic
• Jason Plumb, Splunk
• Jean Bisutti, Microsoft
• John Watson, Verta.ai

Maintainers (@open-telemetry/java-instrumentation-maintainers):

• Lauri Tulmin, Splunk
• Mateusz Rzeszutek, Splunk
• Trask Stalnaker, Microsoft

Emeritus maintainers:

• Nikita Salnikov-Tarnovski, Splunk
• Tyler Benson

Learn more about roles in the community repository.

Thanks to all the people who already contributed!

OSHI Jar Setup with Special Configuration

Introduction: OSHI (Operating System Hardware Information) is a Java library that provides cross-platform access to information about system hardware, operating system, and JVM. Sometimes, you may need to manually download the OSHI jar file and add it to the system classpath, especially in environments where dependency management tools like Maven or Gradle are not available or suitable.

Step1: download oshi-core jar from https://search.maven.org/search?q=g:com.github.oshi%20AND%20a:oshi-core

Step2: Adding OSHI Jar to Classpath:

Once you've downloaded the OSHI jar file, you need to add it to the classpath of your Java application.

1. Command Line: You can add the OSHI jar to the classpath using the -cp or -classpath option when running the java command.

Cmd: java -cp /path/to/oshi-core-v1.jar MainClass

Note: In above cmd, v1 denotes the version for the .jar

Replace /path/to/oshi-core-v1.jar with the actual path to the downloaded jar file and MainClass with the main class of your Java application.

2. Environment Variable: Set the CLASSPATH environment variable to include the path to the OSHI jar file.

Cmd: export CLASSPATH=/path/to/oshi-core-v1.jar:$CLASSPATH

Note: In above cmd, v1 denotes the version for the .jar

Replace /path/to/oshi-core-v1.jar with the actual path to the downloaded jar file.

3. IDE Setup: If you are using an Integrated Development Environment (IDE) like Eclipse or IntelliJ IDEA, you can add the OSHI jar to your project's build path through the IDE's project settings. • In Eclipse: Right-click on your project, select "Properties" > "Java Build Path" > "Libraries" > "Add External JARs", then select the downloaded OSHI jar. • In IntelliJ IDEA: Right-click on your project, select "Open Module Settings" > "Dependencies" tab, click on the "+" icon, and select "JARs or directories" to add the OSHI jar.

Conclusion: By following the steps mentioned above, you can manually download the OSHI jar file and add it to the system classpath for your Java applications, enabling access to system hardware information and monitoring capabilities provided by OSHI.