La instrumentación sin código adjunta un agente a tu aplicación al arrancar. El agente parchea librerías comunes, como servidores y clientes HTTP, drivers de bases de datos y colas de mensajes, y produce trazas, métricas y logs sin cambiar el código fuente. La configuración son las variables de entorno estándar OTEL_* más unas pocas específicas de cada lenguaje, así que toda la configuración es una línea de Dockerfile y unas cuantas variables. Esta guía cubre Java, Python y Node.js.

Requisito previo: un lugar al que enviar datos

Ten un Collector escuchando, por ejemplo el de la guía de Docker Compose, en otel-collector:4318 (HTTP) o :4317 (gRPC). Todos los ejemplos de abajo apuntan a él con OTEL_EXPORTER_OTLP_ENDPOINT.

Java

Descarga el JAR del agente una vez y luego adjúntalo con -javaagent:

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

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=checkout \
     -jar myapp.jar

Los contenedores suelen preferir variables de entorno, con JAVA_TOOL_OPTIONS llevando el flag para no cambiar el entrypoint:

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY myapp.jar .
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/<version>/opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/opentelemetry-javaagent.jar"
CMD ["java", "-jar", "myapp.jar"]

Fija la versión del agente en la URL de descarga en lugar de usar latest, para que las builds sean reproducibles. Luego configúralo en tiempo de ejecución:

OTEL_SERVICE_NAME=checkout \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging \
java -jar myapp.jar

El agente puede configurarse de tres maneras: propiedades de sistema (-Dotel.service.name=...), variables de entorno o un archivo de propiedades al que se hace referencia con OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/file.properties (o -Dotel.javaagent.configuration-file). Mantén el archivo de propiedades en Git cuando tengas muchos ajustes. Para depurar el propio agente, define OTEL_JAVAAGENT_DEBUG=true, y espera una salida muy verbosa. El agente también soporta un archivo de configuración YAML declarativo; consulta la documentación del agente de Java.

Python

Instala la distribución, el exporter OTLP y las librerías de instrumentación que coincidan con tus paquetes instalados:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap -a install escanea tu entorno e instala la instrumentación de lo que encuentra, por ejemplo la instrumentación de Flask cuando Flask está instalado. Ejecuta opentelemetry-bootstrap sin argumentos para ver sus recomendaciones sin instalar. Inicia la aplicación a través de opentelemetry-instrument:

OTEL_SERVICE_NAME=checkout \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
opentelemetry-instrument python myapp.py

Fíjate en las barras invertidas finales: cada variable debe estar en la misma línea de comando lógica que opentelemetry-instrument, o no llegará al proceso. Para servidores como Gunicorn o Uvicorn, envuelve el comando del servidor: opentelemetry-instrument gunicorn app:app. Algunas configuraciones con el gestor de paquetes uv necesitan una solución alternativa para el paso de bootstrap, que describe la página de solución de problemas de Python. La exportación de logs es opcional en Python, así que consulta la sección de logging de la documentación de Python si los logs no aparecen.

Un patrón de Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt \
 && pip install opentelemetry-distro opentelemetry-exporter-otlp \
 && opentelemetry-bootstrap -a install
COPY . .
CMD ["opentelemetry-instrument", "python", "myapp.py"]

Node.js

Instala la API y el paquete de auto-instrumentación:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

Cárgalo antes de tu aplicación con --require, o mediante NODE_OPTIONS:

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_NODE_RESOURCE_DETECTORS=env,host,os
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js

OTEL_NODE_RESOURCE_DETECTORS limita qué detectores de recursos se ejecutan (todos están habilitados por defecto). OTEL_NODE_ENABLED_INSTRUMENTATIONS limita qué instrumentaciones se cargan; consulta la página de configuración del módulo. OTEL_LOG_LEVEL acepta none, error, warn, info, debug, verbose y all, con info como valor predeterminado. Mantenlo en info en producción, ya que la salida de depuración perjudica el rendimiento. Las aplicaciones con módulos ES pueden necesitar una opción adicional de loader; sigue la documentación de Node.js para tu sistema de módulos.

.NET, Go y otros

.NET tiene un agente sin código que se configura del mismo modo (variables de entorno más un script de arranque). Go usa un agente basado en eBPF que se ejecuta como un sidecar privilegiado y necesita la ruta del ejecutable objetivo, así que se usa sobre todo a través del Operator. Consulta la sección de zero-code de la documentación para cada uno.

Qué obtienes y qué no

Obtienes spans para HTTP entrante y saliente, llamadas a bases de datos y librerías de mensajería comunes, junto con métricas de runtime en algunos lenguajes. No obtienes spans a nivel de negocio, como “calcular descuento”, porque el agente no puede saber de ellos. Añade unos pocos spans o atributos manuales con la API de OpenTelemetry donde el detalle extra compense, y mantén el agente para todo lo demás.

Verifica que funciona

1. Inicia la aplicación con el exporter debug del Collector habilitado.
2. Envía una petición: curl http://localhost:8080/.
3. Busca en el log del Collector spans con tu service.name:

docker compose logs otel-collector | grep -i 'service.name'

Si no llega nada, comprueba en este orden: que el endpoint y el puerto coinciden con el protocolo, que el pipeline del Collector para la señal lista el receiver otlp, que la aplicación puede resolver el nombre de host del Collector y que OTEL_SDK_DISABLED no está definida. La guía de solución de problemas amplía cada punto.

Notas de producción

• Fija las versiones del agente y de la distribución, y actualízalas de forma deliberada.
• Define service.name, service.version y deployment.environment.name en cada servicio, porque los dashboards dependen de ellos.
• Empieza con un ratio de muestreo en lugar de conservarlo todo (consulta la guía de muestreo).
• En Kubernetes, usa el Operator para inyectar el agente mediante una anotación en lugar de editar cada Dockerfile.