Java OpenTelemetry Instrumentation

This tutorial demonstrates how to instrument your Java applications to capture OpenTelemetry traces and send them to Coralogix.

OpenTelemetry-Java automatic instrumentation is the most efficient method for adding instrumentation to Java applications. Requiring minimal modifications to the code, it uses a Java agent that can be attached to any Java 8+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks.

Installation

The instructions below apply conform to the latest OpenTelemetry Java Auto Instrumentation, currently Java agent version 1.22.1.

STEP 1. Download and distribute the agent JAR.

• Download the latest OpenTelemetry Java agent.
• Apply the agent to each service host or container that requires access to it.
• The JVM will require access to the agent to function properly.

STEP 2. Update the JVM configuration.

Either of the following options may be used as the template, with the following changes:

• JAVA_TOOL_OPTIONS: Replace the path to the javaagent JAR file with the location of the file downloaded and distributed in STEP 1.
• Specify your account’s specific Coralogix domain
• OTEL_RESOURCE_ATTRIBUTES: Specify your Service.Name
• OTEL_RESOURCE_ATTRIBUTES: Specify Your Coralogix private key, application and subsystem name
• Specify 4 RESOURCE_ATTRIBUTES for application and subsystem:
  • application.name: Replace with the name used for the identification of you Coralogix application name
  • api.name: Replace with the name used for the identification of you Coralogix subsystem name
  • cx.application.name: Replace with the name used for the identification of you Coralogix application name
  • cx.subsystem.name: Replace with the name used for the identification of your Coralogix subsystem name

Option 1 (recommended): Leveraging environment variables

• Pass the Configuration parameters as system properties environment variables in the JVM:

export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-traces.<domain>:443"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<CXPrivateKey>"
export OTEL_RESOURCE_ATTRIBUTES=service.name=<ServiceName>,application.name=<CXApplicationName>,api.name=<CXSubsystemName>,cx.application.name=<CXApplicationName>,cx.subsystem.name=<CXSubsystemName>

java -javaagent:</path/to/>opentelemetry-javaagent.jar -jar myapp.jar

Note: OTEL_EXPORTER_OTLP_TRACES_HEADERS requires the use of URL encoded format. Use %20 as space between Bearer and your CXPrivateKey.

• View the full range of configuration options here.

Option 2: Changing the java command line

• Enable the instrumentation agent using the -javaagent flag to the JVM and pass the Configuration parameters as Java system properties (-D flags):

java -javaagent:path/to/opentelemetry-javaagent.jar \\
    -Dotel.traces.exporter=otlp \\
    -Dotel.exporter.otlp.traces.protocol=grpc \\
    -Dotel.exporter.otlp.traces.endpoint=https://otel-traces.<domain>:443 \\
		-Dotel.exporter.otlp.traces.headers=Authorization=Bearer%20<CXPrivateKey> \\
    -Dotel.resource.attributes=service.name=<ServiceName>,application.name=<CXApplicationName>,api.name=<CXSubsystemName>,cx.application.name=<CXApplicationName>,cx.subsystem.name=<CXSubsystemName> \\
		-jar myapp.jar

Troubleshooting

Confirm that the instrumentation was installed by looking for the following log lines in your console:

[otel.javaagent 2023-02-14 10:40:00:811 +0000] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.21.1

Example

JPetStore 6 is a full web application built on top of MyBatis 3, Spring 5 and Stripes.

STEP 1. Install a version of the Java Development Kit. It will not deploy when using only the Java Runtime Environment.

STEP 2. Download the JDK for your platform.

STEP 3. Clone the jpetstore git repo:

git clone <https://github.com/kazuki43zoo/mybatis-spring-boot-jpetstore.git>

STEP 4. Run the following:

./mvnw package

STEP 5. Download the OpenTelemetry agent.

STEP 6. Apply the environment variables:

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-traces.<domain>:443"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<CXPrivateKey>"
export OTEL_RESOURCE_ATTRIBUTES=service.name=<ServiceName>,application.name=<CXApplicationName>,api.name=<CXSubsystemName>,cx.application.name=<CXApplicationName>,cx.subsystem.name=<CXSubsystemName>

STEP 7. Run the project with the agent:

java -javaagent:</path/to/>opentelemetry-javaagent.jar -jar mybatis-spring-boot-jpetstore-2.0.0-SNAPSHOT

STEP 8. Navigate to http://localhost:8080/.

STEP 9. View the traces in your Coralogix dashboard.

Additional Instrumentation Using Annotations

STEP 1. Open the project with your favorite IDE/text editor.

STEP 2. Edit the pom.xml file and add the following maven dependency:

<dependency>
	<groupId>io.opentelemetry.instrumentation</groupId>
	<artifactId>opentelemetry-instrumentation-annotations</artifactId>
	<version>1.22.1</version>
</dependency>

STEP 3. Edit file src/main/java/com/kazuki43zoo/jpetstore/ui/Cart.java.

STEP 4. Add this import to the java file where methods you want to trace are present.

import io.opentelemetry.instrumentation.annotations.WithSpan;

STEP 5. Before the function you wish to trace, add the annotation “WithSpan”.

Example: cart.java

STEP 6. Rebuild your springboot application applying the changes (using either your IDE or command line).

STEP 7. Run your application again with the Otel agent:

java -javaagent:</path/to/>opentelemetry-javaagent.jar -jar mybatis-spring-boot-jpetstore-2.0.0-SNAPSHOT

Validation

In your Coralogix dashboard, navigate to Explore > Tracing to view the traces generated by your application.

Your traces should now contain additional spans on annotated methods.

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at [email protected].