Agente de instrumentación automática de AWS X-Ray para Java

El agente de instrumentación automática de AWS X-Ray para Java es una solución de rastreo que instrumenta sus aplicaciones web Java con un mínimo esfuerzo de desarrollo. El agente permite rastrear las aplicaciones basadas en servlets y todas las solicitudes posteriores del agente realizadas con marcos y bibliotecas compatibles. Entre ellas se incluyen las solicitudes HTTP a Apache, solicitudes mediante el SDK de AWS y consultas en SQL posteriores realizadas con un controlador JDBC. El agente propaga el contexto de X-Ray, incluidos todos los segmentos y subsegmentos activos, a través de subprocesos. Todas las configuraciones y la versatilidad del SDK de X-Ray siguen disponibles con el agente para Java. Se eligieron los valores predeterminados adecuados para garantizar que el agente funcione con el mínimo esfuerzo.

Lo más adecuado para la solución del agente de X-Ray son los servidores de aplicaciones web Java de solicitud-respuesta basados en servlets. Si su aplicación utiliza un marco asíncrono o no está bien diseñada como servicio de solicitud-respuesta, la instrumentación manual con el SDK podría ser más conveniente. 

Para crear el agente de X-Ray se ha utilizado el kit de herramientas Distributed Systems Comprehension o DiSCo. DisCo es un marco de código abierto para crear agentes de Java que se puede usar en sistemas distribuidos. Si bien no es necesario entender DisCO para usar el agente de X-Ray, puede obtener más información sobre el proyecto consultando su página de inicio en GitHub. El agente de X-Ray también es de código totalmente abierto. Para ver el código fuente, hacer contribuciones o indicar problemas relacionados con el agente, consulte su repositorio en GitHub.

Aplicación de muestra

La aplicación de muestra eb-java-scorekeep está adaptada para ser instrumentada con el agente de X-Ray. Esta ramificación no contiene ningún filtro de servlet ni configuración de grabadora, ya que estas funciones las realiza el agente. Para ejecutar la aplicación de forma local o utilizando recursos de AWS, siga los pasos indicados en el archivo readme de la aplicación de muestra. Las instrucciones para usar la aplicación de muestra con el fin de generar rastros de X-Ray se encuentran en el tutorial de la aplicación de muestra.

Introducción

Para empezar a utilizar el agente de instrumentación automática de X-Ray para Java en su propia aplicación, siga estos pasos.

1. Ejecute el daemon de X-Ray en su entorno. Para obtener más información, consulte Daemon de X-Ray.

2. Descargue la última distribución del agente. Descomprima el archivo y tome nota de su ubicación en el sistema de archivos. El contenido debe ser similar al siguiente.

   disco 
   ├── disco-java-agent.jar 
   └── disco-plugins 
       ├── aws-xray-agent-plugin.jar 
       ├── disco-java-agent-aws-plugin.jar 
       ├── disco-java-agent-sql-plugin.jar 
       └── disco-java-agent-web-plugin.jar

3. Modifique los argumentos de JVM de su aplicación para incluir lo siguiente y así habilitar el agente. Asegúrese de que el argumento -javaagent esté colocado delante del argumento -jar, si procede. El proceso de modificación de los argumentos de JVM varía en función de las herramientas y los marcos que utilice para lanzar su servidor de Java. Consulte la documentación del marco de su servidor para obtener orientación específica.

   -javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

4. Para especificar cómo aparece el nombre de la aplicación en la consola de X-Ray, establezca la variable de entorno AWS_XRAY_TRACING_NAME o la propiedad de sistema com.amazonaws.xray.strategy.tracingName. Si no se proporciona un nombre, se utilizará un nombre predeterminado.

5. Reinicie el servidor o el contenedor. A partir de ese momento se rastrearán las solicitudes entrantes y sus llamadas posteriores. Si no ve los resultados esperados, consulte Solución de problemas.

Configuración

El agente de X-Ray se configura mediante un archivo JSON externo proporcionado por el usuario. De forma predeterminada, este archivo se encuentra en la raíz de la ruta de clases del usuario denominada xray-agent.json (por ejemplo, en su directorio resources). Puede configurar una ubicación personalizada para el archivo de configuración estableciendo la propiedad de sistema com.amazonaws.xray.configFile en la ruta absoluta del sistema de archivos del archivo de configuración.

A continuación, se muestra un ejemplo de archivo de configuración.

{     
    "serviceName": "XRayInstrumentedService", 
    "contextMissingStrategy": "LOG_ERROR", 
    "daemonAddress": "127.0.0.1:2000", 
    "tracingEnabled": true, 
    "samplingStrategy": "CENTRAL",     
    "traceIdInjectionPrefix": "prefix",     
    "samplingRulesManifest": "/path/to/manifest",     
    "awsServiceHandlerManifest": "/path/to/manifest",     
    "awsSdkVersion": 2,     
    "maxStackTraceLength": 50,     
    "streamingThreshold": 100,     
    "traceIdInjection": true,     
    "pluginsEnabled": true,     
    "collectSqlQueries": false 
}

