Skip to main content

Java Zero-Code Instrumentation

Zero-code instrumentation with Java uses a Java agent JAR attached to any Java 8+ application. It dynamically injects bytecode to capture telemetry from many popular libraries and frameworks automatically, without requiring code changes.

Overview​

The OpenTelemetry Java agent can capture telemetry data at the "edges" of your application, such as:

  • Inbound HTTP requests
  • Outbound HTTP calls
  • Database calls
  • Messaging operations
  • And many other popular frameworks and libraries

Prerequisites​

  • Java 8 or higher
  • Your Oodle metrics endpoint and API key

Getting Started​

Step 1: Get Your Oodle Configuration​

In the Oodle UI, navigate to the Settings page and click on Connect in the Open Telemetry tile and copy the provided configuration snippet which includes your metrics endpoint and API key

Open Telemetry Configuration

Step 2: Download the Java Agent​

Download the latest OpenTelemetry Java agent from the official releases:

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

Step 3: Configure Environment Variables​

Set the following environment variables for your Java application:

# OpenTelemetry Configuration
export OTEL_SERVICE_NAME=<YOUR_SERVICE_NAME>
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=<OODLE_OTEL_METRICS_ENDPOINT>
export OTEL_EXPORTER_OTLP_METRICS_HEADERS=X-API-KEY=<OODLE_API_KEY>,X-OODLE-IGNORE-SCOPE-NAME=true
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta

# Optional: Service identification
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR_SERVICE_NAME>

Step 4: Run Your Application with the Agent​

Add the Java agent to your application startup command:

java -javaagent:opentelemetry-javaagent.jar -jar your-application.jar

Docker Configuration​

If you're running your Java application in Docker, add the agent to your Dockerfile:

# Download the OpenTelemetry Java agent
RUN wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

# Set environment variables
ENV OTEL_METRICS_EXPORTER=otlp
ENV OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=<OODLE_OTEL_METRICS_ENDPOINT>
ENV OTEL_EXPORTER_OTLP_METRICS_HEADERS=X-API-KEY=<OODLE_API_KEY>,X-OODLE-IGNORE-SCOPE-NAME=true
ENV OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta

# Run your application with the agent
CMD ["java", "-javaagent:opentelemetry-javaagent.jar", "-jar", "your-application.jar"]

Supported Instrumentations​

The Java agent automatically instruments many popular libraries and frameworks. For a complete list, see the OpenTelemetry Java Instrumentation documentation.

Configuration Options​

Suppressing Specific Instrumentations​

You can disable specific instrumentations using environment variables:

export OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false
export OTEL_INSTRUMENTATION_HTTP_ENABLED=false
export OTEL_INSTRUMENTATION_JDbc_ENABLED=false

Performance Considerations​

For detailed information about the performance impact and overhead of using the OpenTelemetry Java agent, please refer to the official OpenTelemetry Java agent performance documentation.

Troubleshooting​

Common Issues​

  1. Agent not loading: Ensure the -javaagent flag is correctly specified
  2. No metrics appearing: Verify your Oodle endpoint and API key are correct
  3. Performance issues: Check if you have too many instrumentations enabled

Debug Mode​

Enable debug logging to troubleshoot issues (not recommended for production as it generates a large volume of logs):

export OTEL_LOG_LEVEL=DEBUG

Support​

If you have any questions or need assistance with Java instrumentation, please contact us via our help chat app located at the bottom-right of the page or by reaching out to support@oodle.ai.