Requisitos de compatibilidad

La última versión del rastreador Java es compatible con todas las máquinas virtuales Java a partir de la versión 8. Para obtener más información sobre las versiones anteriores a la v8, consulta Tiempos de ejecución de máquinas virtuales Java compatibles.

Para ver la lista completa de versiones y marcos de trabajo Java compatibles con Datadog (incluidas las versiones heredadas y de mantenimiento) consulta los requisitos de compatibilidad.

Para empezar

Antes de empezar, asegúrate de haber instalado y configurado el Agent.

Instrumentación de tu aplicación

Después de instalar y configurar tu Datadog Agent, el siguiente paso es añadir la biblioteca de rastreo directamente en la aplicación para instrumentarla. Consulta más bibliografía con información sobre la compatibilidad.

Para empezar a rastrear tus aplicaciones:

  1. Descarga dd-java-agent.jar, que contiene los últimos archivos de clase de rastreo, en una carpeta a la que tengas acceso con tu usuario de Datadog:
wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar

Nota: Para descargar la última compilación de una versión mayor específica, utiliza el enlace https://dtdg.co/java-tracer-vX, donde X es la versión mayor deseada. Por ejemplo, utiliza https://dtdg.co/java-tracer-v1 para la última versión 1 de compilación. No debe incluir los números de las versiones menores. Para obtener cualquier versión específica, también puedes consultar el repositorio Maven de Datadog.

Nota: Las versiones candidatas (Release Candidate) están disponibles en GitHub DataDog/dd-trace-java releases. Estas versiones tienen “RC” y se recomiendan para tests fuera de tu entorno de producción. Puedes suscribirse a las notificaciones sobre versiones de GitHub para recibir avisos cuando haya nuevas versiones candidatas disponibles para tests. Si tienes algún problema con las versiones candidatas, ponte en contacto con el servicio de asistencia de Datadog.

  1. Para ejecutar tu aplicación desde un script de aplicación IDE, Maven o Gradle, o desde un comando java -jar, con el Continuous Profiler, el rastreo de despliegues y la inyección de logs (si envías logs a Datadog), añade el argumento de máquina virtual Java -javaagent y las siguientes opciones de configuración, según corresponda:

    java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -XX:FlightRecorderOptions=stackdepth=256 -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar
    

    Si tienes mucha necesidad de reducir el tamaño de tu imagen y omitir módulos, puedes utilizar el comando jdeps para identificar dependencias. Sin embargo, los módulos necesarios pueden cambiar con el tiempo, así que hazlo bajo tu propia responsabilidad.

    Habilitar la creación de perfiles puede afectar a tu factura en función de tu paquete APM. Para obtener más información, consulta la página de tarifas.
Variable de entornoPropiedad del sistemaDescripción
DD_ENVdd.envTu entorno de aplicación (production, staging, etc.)
DD_LOGS_INJECTIONdd.logs.injectionHabilita la inyección automática de claves MDC para los ID de rastreo y de tramos (spans) de Datadog. Para ver más detalles, consulta Uso avanzado.

Beta: A partir de la versión 1.18.3, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes configurar DD_LOGS_INJECTION en la interfaz de usuario Catálogo de servicios.
DD_PROFILING_ENABLEDdd.profiling.enabledActivar el Continuous Profiler
DD_SERVICEdd.serviceNombre de un conjunto de procesos que llevan a cabo la misma tarea. Se utiliza para agrupar estadísticas de tu aplicación.
DD_TRACE_SAMPLE_RATEdd.trace.sample.rateConfigura una frecuencia de muestreo en la raíz de la traza para todos los servicios.

Beta: A partir de la versión 1.18.3, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes configurar DD_TRACE_SAMPLE_RATE en la interfaz de usuario Catálogo de servicios.
DD_TRACE_SAMPLING_RULESdd.trace.sampling.rulesConfigura una frecuencia de muestreo en la raíz de la traza para los servicios que coinciden con la regla especificada.
DD_VERSIONdd.versionLa versión de tu aplicación (por ejemplo, 2.5, 202003181415 o 1.3-alpha)

Las opciones de configuración adicionales se describen a continuación.

Añadir la versión del rastreador Java a la máquina virtual Java

Consulta la documentación de tu servidor de aplicaciones para saber cómo pasar -javaagent y otros argumentos de máquinas virtuales Java. Aquí encontrarás las instrucciones para algunos de los marcos de trabajo más frecuentes:

Si tu aplicación se denomina my_app.jar, crea un my_app.conf que contenga:

JAVA_OPTS=-javaagent:/path/to/dd-java-agent.jar