Especificación de la configuración

En la tabla siguiente se describen valores válidos para cada propiedad. Los nombres de las propiedades hay distinción entre mayúsculas y minúsculas, pero en sus claves no. En el caso de propiedades que las variables de entorno y las propiedades del sistema pueden anular, el orden de prioridad es siempre el siguiente: primero la variable de entorno, luego la propiedad del sistema y, por último, el archivo de configuración. Consulte Variables de entorno para obtener información sobre las propiedades que puede anular. Todos los campos son opcionales.

Nombre de la propiedad	Tipo	Valores válidos	Descripción	Variable de entorno	Propiedad del sistema	Valor predeterminado
serviceName	Cadena	Cualquier cadena	El nombre del servicio instrumentado tal como aparecerá en la consola de X-Ray.	AWS_XRAY_TRACING_NAME	com.amazonaws.xray.strategy.tracingName	XRayInstrumentedService
contextMissingStrategy	Cadena	LOG_ERROR, IGNORE_ERROR	La acción que realiza el agente cuando intenta utilizar el contexto del segmento de X-Ray, pero no hay ninguno.	AWS_XRAY_CONTEXT_MISSING	com.amazonaws.xray.strategy.contextMissingStrategy	LOG_ERROR
daemonAddress	Cadena	Dirección IP y puerto formateados o lista de direcciones TCP y UDP	La dirección que utiliza el agente para comunicarse con el daemon de X-Ray.	AWS_XRAY_DAEMON_ADDRESS	com.amazonaws.xray.emitter.daemonAddress	127.0.0.1:2000
tracingEnabled	Booleano	True, False	Permite la instrumentación mediante el agente de X-Ray.	AWS_XRAY_TRACING_ENABLED	com.amazonaws.xray.tracingEnabled	TRUE
samplingStrategy	Cadena	CENTRAL, LOCAL, NONE o ALL	La estrategia de muestreo que utiliza el agente. ALL captura todas las solicitudes, NONE no captura ninguna. Consulte Reglas de muestreo.	N/A	N/A	CENTRAL
traceIdInjectionPrefix	Cadena	Cualquier cadena	Incluye el prefijo proporcionado antes de los ID de rastro inyectados en los registros.	N/A	N/A	Ninguno (cadena vacía)
samplingRulesManifest	Cadena	Ruta de archivo absoluta	La ruta a un archivo de reglas de muestreo personalizadas que se utilizará como fuente de las reglas de muestreo para la estrategia de muestreo local o las reglas alternativas para la estrategia central.	N/A	N/A	DefaultSamplingRules.json
awsServiceHandlerManifest	Cadena	Ruta de archivo absoluta	La ruta a una lista de parámetros permitidos personalizados que captura información adicional de los clientes del SDK de AWS.	N/A	N/A	DefaultOperationParameterWhitelist.json
awsSdkVersion	Entero	1, 2	Versión del SDK de AWS para Java que está utilizando. Se ignora si no se establece también awsServiceHandlerManifest.	N/A	N/A	2
maxStackTraceLength	Entero	Enteros no negativos	El número máximo de líneas de un rastro de pila que se pueden registrar en una traza.	N/A	N/A	50
streamingThreshold	Entero	Enteros no negativos	Una vez cerrados al menos este número de subsegmentos, se transmiten al daemon fuera de banda para evitar que los fragmentos sean demasiado grandes.	N/A	N/A	100
traceIdInjection	Booleano	True, False	Permite la inyección de los ID de rastro de X-Ray en los registros si también se agregan las dependencias y la configuración descritas en la configuración de registro. De lo contrario, no hace nada.	N/A	N/A	TRUE
pluginsEnabled	Booleano	True, False	Habilita los complementos que registran metadatos sobre los entornos de AWS en los que está operando. Consulte Complementos de servicio.	N/A	N/A	TRUE
collectSqlQueries	Booleano	True, False	Registra cadenas de consultas SQL en subsegmentos SQL en la medida de lo posible.	N/A	N/A	FALSE
contextPropagation	Booleano	True, False	Propaga automáticamente el contexto de X-Ray entre subprocesos si es verdadero. De lo contrario, utiliza Thread Local para almacenar el contexto y se requiere la propagación manual de un subproceso a otro.	N/A	N/A	TRUE

Configuración de registro

El nivel de registro del agente de X-Ray se puede configurar de la misma manera que el SDK de X-Ray para Java. Consulte Registro para obtener más información sobre la configuración del registro con el SDK de X-Ray para Java.

Instrumentación manual

Si desea realizar la instrumentación manual además de la instrumentación automática del agente, añada el SDK de X-Ray como una dependencia a su proyecto. Tenga en cuenta que los filtros de servlets personalizados del SDK que se mencionan en Rastreo de solicitudes entrantes no son compatibles con el agente de X-Ray.

