Auto-Instrumentation

What Is Auto-Instrumentation?

Auto-instrumentation adds OpenTelemetry tracing and metrics to your application without code changes. Language-specific agents hook into HTTP clients, database drivers, and frameworks to create spans automatically. This provides immediate visibility with zero code modification.

Java Agent

The Java agent is the most mature auto-instrumentation solution. It uses bytecode manipulation to instrument HTTP clients, servlets, JDBC, gRPC, Kafka, and dozens of other libraries. Attach it as a JVM argument.

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

# Run with the agent
java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.service.name=payment-service \
     -Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \
     -Dotel.metrics.exporter=otlp \
     -Dotel.traces.exporter=otlp \
     -jar payment-service.jar

Node.js Instrumentation

Node.js auto-instrumentation uses the --require flag or a loader hook to patch libraries at startup. The opentelemetry.js package registers instrumentations for HTTP, Express, pg, redis, and other common packages.

// tracing.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  serviceName: 'payment-service',
  traceExporter: new OTLPTraceExporter({
    url: 'http://otel-collector:4317',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

// Run with: node --require ./tracing.js app.js

Python Instrumentation

Python auto-instrumentation uses the opentelemetry-instrument command or sitecustomize hooks. It instruments Flask, Django, FastAPI, requests, psycopg2, and other popular packages.

# Install auto-instrumentation
pip install opentelemetry-distro opentelemetry-exporter-otlp

# Auto-instrument a Flask app
opentelemetry-instrument \
  --service_name payment-service \
  --exporter_otlp_endpoint http://otel-collector:4317 \
  python app.py

Kubernetes Sidecar Injection

In Kubernetes, you can inject the OTel Collector as a sidecar using the OpenTelemetry Operator. The operator automatically instruments your application and routes telemetry to the Collector. This removes the need to modify deployment manifests.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
        instrumentation.opentelemetry.io/otel-sdk-image: "ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest"
    spec:
      containers:
        - name: payment-service
          image: payment-service:latest

Limitations

• Auto-instrumentation captures HTTP and database calls but not business logic.
• Custom spans for specific operations still require manual instrumentation.
• Performance overhead is minimal but non-zero. Measure before deploying.
• Not all libraries are supported. Check the instrumentation list for your language.
• Version compatibility between agent and library versions can cause issues.