Configuración de X-Ray SDK para Java

X-Ray SDK para Java incluye una clase denominada AWSXRay que proporciona la grabadora global. Esto es un TracingHandler que puede utilizar para instrumentar su código. Puede configurar la grabadora global para personalizar la AWSXRayServletFilter que crea segmentos para las HTTP llamadas entrantes.

Complementos del servicio

Utilice plugins para registrar información sobre el servicio que aloja la aplicación.

Para utilizar un complemento, llame a withPlugin en su AWSXRayRecorderBuilder.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

SDKTambién utiliza la configuración del complemento para configurar el campo en el segmento. origin Esto indica el tipo de AWS recurso que ejecuta la aplicación. Cuando utilizas varios complementos, SDK utiliza el siguiente orden de resolución para determinar el origen: ElasticBeanstalk > EKS > ECS >EC2.

Reglas de muestreo

SDKUtiliza las reglas de muestreo que se definen en la consola de X-Ray para determinar qué solicitudes se van a registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. Cree reglas adicionales en la consola de X-Ray para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.

SDKAplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, solo SDK se aplica la primera regla.

También puede configurarlas SDK para que carguen las reglas de muestreo desde un JSON documento. SDKPueden usar las reglas locales como respaldo en los casos en que el muestreo de rayos X no esté disponible, o usar las reglas locales exclusivamente.

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.

La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.

Activado AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.

Para proporcionar reglas de copia de seguridad en Spring, configure la grabadora global con una CentralizedSamplingStrategy en una clase de configuración:

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
  builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

Para Tomcat, añada un agente de escucha que amplíe ServletContextListener y registre el agente de escucha en el descriptor de la implementación.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Startup.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}

...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

Para utilizar reglas locales solo, reemplace la CentralizedSamplingStrategy por LocalizedSamplingStrategy.

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

Registro

De forma predeterminada, SDK envía mensajes ERROR de nivel A a los registros de la aplicación. Puede habilitar el registro a nivel de depuración SDK para generar registros más detallados en el archivo de registro de la aplicación. Los niveles de registro válidos son DEBUGINFO, WARNERROR, y. FATAL FATALel nivel de registro silencia todos los mensajes de registro porque SDK no se registra a un nivel fatal.

logging.level.com.amazonaws.xray = DEBUG

Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar al generar subsegmentos de forma manual.

Inyección de ID de registro de seguimiento en los registros

Para mostrar el identificador de rastreo completo actual en sus declaraciones de registro, puede introducir el identificador en el contexto de diagnóstico mapeado (). MDC Mediante la interfaz SegmentListener, se llama a los métodos desde la grabadora de X-Ray durante los eventos del ciclo de vida del segmento. Cuando comienza un segmento o subsegmento, el identificador de rastreo cualificado se inserta junto MDC con la clave. AWS-XRAY-TRACE-ID Cuando ese segmento termina, la clave se elimina delMDC. Esto expone el ID de registro de seguimiento a la biblioteca de registro en uso. Cuando un subsegmento termina, su ID principal se inyecta en elMDC.

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Esta función funciona con aplicaciones Java equipadas con AWS X-Ray SDK for Java y admite las siguientes configuraciones de registro:

Consulte las siguientes pestañas para conocer las necesidades de cada front end y backend.

Ejemplo de inyección de ID de registro de seguimiento

A continuación se muestra una cadena de PatternLayout modificada para incluir el ID de registro de seguimiento. El ID de registro de seguimiento se imprime después del nombre del subproceso (%t) y antes del nivel de registro (%-5p).

%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray imprime automáticamente la clave y el ID de rastreo en la declaración de registro para facilitar el análisis. A continuación se muestra una instrucción de registro que utiliza el PatternLayout modificado.

2019-09-10 18:58:30.844 [nio-5000-exec-4]  AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

El mensaje de registro en sí está alojado en el patrón %m y se establece al llamar al registrador.

Agentes de escucha de segmento

Los detectores de segmentos son una interfaz para interceptar eventos del ciclo de vida, como el principio y el final de los segmentos producidos por el. AWSXRayRecorder La implementación de una función de escucha de segmentos puede consistir en añadir la misma anotación a todos los subsegmentos cuando se crean con ellos onBeginSubsegment, registrar un mensaje después de enviar cada segmento al daemon o registrar las consultas enviadas por los SQL interceptores beforeEndSubsegmentpara comprobar si el subsegmento representa una SQL consulta afterEndSegment, añadiendo metadatos adicionales en caso afirmativo.

Para ver la lista completa de SegmentListener funciones, consulte la documentación de la grabadora para Java.AWS X-Ray SDK API

En el ejemplo siguiente se muestra cómo agregar una anotación coherente a todos los subsegmentos al crear con onBeginSubsegment e imprimir un mensaje de registro al final de cada segmento con afterEndSegment.

import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;

public class MySegmentListener implements SegmentListener {
    .....
    
    @Override
    public void onBeginSubsegment(Subsegment subsegment) {
        subsegment.putAnnotation("annotationKey", "annotationValue");
    }
    
    @Override
    public void afterEndSegment(Segment segment) {
        // Be mindful not to mutate the segment
        logger.info("Segment with ID " + segment.getId());
    }
}

A continuación, se hace referencia a este agente de escucha de segmento personalizado cuando se crea AWSXRayRecorder.

AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

Variables de entorno

Puede usar variables de entorno para configurar el X-Ray SDK para Java. SDKAdmite las siguientes variables.

Las variables de entorno anulan las propiedades de sistema equivalentes y los valores establecidos en el código.

Propiedades del sistema

Puede utilizar las propiedades del sistema como una alternativa JVM específica a las variables de entorno. SDKSoporta las siguientes propiedades:

Si se ha establecido tanto una propiedad del sistema y como su variable de entorno equivalente, se utiliza el valor de la variable de entorno. En cualquier caso, esos valores anulan los valores establecidos en el código.