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.
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.
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.OTEL_EXPORTER_OTLP_ENDPOINT
: Select the OpenTelemetry endpoint associated with your Coralogix domain.OTEL_RESOURCE_ATTRIBUTES
: Specify your Service.Name.OTEL_RESOURCE_ATTRIBUTES
: Specify Your Coralogix Send-Your-Data API key, application and subsystem name.application.name
: Replace with the name used for the identification of you Coralogix application nameapi.name
: Replace with the name used for the identification of you Coralogix subsystem namecx.application.name
: Replace with the name used for the identification of you Coralogix application namecx.subsystem.name
: Replace with the name used for the identification of your Coralogix subsystem nameOption 1 (recommended): Leveraging environment variables
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="<coralogix_otel_endpoint>" export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <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
Option 2: Changing the java command line
-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=<coralogix_otel_endpoint> \\ -Dotel.exporter.otlp.traces.headers=Authorization=Bearer "<CXPrivateKey>" \\ -Dotel.resource.attributes=service.name=<ServiceName>,application.name=<CXApplicationName>,api.name=<CXSubsystemName>,cx.application.name=<CXApplicationName>,cx.subsystem.name=<CXSubsystemName> \\ -jar myapp.jar
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
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="<coralogix_otel_endpoint>" export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <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.
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
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.
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].