Démarrez avec l'exemple d'application Scorekeep

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

Vous pouvez suivre ce didacticiel à l'aide du Console de gestion AWS ou du AWS CLI.

Conditions préalables

Ce didacticiel permet CloudFormation de créer et de configurer les ressources qui exécutent l'exemple d'application et le X-Ray démon. 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 Console de gestion AWS ou des éléments AWS CLI suivants :

Chacune de ces étapes génère des requêtes HTTP à l'API et des appels en aval à DynamoDB pour lire et écrire des données sur les utilisateurs, les sessions, les jeux, les déplacements et les états.

Consultez la carte des traces dans Console de gestion AWS

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

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 une partie. 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 dans 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 au 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 X-Ray SDK pour Java. Lorsque vous déployez l'application avec le CloudFormation modèle, elle crée les tables DynamoDB, Amazon ECS Cluster et les autres services nécessaires à l'exécution de Scorekeep sur ECS. Un fichier de définition de tâches 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 proviennent de l'ECR X-Ray public officiel. L'image du conteneur de l'API scorekeep contient l'API compilée avec Gradle. L'image du conteneur frontal Scorekeep dessert le frontend à l'aide du serveur proxy Nginx. Ce serveur achemine les requêtes 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 vers DynamoDB à l'aide du. AWS SDK pour Java Pour instrumenter ces appels, l'application prend simplement les AWS SDK-related sous-modules comme dépendances, et le X-Ray SDK pour Java instrumente automatiquement tous les clients du AWS SDK.

L'application utilise Docker pour créer le code source sur instance avec le fichier Gradle Docker Image et pour exécuter le Scorekeep API Dockerfile fichier JAR exécutable que Gradle génère sur son. 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 core, 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' X-Ray API, le X-Ray démon doit écouter le trafic sur le port UDP 2000. Pour ce faire, l'application fait exécuter le X-Ray démon dans un conteneur qui est déployé en même temps que l'application Scorekeep sur ECS en tant que conteneur sidecar. Consultez la rubrique sur les X-Ray démons 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 X-Ray SDK pour Java fournit une classe nommée AWSXRay 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 plus d’informations, consultez 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 AmazonSNSFullAccess que 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 IAM de DynamoDB afin d'améliorer la sécurité de l'application. Pour en savoir plus sur les meilleures pratiques de sécurité en matière de 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 appliquez cette politique à votre profil d'instance.

Si vous avez associé la nouvelle politique au scorekeepRole rôle, vous devez la détacher avant de supprimer la CloudFormation pile, car cette stratégie associée bloquera 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 X-Ray dans le chapitre suivant,AWS X-Ray concepts.

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

Pour exécuter le X-Ray démon localement ou sur AWS. AWS X-Ray daemon

Pour contribuer à l'exemple d'application sur GitHub, consultez https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted eb-java-scorekeep.