Erste Schritte mit der Scorekeep-Beispielanwendung

In diesem Tutorial wird der xray-gettingstarted Zweig der Scorekeep-Beispielanwendung verwendet, mit dem die Ressourcen erstellt und konfiguriert werden, CloudFormation auf denen die Beispielanwendung und der X-Ray Daemon auf Amazon ECS ausgeführt werden. Die Anwendung verwendet das Spring-Framework, um eine JSON-Web-API zu implementieren und Daten in Amazon AWS SDK für Java DynamoDB zu speichern. Ein Servlet-Filter in der Anwendung instrumentiert alle eingehenden Anfragen, die von der Anwendung bedient werden, und ein Request-Handler auf dem AWS SDK-Client steuert Downstream-Aufrufe an DynamoDB.

Sie können diesem Tutorial folgen, indem Sie entweder den oder den AWS-Managementkonsole verwenden. AWS CLI

Voraussetzungen

In diesem Tutorial werden CloudFormation die Ressourcen erstellt und konfiguriert, auf denen die Beispielanwendung und der X-Ray Daemon ausgeführt werden. Für die Installation und Ausführung des Tutorials sind die folgenden Voraussetzungen erforderlich:

Installieren Sie die Scorekeep-Anwendung mit CloudFormation

Generieren von Ablaufverfolgungsdaten

Die Beispielanwendung enthält eine Front-End-Webanwendung. Verwenden Sie die Webanwendung, um Datenverkehr an die API zu generieren und Ablaufverfolgungsdaten an X-Ray zu senden. Rufen Sie zunächst die Web-App-URL mit dem AWS-Managementkonsole oder dem ab AWS CLI:

Jeder dieser Schritte generiert HTTP-Anfragen an die API und Downstream-Aufrufe an DynamoDB, um Benutzer-, Sitzungs-, Spiel-, Zug- und Statusdaten zu lesen und zu schreiben.

Sehen Sie sich die Trace-Map in der AWS-Managementkonsole

Sie können die von der Beispielanwendung generierte Trace-Map und die von der Beispielanwendung generierten Spuren in den CloudWatch Konsolen X-Ray und sehen.

Die Ursache gibt an, dass die E-Mail-Adresse, die in einem Aufruf von createSubscription in der Klasse WebConfig angegeben wurde, ungültig ist. Im nächsten Abschnitt werden wir das beheben.

Konfigurieren von Amazon-SNS-Benachrichtigungen

Scorekeep verwendet Amazon SNS, um Benachrichtigungen zu senden, wenn Benutzer ein Spiel beenden. Wenn die Anwendung gestartet wird, versucht sie, ein Abonnement für eine E-Mail-Adresse zu erstellen, die in einem CloudFormation Stack-Parameter definiert ist. Dieser Anruf schlägt derzeit fehl. Konfigurieren Sie eine Benachrichtigungs-E-Mail, um Benachrichtigungen zu aktivieren und die in der Trace-Map hervorgehobenen Fehler zu beheben.

Wenn die Aktualisierung abgeschlossen ist, startet Scorekeep neu und erstellt ein Abonnement für das SNS-Thema. Überprüfen Sie Ihre E-Mail-Adresse und bestätigen Sie das Abonnement, um Aktualisierungen anzuzeigen, wenn Sie ein Spiel abgeschlossen haben. Öffnen Sie die Trace-Map, um sicherzustellen, dass die Aufrufe an SNS nicht mehr fehlschlagen.

Erkunden der Beispielanwendung

Die Beispielanwendung ist eine HTTP-Web-API in Java, die für die Verwendung des X-Ray SDK für Java konfiguriert ist. Wenn Sie die Anwendung mit der CloudFormation Vorlage bereitstellen, erstellt sie die DynamoDB-Tabellen, Amazon ECS-Cluster und andere Dienste, die für die Ausführung von Scorekeep auf ECS erforderlich sind. Eine Aufgabendefinitionsdatei für ECS wird mit erstellt. CloudFormation Diese Datei definiert die Container-Images, die pro Aufgabe in einem ECS-Cluster verwendet werden. Diese Bilder stammen aus der offiziellen X-Ray öffentlichen ECR. Für das Scorekeep-API-Container-Image wurde die API mit Gradle kompiliert. Das Container-Image des Scorekeep-Frontend-Containers dient dem Frontend mithilfe des Nginx-Proxyservers. Dieser Server leitet Anfragen über Pfade, die mit /api beginnen, an die API weiter.

Zum Instrumentieren eingehender HTTP-Anforderungen fügt die Anwendung den vom SDK bereitgestellten TracingFilter hinzu.

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

