Agente de OpenTelemetry para Java: instrumentar una aplicación y enviarla a Dynatrace

Agente de OpenTelemetry para Java: descárgalo, configura la exportación OTLP a Dynatrace, despliega en VM o Kubernetes y verifica trazas, métricas y logs.
Agent OpenTelemetry Java : instrumenter une application et l'envoyer à Dynatrace

Tu equipo quiere una instrumentación estándar, portable y sin tocar el código de una aplicación Spring Boot. No tiene OneAgent en esos contenedores, o ha elegido OpenTelemetry como norma de plataforma. El agente de OpenTelemetry para Java responde a esa necesidad: un archivo JAR que se añade al arranque de la JVM, y las trazas, métricas y logs salen en OTLP hacia Dynatrace.

Objetivo de este tutorial: descargar el agente, configurarlo mediante variables de entorno para enviar las tres señales a Dynatrace, desplegarlo en una VM y luego en Kubernetes, y verificar la llegada de los datos. El contenido sirve para Dynatrace SaaS y Dynatrace Managed; solo cambia la URL del endpoint.

Si el mismo proceso ya lo monitoriza OneAgent, lee primero OneAgent y OpenTelemetry: evitar los duplicados. Dos autoinstrumentaciones en una misma JVM producen spans duplicados.

Requisitos previos

  • Java 8 o superior (comprueba la matriz de compatibilidad de la versión de agente elegida).
  • Un token de API de Dynatrace con los scopes openTelemetryTrace.ingest, metrics.ingest y logs.ingest.
  • La URL del endpoint OTLP:
    • SaaS: https://<env-id>.live.dynatrace.com/api/v2/otlp;
    • Managed: https://<votre-domaine>/e/<env-id>/api/v2/otlp;
    • mediante un ActiveGate: https://<activegate>:9999/e/<env-id>/api/v2/otlp.
  • Acceso HTTPS de salida desde la aplicación, o un Collector intermedio.

Pasos para configurar el agente de OpenTelemetry para Java

Paso 1: descargar el agente

mkdir -p /opt/otel
curl -fsSL -o /opt/otel/opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

En producción, sustituye latest por una versión fija (por ejemplo download/v2.x.y/) para que cada build sea reproducible, y prueba las subidas de versión como una dependencia más.

Paso 2: configurar la exportación hacia Dynatrace

Crea un archivo de entorno /etc/checkout/otel.env:

OTEL_SERVICE_NAME=checkout
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=production
OTEL_EXPORTER_OTLP_ENDPOINT=https://abc12345.live.dynatrace.com/api/v2/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Api-Token%20dt0c01.XXXX.YYYY
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PROPAGATORS=tracecontext,baggage

Líneas críticas:

  • OTEL_EXPORTER_OTLP_ENDPOINT: la URL base, sin /v1/traces. El propio agente añade /v1/traces, /v1/metrics y /v1/logs.
  • OTEL_EXPORTER_OTLP_HEADERS: el espacio entre Api-Token y el token se codifica como %20, como prevé la especificación de las variables de OpenTelemetry.
  • http/protobuf: la API OTLP de Dynatrace espera HTTP con protobuf. Para gRPC, pasa por un Collector.
  • delta: Dynatrace espera métricas con temporalidad delta. Sin esta línea, pueden rechazarse contadores; todo está explicado en la temporalidad de las métricas OTLP.

No versiones nunca este archivo con el token: inyéctalo desde tu gestor de secretos.

Paso 3: arrancar la JVM con el agente (VM o bare metal)

Unidad systemd mínima:

[Unit]
Description=Checkout service
After=network-online.target

[Service]
EnvironmentFile=/etc/checkout/otel.env
ExecStart=/usr/bin/java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar /opt/checkout/checkout.jar
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl restart checkout

La opción -javaagent debe ir antes de -jar; de lo contrario se pasa como argumento a la aplicación y se ignora.

Paso 4: variante en Kubernetes

Copia el agente a un volumen compartido con un init container y cárgalo después con JAVA_TOOL_OPTIONS:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
spec:
  replicas: 2
  selector:
    matchLabels: { app: checkout }
  template:
    metadata:
      labels: { app: checkout }
    spec:
      volumes:
        - name: otel
          emptyDir: {}
      initContainers:
        - name: otel-agent
          image: curlimages/curl:8.10.1
          command: ["curl", "-fsSL", "-o", "/otel/opentelemetry-javaagent.jar",
                    "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.10.0/opentelemetry-javaagent.jar"]
          volumeMounts: [{ name: otel, mountPath: /otel }]
      containers:
        - name: app
          image: registry.example.com/checkout:1.4.2
          envFrom:
            - secretRef: { name: checkout-otel }
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/otel/opentelemetry-javaagent.jar"
          volumeMounts: [{ name: otel, mountPath: /otel }]