Para obtener más información, consulta la documentación sobre Spring Boot.

Linux

Para habilitar el rastreo cuando se ejecuta Tomcat en Linux:

  1. Abre tu archivo de script de inicio de Tomcat, por ejemplo setenv.sh.
  2. Añade lo siguiente a setenv.sh:
    CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"
    

Windows (Tomcat como servicio de Windows)

Para habilitar el rastreo cuando se ejecuta Tomcat como servicio de Windows:

  1. Abre un Command Prompt.
  2. Ejecuta el siguiente comando para actualizar la configuración de tu servicio Tomcat:
    tomcat8 //US//<SERVICE_NAME> --Environment="CATALINA_OPTS=%CATALINA_OPTS% -javaagent:\"c:\path\to\dd-java-agent.jar\""
    
    Sustituye <SERVICE_NAME> por el nombre de tu servicio Tomcat y sustituye la ruta por dd-java-agent.jar.
  3. Reinicia tu servicio Tomcat para que los cambios se apliquen.

Windows (Tomcat con script de configuración de entorno)

Para habilitar el rastreo cuando se ejecuta Tomcat con un script de configuración de entorno:

  1. Crea setenv.bat en el directorio ./bin de la carpeta del proyecto Tomcat, si no existe.
  2. Añade lo siguiente a setenv.bat:
    set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"
    

Si el paso anterior no funciona, intenta añadir lo siguiente:

set JAVA_OPTS=%JAVA_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"
  • En modalidad independiente:

    Añade la siguiente línea al final de standalone.conf:

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/dd-java-agent.jar"
  • En modalidad independiente y en Windows, añade la siguiente línea al final de standalone.conf.bat:
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/dd-java-agent.jar"
  • En modalidad de dominio:

    Añade la siguiente línea en el archivo domain.xml, debajo de la etiqueta (tag) server-groups.server-group.jvm.jvm-options:

<option value="-javaagent:/path/to/dd-java-agent.jar"/>

Para obtener más información, consulta la documentación de JBoss.

Si utilizas jetty.sh para iniciar Jetty como servicio, edítalo y añade:

JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/dd-java-agent.jar"

Si utilizas start.ini para iniciar Jetty, añade la siguiente línea (debajo de --exec o añade la línea --exec si no está allí):

-javaagent:/path/to/dd-java-agent.jar

En la consola administrativa:

  1. Selecciona Servers (Servidores). En Server Type (Tipo de Servidor), selecciona WebSphere application servers (Servidores de la aplicación WebSphere) y elige tu servidor.
  2. Selecciona Java and Process Management > Process Definition (Java y Gestión de procesos > Definición de procesos).
  3. En la sección Additional Properties (Propiedades adicionales), haz clic en Java Virtual Machine (Máquina virtual Java).
  4. En el campo Generic JVM arguments (Argumentos de máquinas virtuales Java genéricos), introduce:
-javaagent:/path/to/dd-java-agent.jar

Para ver más detalles y opciones, consulta la documentación de WebSphere.

Nota

  • Si quieres añadir el argumento -javaagent a tu comando java -jar, tienes que añadirlo antes del argumento -jar como opción de la máquina virtual Java y no como un argumento de aplicación. Por ejemplo:

    java -javaagent:/path/to/dd-java-agent.jar -jar my_app.jar
    

    Para obtener más información, consulta la documentación sobre Oracle.

  • No añadas dd-java-agent a tu classpath, ya que podría provocar un comportamiento inesperado.

Instrumentación automática

La instrumentación automática para Java utiliza las capacidades de instrumentación java-agent que proporciona la máquina virtual Java. Cuando se registra un java-agent, puede modificar archivos de clase durante la carga.

Nota: Las clases que se cargan con un ClassLoader remoto no se instrumentan de forma automática.

La instrumentación puede venir de la instrumentación automática, de la API OpenTracing o de una combinación de ambas. La instrumentación suele registrar los siguientes datos:

  • La duración normalmente se registra con el reloj NanoTime de la máquina virtual Java, salvo si la API OpenTracing proporciona una marca de tiempo
  • Pares de etiquetas clave/valor
  • Errores y trazas de stacks tecnológicos que la aplicación no gestiona
  • Número total de trazas (solicitudes) que circulan por el sistema

Configuración

Si es necesario, configura la biblioteca de rastreo para que envíe datos de telemetría sobre el rendimiento de la aplicación, según sea necesario, incluida la configuración del etiquetado unificado de servicios. Para ver más detalles, consulta la configuración de bibliotecas.

Leer más