@Configuration
public class WebConfig {

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

Dieser Filter sendet Ablaufverfolgungsdaten über alle eingehenden Anforderungen, die die Anwendung verarbeitet, einschließlich Anforderungs-URL, Methode, Antwortstatus sowie Start- und Endzeit.

Die Anwendung führt auch Downstream-Aufrufe an DynamoDB durch. AWS SDK für Java Um diese Aufrufe zu instrumentieren, verwendet die Anwendung einfach die AWS SDK-related Submodule als Abhängigkeiten, und das X-Ray SDK für Java instrumentiert automatisch alle AWS SDK-Clients.

Die Anwendung verwendetDocker, um den Quellcode auf der Instanz mit der Gradle Docker Image und der Scorekeep API Dockerfile Datei zu erstellen, um die ausführbare JAR auszuführen, die Gradle auf ihrer Seite generiert. 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" ]

Die build.gradle-Datei lädt die SDK-Untermodule von Maven während der Kompilierung herunter, indem sie zu Abhängigkeiten erklärt werden.

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

Die Submodule Core, AWS SDK und AWS SDK Instrumentor sind alles, was benötigt wird, um alle Downstream-Aufrufe, die mit dem SDK getätigt werden, automatisch zu instrumentieren. AWS

Um die Rohsegmentdaten an die X-Ray API weiterzuleiten, muss der X-Ray Daemon den Datenverkehr auf dem UDP-Port 2000 abhören. Dazu wird der X-Ray Daemon in der Anwendung in einem Container ausgeführt, der zusammen mit der Scorekeep-Anwendung auf ECS als Sidecar-Container bereitgestellt wird. Weitere Informationen finden Sie im X-Ray Daemon-Thema.

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

Das X-Ray SDK für Java stellt eine Klasse mit dem Namen bereitAWSXRay, die den globalen Recorder bereitstellt, mit dem Sie Ihren Code instrumentieren können. TracingHandler Sie können die globale Aufzeichnung so konfigurieren, dass der AWSXRayServletFilter, der Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird. Das Beispiel enthält einen statischen Block in der WebConfig-Klasse, der die globale Aufzeichnung mit Plugins und Samplingregeln konfiguriert.

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

In diesem Beispiel wird der Builder zum Laden von Samplingregeln aus einer Datei namens sampling-rules.json verwendet. Samplingregeln bestimmen die Rate, mit der das SDK Segmente für eingehende Anforderungen aufzeichnet.

{
  "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
  }
}

Die Samplingregeldatei definiert vier benutzerdefinierte Samplingregeln und die Standardregel. Für jede eingehende Anforderung wertet das SDK die benutzerdefinierten Regeln in der Reihenfolge aus, in der sie definiert sind. Das SDK wendet die erste Regel an, die der Methode, dem Pfad und dem Service-Namen der Anforderung entspricht. Bei Scorekeep fängt die erste Regel alle POST-Anforderungen (Aufrufe zum Erstellen von Ressourcen) ab, indem pro Sekunde ein festes Ziel einer einzelnen Anfrage und eine Rate von 1.0 angewendet wird bzw. 100 % der Anforderungen nach dem festen Ziel erfüllt sind.

Die übrigen drei benutzerdefinierte Regeln wenden eine Rate von fünf Prozent ohne festes Ziel auf Sitzungs-, Spiel- und Statuslesevorgänge (GET-Anfragen) an. Dies minimiert die Anzahl der Ablaufverfolgungen für regelmäßige Aufrufe, die das Front-End automatisch alle paar Sekunden ausführt, um sicherzustellen, dass die Inhalte auf dem neuesten Stand sind. Für alle übrigen Anforderungen definiert die Datei eine Standardrate von einer einzelnen Anfrage pro Sekunde und einer Rate von 10 Prozent.

Die Beispielanwendung zeigt auch, wie Sie erweiterte Funktionen wie die manuelle SDK-Client-Instrumentierung verwenden sowie zusätzliche Untersegmente und ausgehende HTTP-Aufrufe erstellen. Weitere Informationen finden Sie unter AWS X-Ray Beispielapplikation.

Optional: Richtlinie für geringste Rechte

Die Scorekeep-ECS-Container greifen mithilfe von Vollzugriffsrichtlinien wie und auf Ressourcen zu. AmazonSNSFullAccess AmazonDynamoDBFullAccess Die Verwendung von Vollzugriffsrichtlinien ist nicht die beste Methode für Produktionsanwendungen. Im folgenden Beispiel wird die DynamoDB-IAM-Richtlinie aktualisiert, um die Sicherheit der Anwendung zu verbessern. Weitere Informationen zu den bewährten Sicherheitsmethoden in IAM-Richtlinien finden Sie unter Identitäts- und Zugriffsmanagement für. 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"

Um Ihre Richtlinie zu aktualisieren, identifizieren Sie zunächst den ARN Ihrer DynamoDB-Ressourcen. Anschließend verwenden Sie den ARN in einer benutzerdefinierten IAM-Richtlinie. Schließlich wenden Sie diese Richtlinie auf Ihr Instanzprofil an.

Wenn Sie die neue Richtlinie an die scorekeepRole Rolle angehängt haben, müssen Sie sie trennen, bevor Sie den CloudFormation Stapel löschen, da diese angefügte Richtlinie das Löschen des Stacks verhindert. Die Richtlinie kann automatisch getrennt werden, indem Sie die Richtlinie löschen.

Bereinigen

Gehen Sie wie folgt vor, um die Ressourcen der Scorekeep-Anwendung zu löschen:

Nächste Schritte

Erfahren Sie mehr darüber X-Ray im nächsten Kapitel,AWS X-Ray Konzepte.

Um Ihre eigene App zu instrumentieren, erfahren Sie mehr über das X-Ray SDK für Java oder eines der anderen X-Ray SDKs:

Informationen zum lokalen oder lokalen Ausführen des X-Ray Daemons finden Sie AWS unterAWS X-Ray Dämon.

Um zur Beispielanwendung beizutragen, siehe GitHub https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted eb-java-scorekeep.