Auto Instrumenting Java Apps with OpenTelemetry

This guide shows you how to auto instrument your Java application using the OpenTelemetry Java agent and send data to our service.

Prerequisites

• A VMware Aria Operations for Applications (formerly known as Tanzu Observability by Wavefront) account to visualize and monitor your application health. If you don’t have one already, you can sign up on our website.
• Docker to run the Wavefront proxy.
• Java 11 or later.
• Maven

Install the Wavefront Proxy

Follow these steps to install the Wavefront proxy using Docker. See Install a Proxy to find other options for installing the proxy in your environment.

1. Make sure you have Proxies permission.
   1. Click the gear icon on the toolbar and select your username.
   2. On the Groups, Roles & Permissions tab, verify that the Proxies check box is selected.
   3. If you don’t see the check box next to Proxies selected, ask a user with the Accounts permission to grant you with the Proxies permission.
2. Generate an API Token.
3. Run the following command to install the proxy:

    docker run -d \
        -e WAVEFRONT_URL=https://{CLUSTER}.wavefront.com/api/ \
        -e WAVEFRONT_TOKEN={TOKEN} \
        -e JAVA_HEAP_USAGE=512m \
        -e WAVEFRONT_PROXY_ARGS="--otlpGrpcListenerPorts 4317" \
        -p 2878:2878 \
        -p 4317:4317 \
        wavefronthq/proxy:latest
   

   You need to:

   • Replace {CLUSTER} with the name of your cluster.
   • Replace {TOKEN} with the API token that you generated.
4. Confirm that the proxy is running.

    docker ps
   

   If docker ps does not list the Wavefront proxy, it means that the Wavefront proxy stopped running. If this happens, use docker logs <container ID> to view the logs and find the issue. The docker command you ran in step 3 prints out the container ID.

Run the Auto-Instrumented Application

For instrumentation, you use the Java agent provided by OpenTelemetry, which can be attached to any Java application. This agent dynamically injects bytecode to collect telemetry data, and developers can avoid manual instrumentation.

1. Clone the Spring Petclinic application and navigate to the directory.

    git clone https://github.com/spring-projects/spring-petclinic.git
    cd spring-petclinic
   

2. Run ./mvnw package from the root directory of the project.
3. Download the OpenTelemetry Java agent.

    curl -L https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar --output otelagent.jar
   

4. Assign the file path to the JAVA_AGENT variable.

    JAVA_AGENT=./otelagent.jar
   

5. Attach the Java agent and start the Spring Petclinic application.

    java -javaagent:$JAVA_AGENT -Dotel.service.name=petclinic -Dotel.resource.attributes=application=demo-petclinic -Dotel.exporter.otlp.metrics.temporality.preference=DELTA -Dotel.exporter.otlp.metrics.default.histogram.aggregation=EXPONENTIAL_BUCKET_HISTOGRAM -jar target/*.jar
   

6. Navigate to http://localhost:8080 and interact with the Petclinic application to generate telemetry data.

View the Metrics and Distributed Traces

You can see the traces on the Traces Browser and the Application Map, and metrics on charts.

View Traces

• Traces Browser: On the toolbar, click Applications > Traces. You see the traces sent by the Petclinic application. Example:
• Application Map: On the toolbar, click Applications > Application Status. You see the Petclinic application and the services it communicates with when sending data to our service. Example:

Create Charts with Metrics

When the metrics data collected from the Wavefront proxy are sent to our service, you can examine them in our user interface.

Example:

The query ts(jvm.threads.live) shows the total number of live threads in the Petclinic application.

Learn More!

To manually configure your application and send data to our service, see Instrumenting Java Apps with OpenTelemetry.