nota

Debe usar la última versión del SDK de X-Ray para realizar la instrumentación manual y usar el agente al mismo tiempo.

Si está trabajando en un proyecto de Maven, añada las siguientes dependencias a su archivo pom.xml.

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

Si está trabajando en un proyecto de Gradle, añada las siguientes dependencias a su archivo build.gradle.

implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' 

Puede agregar subsegmentos personalizados además de anotaciones, metadatos e identificadores de usuariomientras usas el agente, tal como lo haría con el SDK normal. El agente propaga automáticamente el contexto de un subproceso a otro, por lo que no deberían hacer falta soluciones provisionales para propagar el contexto cuando se trabaja con aplicaciones multiproceso.

Solución de problemas

Como el agente ofrece una instrumentación totalmente automática, puede resultar difícil identificar la causa raíz de un problema cuando se están produciendo problemas. Si el agente de X-Ray no funciona según lo esperado, revise los siguientes problemas y soluciones. El agente y el SDK de X-Ray utilizan Jakarta Commons Logging (JCL). Para ver el resultado del registro, asegúrese de que un puente que conecte JCL con su backend de registro esté en la ruta de clases, como en el siguiente ejemplo: log4j-jcl o jcl-over-slf4j.

Problema: he habilitado el agente para Java en mi aplicación, pero no veo nada en la consola de X-Ray

¿El daemon de X-Ray se está ejecutando en la misma máquina?

Si no es así, consulte la documentación del daemon de X-Ray para configurarlo.

¿Ve un mensaje similar a "Initializing the X-Ray agent recorder" en los registros de su aplicación?

Si ha agregado correctamente el agente a la aplicación, este mensaje estará registrado en el nivel INFO cuando se inicie la aplicación, antes de que esta comience a recibir solicitudes. Si este mensaje no aparece, significa que el agente para Java no se está ejecutando con el proceso de Java. Asegúrese de haber seguido todos los pasos de configuración correctamente sin errores tipográficos.

¿Ve varios mensajes de error que digan algo así como "Suppressing AWS X-Ray context missing exception" en los registros de su aplicación?

Estos errores se producen porque el agente está intentando instrumentar las solicitudes posteriores, como las solicitudes del SDK de AWS o las consultas en SQL, pero no ha podido crear un segmento automáticamente. Si ve muchos de estos errores, es posible que el agente no sea la mejor herramienta para el uso que usted le quiere dar y, en su lugar, tal vez debería considerar la instrumentación manual con el SDK de X-Ray. Como alternativa, puedes habilitar los registros de depuración del SDK de X-Ray para ver el rastro de pila del punto donde se producen las excepciones de falta de contexto. Puede agrupar estas porciones del código con segmentos personalizados, lo que debería corregir estos errores. Para ver un ejemplo de cómo encapsular las solicitudes posteriores con segmentos personalizados, consulte el código de muestra que aparece en Instrumentación de código de inicio.

Problema: algunos de los segmentos que espero no aparecen en la consola de X-Ray

¿Su aplicación utiliza el multiproceso?

Si espera que se creen ciertos segmentos pero no aparecen en la consola, la causa pueden ser subprocesos en segundo plano en la aplicación. Si su aplicación realiza tareas mediante subprocesos en segundo plano que “se activan y se olvidan”, como realizar una llamada puntual a una función de Lambda con el SDK de AWS o sondear periódicamente algún punto de conexión HTTP, podría confundir al agente mientras propaga el contexto de un subproceso a otro. Para comprobar que este es su problema, habilite los registros de depuración del SDK de X-Ray y mire a ver si hay mensajes como este: Not emitting segment named <NOMBRE > as it parents in-progress subsegments. Para solucionar este problema, puede intentar unir los subprocesos en segundo plano antes de que el servidor vuelva a funcionar para asegurarse de que todo el trabajo realizado en ellos queda registrado. O bien, puede establecer la configuración contextPropagation del agente en false para inhabilitar la propagación del contexto en subprocesos en segundo plano. En ese caso, tendrá que instrumentar manualmente esos subprocesos con segmentos personalizados o ignorar las excepciones de falta de contexto que generen.

¿Ha establecido reglas de muestreo?

Si aparecen segmentos aparentemente aleatorios o inesperados en la consola de X-Ray, o los segmentos que esperaba que estuvieran en la consola no están, es posible que tenga un problema de muestreo. El agente de X-Ray lleva a cabo un muestreo centralizado en todos los segmentos que crea, aplicando las reglas de la consola de X-Ray. La regla por defecto es obtener muestras en 1 segmento por segundo y, posteriormente, en el 5 % de los segmentos. Eso significa que es posible que no se obtengan muestras de los segmentos que se creen rápidamente con el agente. Para solucionar este problema, debe crear reglas de muestreo personalizadas en la consola de X-Ray para un muestreo adecuado de los segmentos deseados. Para obtener más información, consulte Configuración de reglas de muestreo.