Commencer à utiliser l'exemple d'application Scorekeep

Ce didacticiel utilise la xray-gettingstarted branche de l'exemple d'application Scorekeep, qui permet de AWS CloudFormation créer et de configurer les ressources qui exécutent l'exemple d'application et le daemon X-Ray sur Amazon ECS. L'application utilise le framework Spring pour implémenter une API Web JSON et AWS SDK for Java pour conserver les données dans Amazon DynamoDB. Un filtre de servlet intégré à l'application gère toutes les demandes entrantes traitées par l'application, et un gestionnaire de demandes sur le client du AWS SDK gère les appels en aval à DynamoDB.

Vous pouvez suivre ce didacticiel en utilisant le AWS Management Console ou le AWS CLI.

Prérequis

Ce didacticiel permet AWS CloudFormation de créer et de configurer les ressources qui exécutent l'exemple d'application et le daemon X-Ray. Les prérequis suivants sont requis pour installer et exécuter le didacticiel :

Installez l'application Scorekeep à l'aide de CloudFormation

Génération de données de suivi

L'exemple d'application inclut une application web frontale. Utilisez l'application Web pour générer du trafic vers l'API et envoyer des données de suivi à X-Ray. Tout d'abord, récupérez l'URL de l'application Web à l'aide du AWS Management Console ou du AWS CLI :

Chacune de ces étapes génère des requêtes HTTP adressées à l'API et des appels en aval à DynamoDB pour lire et écrire les données relatives à l'utilisateur, à la session, au jeu, au déplacement et à l'état.

Consultez la carte de suivi dans AWS Management Console

Vous pouvez consulter la carte de suivi et les traces générées par l'exemple d'application dans X-Ray et CloudWatch les consoles.

La cause indique que l'adresse e-mail fournie dans un appel vers createSubscription effectué dans la classe WebConfig n'était pas valide. Dans la section suivante, nous allons résoudre ce problème.

Configuration des notifications Amazon SNS

Scorekeep utilise Amazon SNS pour envoyer des notifications lorsque les utilisateurs terminent un jeu. Lorsque l'application démarre, elle essaie de créer un abonnement pour une adresse e-mail définie dans un paramètre de CloudFormation pile. Cet appel échoue actuellement. Configurez un e-mail de notification pour activer les notifications et résoudre les défaillances mises en évidence sur la carte de suivi.

Lorsque la mise à jour est terminée, Scorekeep redémarre et crée un abonnement à la rubrique SNS. Vérifiez votre adresse e-mail et confirmez l'abonnement pour voir les mises à jour lorsque vous terminez un jeu. Ouvrez la carte de suivi pour vérifier que les appels à SNS n'échouent plus.

Exploration de l'exemple d'application

L'exemple d'application est une API Web HTTP en Java configurée pour utiliser le SDK X-Ray pour Java. Lorsque vous déployez l'application avec le CloudFormation modèle, elle crée les tables DynamoDB, le cluster Amazon ECS et les autres services nécessaires pour exécuter Scorekeep sur ECS. Un fichier de définition de tâche pour ECS est créé via CloudFormation. Ce fichier définit les images de conteneur utilisées par tâche dans un cluster ECS. Ces images sont obtenues auprès de l'ECR public officiel de X-Ray. L'image du conteneur de l'API scorekeep contient l'API compilée avec Gradle. L'image de conteneur du conteneur frontal Scorekeep sert le frontend à l'aide du serveur proxy nginx. Ce serveur achemine les demandes vers des chemins commençant par /api vers l'API.

Pour instrumenter les demandes HTTP, l'application ajoute le TracingFilter fourni par le kit de développement logiciel.

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

@Configuration
public class WebConfig {

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

Ce filtre envoie des données de suivi sur toutes les demandes entrantes servies par l'application, y compris l'URL de demande, la méthode, le statut de réponse, l'heure de début et de fin.

L'application effectue également des appels en aval à DynamoDB à l'aide du. AWS SDK for Java Pour instrumenter ces appels, l'application utilise simplement les sous-modules AWS liés au SDK comme dépendances, et le SDK X-Ray pour Java instrumente automatiquement tous les clients du SDK. AWS

L'application utilise Docker pour créer le code source sur instance avec le fichier Gradle Docker Image et le Scorekeep API Dockerfile fichier pour exécuter le fichier JAR exécutable généré par Gradle. 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" ]

Le fichier build.gradle télécharge les sous-modules du kit de développement logiciel à partir de Maven pendant la compilation en les déclarant comme des dépendances.

...
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")
    }
}

