Introducción a la aplicación de ejemplo Scorekeep

Este tutorial utiliza la xray-gettingstarted rama de la aplicación de ejemplo Scorekeep, que se utiliza CloudFormation para crear y configurar los recursos que ejecutan la aplicación y el daemon de muestra en Amazon ECS. X-Ray La aplicación utiliza el marco Spring para implementar una API web JSON y conservar los datos en AWS SDK para Java Amazon DynamoDB. Un filtro de servlets en la aplicación sirve de instrumento para todas las solicitudes entrantes que atiende la aplicación, y un controlador de solicitudes en el cliente del AWS SDK gestiona las llamadas posteriores a DynamoDB.

Puede seguir este tutorial utilizando el o el. Consola de administración de AWS AWS CLI

Requisitos previos

Este tutorial se utiliza CloudFormation para crear y configurar los recursos que ejecutan la aplicación y el X-Ray daemon de ejemplo. Se tienen que cumplir los siguientes requisitos previos para instalar y ejecutar el tutorial:

Instale la aplicación Scorekeep usando CloudFormation

Generación de datos de rastreo

La aplicación de ejemplo incluye una aplicación web front-end. Utilice la aplicación web para generar tráfico a la API y enviar los datos de rastreo a X-Ray. En primer lugar, recupere la URL de la aplicación web mediante la Consola de administración de AWS o la AWS CLI:

Cada uno de estos pasos genera solicitudes HTTP a la API y llamadas posteriores a DynamoDB para leer y escribir el usuario, la sesión, el juego, la movida y los datos de estado.

Vea el mapa de rastreo en Consola de administración de AWS

Puede ver el mapa de rastreo y los rastros generados por la aplicación de ejemplo en las CloudWatch consolas X-Ray y.

La causa indica que la dirección de correo electrónico proporcionada en una llamada a createSubscription realizada en la clase WebConfig no era válida. Lo arreglaremos en la siguiente sección.

Configuración de notificaciones de Amazon SNS

Scorekeep utiliza Amazon SNS para enviar notificaciones cuando los usuarios completan un juego. Cuando la aplicación se inicia, intenta crear una suscripción para una dirección de correo electrónico definida en un parámetro de CloudFormation pila. Esa llamada está fallando actualmente. Configure un correo electrónico de notificación para habilitar las notificaciones y resolver los errores destacados en el mapa de rastros.

Cuando se completa la actualización, Scorekeep se reinicia y crea una suscripción al tema de SNS. Compruebe su correo electrónico y confirme la suscripción para ver las actualizaciones cuando complete un juego. Abra el mapa de rastros para comprobar que las llamadas a SNS ya no están fallando.

Explorar la aplicación de ejemplo

La aplicación de ejemplo es una API web HTTP en Java que está configurada para usar el X-Ray SDK para Java. Al implementar la aplicación con la CloudFormation plantilla, crea las tablas de DynamoDB, el clúster de Amazon ECS y otros servicios necesarios para ejecutar Scorekeep en ECS. Se crea un archivo de definición de tareas para ECS mediante. CloudFormation Este archivo define las imágenes del contenedor utilizadas por tarea en un clúster de ECS. Estas imágenes se obtienen del ECR X-Ray público oficial. La imagen del contenedor de la API de Scorekeep tiene la API compilada con Gradle. La imagen de contenedor del contenedor frontend de Scorekeep atiende al frontend mediante el servidor proxy nginx. Este servidor dirige las solicitudes a las rutas que empiezan por /api a la API.

Para instrumentar las solicitudes de HTTP entrantes, la aplicación añade el TracingFilter que proporciona el SDK.

import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
...

@Configuration
public class WebConfig {

  @Bean
  public Filter TracingFilter() {
    return new AWSXRayServletFilter("Scorekeep");
  }
...

Este filtro envía datos de rastreo sobre todas las solicitudes entrantes que la aplicación atiende, incluidos el URL, el método, el estado de la respuesta, la hora de inicio y la hora de finalización de la solicitud.

La aplicación también realiza llamadas posteriores a DynamoDB mediante el AWS SDK para Java. Para instrumentar estas llamadas, la aplicación simplemente toma los AWS SDK-related submódulos como dependencias y el SDK para Java instrumenta automáticamente a todos los clientes del X-Ray SDK. AWS

La aplicación utiliza Docker para compilar el código de fuente de la instancia con Gradle Docker Image y el archivo Scorekeep API Dockerfile para ejecutar el archivo ejecutable JAR que Gradle genera en su ENTRYPOINT.

docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build

ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]

El archivo build.gradle descarga todos los submódulos del SDK de Maven durante la compilación declarándolos como dependencias.

...
dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    testCompile('org.springframework.boot:spring-boot-starter-test')
    compile('com.amazonaws:aws-java-sdk-dynamodb')
    compile("com.amazonaws:aws-xray-recorder-sdk-core")
    compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk")
    compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor")
    ...
}
dependencyManagement {
    imports {
        mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67")
        mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0")
    }
}

Los submódulos core, AWS SDK y AWS SDK Instrumentor son todo lo que se necesita para instrumentar automáticamente cualquier llamada posterior que se realice con el SDK. AWS

