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

El agente de AWS X-Ray autoinstrumentación 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. Esto incluye HTTP las solicitudes y SQL consultas posteriores de AWS SDK Apache realizadas mediante 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 X-Ray SDK siguen estando disponibles con el agente 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ñado como un servicio de solicitud-respuesta, puede que prefiera considerar la instrumentación manual con él. SDK 

El agente X-Ray se creó con el kit de herramientas de comprensión de sistemas distribuidos, o D. iSCo D iSCo es un marco de código abierto para crear agentes Java que se pueden usar en sistemas distribuidos. Si bien no es necesario comprender D iSCo para usar el agente de rayos X, puede obtener más información sobre el proyecto visitando 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 plantear problemas sobre el agente, visita su repositorio en GitHub.

Aplicación de muestra

La aplicación eb-java-scorekeepde muestra está adaptada para ser instrumentada con el agente de rayos X. 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 AWS X-Ray demonio.

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 JVM argumentos de su solicitud para incluir lo siguiente, lo que habilitará al agente. Asegúrese de que el argumento -javaagent esté colocado delante del argumento -jar, si procede. El proceso de modificación de JVM los argumentos varía en función de las herramientas y los marcos que utilice para lanzar el servidor 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 Resolución de problemas.

Configuración

El agente X-Ray se configura mediante un JSON archivo 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. Para obtener información sobre las propiedades que puede anular, consulte. Variables de entorno Todos los campos son opcionales.

Nombre de la propiedad	Tipo	Valores válidos	Descripción	Variable de entorno	Propiedad del sistema	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 TCP de UDP direcciones	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, ALL	La estrategia de muestreo que utiliza el agente. ALLcaptura todas las solicitudes, no NONE captura ninguna solicitud. Consulte Reglas de muestreo.	N/A	N/A	CENTRAL
traceIdInjectionPrefijo	Cadena	Cualquier cadena	Incluye el prefijo proporcionado antes de inyectar la traza IDs 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
awsServiceHandlerManifiesto	Cadena	Ruta de archivo absoluta	La ruta a una lista de parámetros permitidos personalizada, que captura información adicional de AWS SDK los clientes.	N/A	N/A	DefaultOperationParameterWhitelist.json
awsSdkVersion	Entero	1, 2	Versión de la versión AWS SDKpara Java que estás usando. Se ignora si no se establece también awsServiceHandlerManifest.	N/A	N/A	2
maxStackTraceLongitud	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 out-of-band 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 los metadatos sobre los AWS entornos en los que se opera. Consulte Complementos de servicio.	N/A	N/A	TRUE
collectSqlQueries	Booleano	True, False	Registra las cadenas de SQL consulta en SQL subsegmentos según el mejor esfuerzo 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 X-Ray SDK para Java. Consulte Registro para obtener más información sobre la configuración del registro con X-Ray SDK para Java.

Instrumentación manual

Si desea realizar una instrumentación manual además de la autoinstrumentación del agente, añada el X-Ray SDK como una dependencia a su proyecto. Tenga en cuenta que los filtros SDK de servlet personalizados que se mencionan en Tracing Incoming Requests no son compatibles con el agente X-Ray.

nota

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

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 añadir subsegmentos personalizados además de las anotaciones, los metadatos y el usuario IDs mientras utiliza el agente, tal y como haría normalmente. SDK 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.

Resolució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 de X-Ray y el SDK uso de Jakarta Commons Logging (JCL). Para ver el resultado del registro, asegúrese de que un puente que se conecte JCL a su servidor de registro esté en la ruta de clases, como en el siguiente ejemplo: o. log4j-jcl 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 “Iniciando la grabadora del agente de X-Ray” en los registros de su aplicación?

Si ha agregado correctamente el agente a su aplicación, este mensaje se registra en el INFO nivel cuando se inicia la aplicación, antes de que 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.

En los registros de su aplicación, ¿ve varios mensajes de error que digan algo así como «Suprimir la excepción por falta de AWS X-Ray contexto»?

Estos errores se producen porque el agente está intentando instrumentar solicitudes posteriores, como AWS SDK solicitudes o SQL consultas, 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 su caso de uso y, en su SDK lugar, tal vez desee considerar la instrumentación manual con el X-Ray. Como alternativa, puede habilitar los registros de SDK depuración de X-Ray para ver el seguimiento de la pila de dónde se producen las excepciones que faltan en el 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 son de tipo «activar y olvidar», como realizar una llamada puntual a una función de Lambda con AWS SDK la función Lambda o sondear HTTP algún punto final periódicamente, esto puede confundir al agente mientras propaga el contexto entre los subprocesos. Para comprobar que este es tu problema, activa los registros de SDK depuración de X-Ray y comprueba si hay mensajes como: No se emite el segmento denominado < NAME >, ya que origina los subsegmentos en curso. 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.