Les sous-modules principaux, AWS SDK et AWS SDK Instrumentor sont tout ce qui est nécessaire pour instrumenter automatiquement tous les appels en aval effectués avec le SDK. AWS

Pour relayer les données de segment brutes vers l'API X-Ray, le daemon X-Ray doit écouter le trafic sur le port UDP 2000. Pour ce faire, l'application fait exécuter le daemon X-Ray dans un conteneur qui est déployé parallèlement à l'application Scorekeep sur ECS en tant que conteneur annexe. Consultez la rubrique consacrée au daemon X-Ray pour plus d'informations.

...
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
      ...

Le SDK X-Ray pour Java fournit une classe AWSXRay nommée qui fournit l'enregistreur global, TracingHandler que vous pouvez utiliser pour instrumenter votre code. Vous pouvez configurer l'enregistreur mondial pour personnaliser le AWSXRayServletFilter qui crée des segments pour les appels HTTP entrants. L'exemple inclut un bloc statique dans la classe WebConfig qui configure l'enregistreur mondial avec des plug-ins et des règles d'échantillonnage.

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());
    ...
    
  }
}

Cet exemple utilise le générateur pour charger des règles d'échantillonnage à partir d'un fichier nommé sampling-rules.json. Les règles d'échantillonnage déterminent le taux auquel le kit SDK enregistre des segments pour les demandes 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
  }
}

Le fichier de règles d'échantillonnage définit quatre règles personnalisées et une règle par défaut. Pour chaque demande entrante, le kit SDK évalue les règles personnalisées dans l'ordre dans lequel elles sont définies. Le kit de développement logiciel (SDK) applique la première règle qui correspond à la méthode, au chemin et au nom de service de la demande. Pour Scorekeep, la première règle intercepte toutes les demandes POST (appels de création de ressource) en appliquant un objectif fixé à une demande par seconde et un taux de 1,0 ou 100 % des demandes une fois l'objectif fixé atteint.

Les trois autres règles personnalisées appliquent un taux de 5 %, sans aucun objectif fixé concernant les lectures de session, de jeu et d'état (demandes GET). Il s'ensuit une réduction du nombre de suivis pour les appels périodiques émis automatiquement par le service frontal à quelques secondes d'intervalle pour vérifier que le contenu est à jour. Pour toutes les autres demandes, le fichier définit un taux par défaut d'une demande par seconde et un taux de 10 %.

L'exemple d'application indique également comment utiliser des fonctionnalités avancées, telles que l'instrumentation manuelle d'un client de kit de développement logiciel, la création de sous-segments supplémentaires et des appels HTTP sortants. Pour de plus amples informations, veuillez consulter AWS X-Ray exemple d'application.

Facultatif : stratégie de moindre privilège

Les conteneurs Scorekeep ECS accèdent aux ressources en utilisant des politiques d'accès complet, telles que AmazonSNSFullAccess et. AmazonDynamoDBFullAccess L'utilisation de politiques d'accès complet n'est pas la meilleure pratique pour les applications de production. L'exemple suivant met à jour la politique DynamoDB IAM afin d'améliorer la sécurité de l'application. Pour en savoir plus sur les meilleures pratiques de sécurité dans les politiques IAM, consultez la section Gestion des identités et des accès pour 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"

Pour mettre à jour votre politique, vous devez d'abord identifier l'ARN de vos ressources DynamoDB. Vous utilisez ensuite l'ARN dans une politique IAM personnalisée. Enfin, vous devez appliquer cette politique à votre profil d'instance.

Si vous avez attaché la nouvelle politique au scorekeepRole rôle, vous devez la détacher avant de supprimer la CloudFormation pile, car cette politique attachée empêchera la suppression de la pile. La politique peut être automatiquement détachée en la supprimant.

Nettoyage

Pour supprimer les ressources de l'application Scorekeep, procédez comme suit :

Étapes suivantes

Apprenez-en plus sur X-Ray dans le chapitre suivant,AWS X-Ray concepts.

Pour instrumenter votre propre application, apprenez-en plus sur le SDK X-Ray pour Java ou sur l'un des autres SDK X-Ray :

Pour exécuter le daemon X-Ray en local ou en mode actif AWS, consultezAWS X-Ray daemon.

Pour contribuer à l'exemple d'application sur GitHub, voir eb-java-scorekeep.