Para transmitir los datos de los segmentos sin procesar a la X-Ray API, es necesario que el X-Ray daemon escuche el tráfico en el puerto UDP 2000. Para ello, la aplicación hace que el X-Ray demonio se ejecute en un contenedor que se implementa junto con la aplicación Scorekeep en ECS como contenedor secundario. Consulta el tema sobre los X-Ray demonios para obtener más información.

...
Resources:
  ScorekeepTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties: 
      ContainerDefinitions: 
      ...
      
      - Cpu: '256'
        Essential: true
        Image: amazon/aws-xray-daemon
        MemoryReservation: '128'
        Name: xray-daemon
        PortMappings: 
          - ContainerPort: '2000'
            HostPort: '2000'
            Protocol: udp
      ...

El X-Ray SDK para Java proporciona una clase denominada AWSXRay que proporciona la grabadora global, TracingHandler que puede utilizar para instrumentar el código. Puede configurar la grabadora global para que personalice el AWSXRayServletFilter que crea los segmentos para las llamadas HTTP entrantes. La muestra incluye un bloque estático en la clase WebConfig que configura la grabadora global con complementos y reglas de muestreo.

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

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

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

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

En este ejemplo se utiliza el compilador para cargar las reglas de muestreo desde un archivo denominado sampling-rules.json. Las reglas de muestreo determinan la velocidad a la que el SDK registra los segmentos de las solicitudes entrantes.

{
  "version": 1,
  "rules": [
    {
      "description": "Resource creation.",
      "service_name": "*",
      "http_method": "POST",
      "url_path": "/api/*",
      "fixed_target": 1,
      "rate": 1.0
    },
    {
      "description": "Session polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/session/*",
      "fixed_target": 0,
      "rate": 0.05
    },
    {
      "description": "Game polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/game/*/*",
      "fixed_target": 0,
      "rate": 0.05
    },
    {
      "description": "State polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/state/*/*/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

El archivo de reglas de muestreo define cuatro reglas de muestreo personalizadas y la regla predeterminada. Para cada solicitud de entrada, el SDK evalúa las reglas personalizadas en el orden en que están definidas. El SDK aplica la primera regla que coincide con el método, la ruta y el nombre de servicio de la solicitud. Para Scorekeep, la primera regla captura todas las solicitudes POST (llamadas de creación de recursos) aplicando un objetivo fijo de una solicitud por segundo y una tasa del 1,0, es decir, el 100 % de las solicitudes después de cumplir el objetivo fijo.

Las otras tres reglas personalizadas aplican una tasa del 5 % sin objetivo fijo a las lecturas de sesiones, juegos y estado (solicitudes GET). De este modo se reduce al mínimo el número de rastros de las llamadas periódicas que el front-end realiza automáticamente cada pocos segundos para asegurarse de que el contenido está actualizado. Para el resto de solicitudes, el archivo define una velocidad predeterminada de una solicitud por segundo y una tasa del 10 %.

La aplicación de ejemplo también muestra cómo usar funciones avanzadas, como la instrumentación manual de clientes SDK, la creación de subsegmentos adicionales y llamadas HTTP salientes. Para obtener más información, consulte AWS X-Ray aplicación de muestra.

Opcional: política de privilegios mínimos

Los contenedores ECS de Scorekeep acceden a los recursos mediante políticas de acceso total, como AmazonSNSFullAccess y AmazonDynamoDBFullAccess. El uso de políticas de acceso total no es la mejor práctica para las aplicaciones de producción. En el siguiente ejemplo se actualiza la política de IAM de DynamoDB para mejorar la seguridad de la aplicación. Para obtener más información sobre las prácticas recomendadas de seguridad en las políticas de IAM, consulte Administración de identidades y accesos para. AWS X-Ray

ECSTaskRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement: 
          - 
            Effect: "Allow"
            Principal: 
              Service: 
                - "ecs-tasks.amazonaws.com"
            Action: 
              - "sts:AssumeRole"
      ManagedPolicyArns:
        - "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"
        - "arn:aws:iam::aws:policy/AmazonSNSFullAccess"
        - "arn:aws:iam::aws:policy/AWSXrayFullAccess"
      RoleName: "scorekeepRole"

Para actualizar las políticas, primero identifique los ARN de sus recursos de DynamoDB. A continuación, utilice los ARN en una política de IAM personalizada. Por último, aplique esa política al perfil de instancia.

Si ha adjuntado la nueva política al scorekeepRole rol, debe desconectarla antes de eliminar la CloudFormation pila, ya que esta política adjunta impedirá que se elimine la pila. La política se puede separar automáticamente eliminándola.

Limpieza

Siga estos pasos para eliminar los recursos de la aplicación Scorekeep:

Siguientes pasos

Obtenga más información X-Ray en el siguiente capítulo,AWS X-Ray conceptos.

Para crear tu propia aplicación, obtén más información sobre el X-Ray SDK para Java o uno de los otros X-Ray SDK:

Para ejecutar el X-Ray daemon localmente o de forma local AWS, consulte. AWS X-Ray demonio

Para contribuir a la aplicación de ejemplo GitHub, consulte https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted eb-java-scorekeep.