#Java Auto-instrumentation

The Java auto-instrumentation provides comprehensive telemetry collection for Java applications using the OpenTelemetry Java agent. This instrumentation automatically captures traces, metrics, and logs from Java applications and popular frameworks without requiring code modifications.

#How Java Auto-instrumentation Works

The Operator injects the OpenTelemetry Java agent into Java application containers as a Java agent JAR file. The agent uses bytecode instrumentation to automatically instrument Java classes at runtime, capturing telemetry data from:

• HTTP servers and clients (Servlet, Spring MVC, JAX-RS, etc.)
• Database clients (JDBC, Hibernate, etc.)
• Messaging systems (JMS, Kafka, RabbitMQ, etc.)
• RPC frameworks (gRPC, etc.)
• Caching libraries (Redis, Memcached, etc.)
• And many other popular Java libraries and frameworks

#Enabling Java Instrumentation

To enable auto-instrumentation for Java applications, annotate your pod or namespace:

apiVersion: v1
kind: Pod
metadata:
  name: java-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
spec:
  containers:
  - name: app
    image: myjavaapp:latest

The Operator automatically injects the Java agent and configures the JVM to load it at startup by setting the JAVA_TOOL_OPTIONS environment variable with the -javaagent flag.

#Java Agent Environment Variables

The following environment variables control Java agent behavior:

#Instrumentation Control

• OTEL_JAVAAGENT_ENABLED - Enable or disable the Java agent (default: true)
• OTEL_JAVAAGENT_DEBUG - Enable debug logging for the agent (default: false)
• OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED - Enable all instrumentations by default (default: true)

#Specific Instrumentation Control

You can enable or disable specific instrumentations:

• OTEL_INSTRUMENTATION_JDBC_ENABLED - JDBC instrumentation
• OTEL_INSTRUMENTATION_SPRING_WEB_ENABLED - Spring Web instrumentation
• OTEL_INSTRUMENTATION_KAFKA_ENABLED - Kafka instrumentation
• OTEL_INSTRUMENTATION_REDIS_ENABLED - Redis instrumentation

Example configuration:

spec:
  java:
    env:
      - name: OTEL_INSTRUMENTATION_JDBC_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_KAFKA_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_REDIS_ENABLED
        value: "false"

#Extension Configuration

Configure additional agent extensions:

• OTEL_JAVAAGENT_EXTENSIONS - Path to additional agent extensions
• OTEL_JAVAAGENT_CONFIGURATION_FILE - Path to agent configuration file

#Advanced Configuration

#Custom Agent Image

You can specify a custom Java agent image:

spec:
  java:
    image: my-registry.com/custom-java-agent:my-tag

#Volume Mounts

The agent is mounted into the application container at /otel-auto-instrumentation-java-<container-name>/.

#Container-specific Injection

For multi-container pods, specify which containers should be instrumented:

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/container-names: "app,worker"

#Supported Java Versions

The OpenTelemetry Java agent supports:

• Java 8 and later

#Troubleshooting

#Verifying Agent Injection

Check that the agent was injected successfully:

kubectl describe pod <pod-name>

Look for the -javaagent argument in the container command.

#Enabling Debug Logging

Enable debug logging to troubleshoot issues:

spec:
  java:
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "true"
      - name: OTEL_LOG_LEVEL
        value: "debug"

#Common Issues

Agent not loading: Verify that the init container completed successfully and the agent JAR is present in the shared volume.

Missing traces: Check that the exporter endpoint is correct and accessible from the application pod.

High memory usage: Reduce the number of enabled instrumentations or adjust JVM heap settings.

#Example Configuration

Complete example for Java application instrumentation:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: java-instrumentation
  namespace: java-development
spec:
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "false"
  exporter:
    endpoint: http://otel-collector.observability.svc:4318
  env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: deployment.environment.name=development
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  propagators:
    - tracecontext
    - baggage
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: java-app
  namespace: java-development
spec:
  replicas: 1
  selector:
    matchLabels:
      app: java-app
  template:
    metadata:
      labels:
        app: java-app
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
      - name: app
        image: myjavaapp:latest
        ports:
        - containerPort: 8080

#Configuration Reference

For detailed configuration options, supported libraries, and advanced usage scenarios, refer to the official OpenTelemetry Operator documentation:

Java Auto-instrumentation Documentation