El secreto checkout-otel contiene las variables del paso 2. La versión del agente y la imagen de curl son ejemplos: toma una versión publicada y validada en tu entorno. Con el operador de OpenTelemetry, el recurso Instrumentation automatiza esta inyección. Para una exportación centralizada, apunta mejor el endpoint a un Collector de OpenTelemetry que custodie el token.

Cómo comprobar que funciona

  1. Logs de arranque: la JVM muestra una línea del tipo opentelemetry-javaagent - version: 2.x.y. Si falta, el agente no está cargado.
  2. Errores de exportación: busca Failed to export en los logs. Un código 401 o 403 indica un token o un scope incorrecto; un 404, una URL de endpoint errónea.
  3. Modo debug puntual: OTEL_JAVAAGENT_DEBUG=true muestra los spans en la consola. Retíralo después, es muy verboso.
  4. En Dynatrace SaaS, ejecuta en un Notebook:
fetch spans, from: now() - 15m
| filter service.name == "checkout"
| summarize requetes = count(), by: { span.name }
| sort requetes desc
| limit 20

Deberías ver las rutas HTTP de la aplicación. Para los logs: fetch logs | filter service.name == "checkout" | limit 20. En Managed, el servicio aparece en la lista de servicios y las trazas en la vista de trazas distribuidas; las métricas se ven en el explorador de datos. Las pantallas exactas dependen de tu versión: consulta la documentación de OpenTelemetry de Dynatrace.

Resolución de problemas

  • Ningún dato, ningún error: la imagen no lee la variable JAVA_TOOL_OPTIONS (algunas imágenes base la redefinen en su script de arranque). Comprueba con kubectl exec que la JVM muestra «Picked up JAVA_TOOL_OPTIONS».
  • Hay trazas, faltan métricas: la temporalidad se quedó en cumulative, o el token no tiene el scope metrics.ingest.
  • Logs duplicados: la aplicación ya escribe en la salida estándar, que recoge otro agente. Elige un único camino para los logs.
  • Arranque más lento: el agente añade un coste al arranque de la JVM. Ajusta las sondas de disponibilidad (readiness) si fallan tras añadir el agente.
  • Errores TLS: detrás de un proxy corporativo, la JVM debe confiar en el certificado del proxy (truststore de Java); si no, la exportación falla en silencio en la aplicación.

Buenas prácticas

  • Un service.name estable por servicio: sostiene los SLO y las alertas, consulta las alertas de burn rate de SLO.
  • Rellena service.version en cada despliegue: comparar dos versiones resulta inmediato.
  • Desactiva las instrumentaciones innecesarias en lugar de filtrar después (OTEL_INSTRUMENTATION_<NOM>_ENABLED=false).
  • Muestrea con prudencia: un muestreo demasiado agresivo en el cliente falsea los SLI calculados sobre los spans.
  • Nunca un agente de OpenTelemetry en una JVM ya instrumentada por OneAgent.

Preguntas frecuentes

¿Hay que modificar el código de la aplicación?

No para la instrumentación básica: el agente instrumenta automáticamente los frameworks habituales (HTTP, JDBC, mensajería). Añade la API de OpenTelemetry solo para spans o atributos de negocio.

¿Envío directo o mediante un Collector?

El envío directo vale para una prueba o unos pocos servicios. A partir de ahí, un Collector centraliza el token, el filtrado y los reintentos.

¿Se capturan los logs de la aplicación?

El agente captura los appenders de las bibliotecas de logs habituales (Logback, Log4j) cuando la exportación de logs está activa, con el identificador de traza asociado. Comprueba tu biblioteca en la lista de instrumentaciones compatibles.

Conclusión

Con un JAR y una decena de variables, el agente de OpenTelemetry para Java envía trazas, métricas y logs a Dynatrace sin tocar el código. Fija la versión, impón la temporalidad delta, mantén un único propietario de la instrumentación por proceso y verifica en Grail. Tus SLO pasan a apoyarse en datos estándar y portables.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión. Las funciones evolucionan rápido: comprueba su disponibilidad en tu entorno y en la documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
OneAgent OpenTelemetry doublons : éviter les spans en double et le contexte cassé

OneAgent y OpenTelemetry duplicados: evitar spans repetidos y contexto roto

Next Post
Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l'erreur qui fait disparaître vos compteurs

Temporalidad de las métricas OTLP hacia Dynatrace: delta o cumulative, el error que hace desaparecer tus contadores

Related Posts