Zero-Code Instrumentation of Java using OpenTelemetry

Instrument Java using Zero-Code OpenTelemetry to emit useful telemetry.

4 minute read

Overview

Zero-code instrumentation in Java with OpenTelemetry uses a Java agent that attaches to any Java 8+ application (but certain instrumentations require Java 11+). This approach requires no changes to the application code itself, as the agent dynamically injects bytecode to capture telemetry from popular libraries and frameworks. This is particularly useful for capturing telemetry at the boundaries of an application, such as incoming requests, database calls, and outbound HTTP requests.

Download the Java Agent

Visit the OpenTelemetry Java Instrumentation Releases page and download the latest version of opentelemetry-javaagent.jar from the list of assets. This JAR file contains the necessary bytecode instrumentation libraries which will automatically instrument your application at runtime. Place the opentelemetry-javaagent.jar file within your project directory or a designated folder where your Java applications reside. This will make it convenient to reference the agent in your application startup commands in the next step.

Define the Agent and Properties

To use the Java agent, you can either modify your application’s startup command or define the agent and properties using environment variables:

Direct Command-Line Configuration

Modify your Java application’s startup command by adding the -javaagent parameter followed by the path to the downloaded opentelemetry-javaagent.jar file. This will load the agent along with your application. You should also define a service name for your application to help identifying your service in telemetry data. Add the -Dotel.service.name system property to specify this.

java -javaagent:/path/to/opentelemetry-javaagent.jar -Dotel.service.name=my-service -jar yourapp.jar

Replace my-service with a meaningful name for your application, replace /path/to/ with the path to the opentelemetry-javaagent.jar file you downloaded, and replace yourapp with the name of your application jar.

Note: Don’t run this command yet - there is more configuration required in the following sections.

(Alternative) Use Environment Variables

Instead of modifying your Java application’s startup command, you can define the Java agent and other configuration properties using environment variables. This is especially useful in containerized environments.

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

Replace my-service with a meaningful name for your application, replace /path/to/ with the path to the opentelemetry-javaagent.jar file you downloaded.

Configure Exporters

You configure OTLP exporters for logs, traces and metrics with the endpoint from which Edge Delta will consume telemetry. After this step, you set the Edge Delta agent to listen on the selected host and port. Use a dedicated port like 4318 for OTLP, which is commonly used and recognized for telemetry data. See Ingest from an OTLP Source for more information on configuring the Edge Delta agent.

The endpoint configuration depends on your environment. For example, in a Kubernetes Environment, you need a service open, for example ed-data-supply-svc, for the port that the exporters will send logs, metrics, and traces to. For non-kubernetes environments with exporters running in the same environment as the Edge Delta agent, such as on a Linux VM, the exporters will be able to communicate directly with the Edge Delta agent on localhost. For HTTP (4318), include the path /v1/traces, /v1/metrics, or /v1/logs. For gRPC (4317), do not include the path. See Ingest Data from an OTLP Source.

Again, there are two ways of defining the exporter and endpoint:

Direct Command-Line Configuration

You can set the exporters in the startup command directly by adding these parameters to the startup command for your Java application:

     -Dotel.traces.exporter=otlp \
     -Dotel.metrics.exporter=otlp \
     -Dotel.logs.exporter=otlp \
     -Dotel.exporter.otlp.endpoint=http://ed-data-supply-svc:4317 \

Replace ed-data-supply-svc:4317 with an endpoint you want to use to expose telemetry.

(Alternative) Use Environment Variables

Use environment variables to define the exporters and endpoint, which is especially useful in containerized applications:

export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://ed-data-supply-svc:4317

Replace ed-data-supply-svc:4317 with an endpoint you want to use to expose telemetry.

Explore Supported Libraries and Frameworks

The OpenTelemetry Java agent comes with built-in instrumentation for a wide array of popular libraries and frameworks. This automatic instrumentation can capture telemetry for operations such as HTTP requests, database activities, messaging systems, and more, without any need for code changes. See the available libraries and frameworks. Check that the versions of the libraries or frameworks you are using in your Java application are supported by the OpenTelemetry Java agent version you have downloaded.

Run and Verify Instrumentation

Run your Java application using the startup command configured with the OpenTelemetry Java agent.

Command Line Approach: Combine all the parameters discussed in the previous sections to start your application:

java -javaagent:/path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=my-service \
     -Dotel.traces.exporter=otlp \
     -Dotel.metrics.exporter=otlp \
     -Dotel.logs.exporter=otlp \
     -Dotel.exporter.otlp.endpoint=http://ed-data-supply-svc:4317 \
     -jar yourapp.jar

Environment Variables Approach: Alternatively, run the following command after setting the environment parameters discussed in the previous sections:

java -jar yourapp.jar

Check the application logs and OpenTelemetry debug logs (if enabled) for any issues related to the agent or telemetry export. This will help identify configuration errors or connectivity problems.

Use Edge Delta to verify that telemetry data is being received. Look for your service name and ensure traces, metrics, and logs are visible. The dashboard should show real-time data logs and traces captured by the OpenTelemetry agent. Confirm that all critical operations and transactions within your application are being traced. You can use control data or test transactions to ensure coverage across various components.