Guida introduttiva all'applicazione di esempio Scorekeep

Questo tutorial utilizza il xray-gettingstarted ramo dell'applicazione di esempio Scorekeep, che utilizza AWS CloudFormation per creare e configurare le risorse che eseguono l'applicazione di esempio e il demone X-Ray su Amazon ECS. L'applicazione utilizza il framework Spring per implementare un'API Web JSON e AWS SDK for Java per rendere persistenti i dati su Amazon DynamoDB. Un servlet filtra nell'applicazione per tutte le richieste in entrata servite dall'applicazione e un gestore di richieste sugli strumenti client AWS SDK per le chiamate downstream a DynamoDB.

Puoi seguire questo tutorial usando il o il. AWS Management Console AWS CLI

Prerequisiti

Questo tutorial serve AWS CloudFormation a creare e configurare le risorse che eseguono l'applicazione di esempio e il demone X-Ray. I seguenti prerequisiti sono necessari per l'installazione e l'esecuzione del tutorial:

Installa l'applicazione Scorekeep utilizzando CloudFormation

Generare i dati di tracciamento

L'applicazione di esempio include un app web di front-end. Utilizza l'app Web per generare traffico verso l'API e inviare dati di traccia a X-Ray. Innanzitutto, recupera l'URL dell'app Web utilizzando AWS Management Console o: AWS CLI

Ciascuno di questi passaggi genera richieste HTTP all'API e chiamate downstream a DynamoDB per leggere e scrivere dati relativi a utenti, sessioni, giochi, spostamenti e stati.

Visualizza la mappa di tracciamento nel AWS Management Console

È possibile visualizzare la mappa di traccia e le tracce generate dall'applicazione di esempio negli X-Ray e CloudWatch nelle console.

La causa indica che l'indirizzo e-mail fornito in una chiamata a createSubscription invocata nella classe WebConfig non è valido. Nella prossima sezione, lo risolveremo.

Configurazione delle notifiche Amazon SNS

Scorekeep utilizza Amazon SNS per inviare notifiche quando gli utenti completano una partita. All'avvio, l'applicazione tenta di creare un abbonamento per un indirizzo e-mail definito in un CloudFormation parametro stack. Al momento la chiamata non è riuscita. Configura un'e-mail di notifica per abilitare le notifiche e risolvere gli errori evidenziati nella mappa di traccia.

Quando l'aggiornamento viene completato, Scorekeep si riavvia e crea una sottoscrizione per l'argomento SNS. Controlla la tua e-mail e conferma che la sottoscrizione per visualizzare gli aggiornamenti al completamento di un gioco. Apri la mappa di tracciamento per verificare che le chiamate a SNS non abbiano più esito negativo.

Esplorare l'applicazione di esempio

L'applicazione di esempio è un'API Web HTTP in Java configurata per utilizzare X-Ray SDK for Java. Quando distribuisci l'applicazione con il CloudFormation modello, crea le tabelle DynamoDB, Amazon ECS Cluster e altri servizi necessari per eseguire Scorekeep su ECS. Un file di definizione delle attività per ECS viene creato tramite. CloudFormation Questo file definisce le immagini dei contenitori utilizzate per attività in un cluster ECS. Queste immagini sono ottenute dall'ECR pubblico ufficiale di X-Ray. L'immagine del contenitore dell'API scorekeep ha l'API compilata con Gradle. L'immagine del contenitore del frontend Scorekeep serve il frontend utilizzando il server proxy nginx. Questo server indirizza le richieste verso percorsi che iniziano con /api all'API.

Per analizzare le richieste HTTP in ingresso, l'applicazione aggiunge il TracingFilter fornito dall'SDK.

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

@Configuration
public class WebConfig {

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

Questo filtro invia i dati di tracciamento di tutte le richieste in entrata elaborate dall'applicazione, inclusi URL della richiesta, metodo, stato della risposta, ora di inizio e ora di fine.

L'applicazione effettua anche chiamate downstream a DynamoDB utilizzando. AWS SDK for Java Per strumentare queste chiamate, l'applicazione utilizza semplicemente i sottomoduli AWS relativi all'SDK come dipendenze e l'X-Ray SDK for Java monitora automaticamente tutti i client SDK. AWS

L'applicazione crea il codice sorgente su istanza con Gradle Docker Image e il file Docker per eseguire il Scorekeep API Dockerfile file JAR eseguibile che Gradle genera al suo interno. 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" ]

Il file build.gradle attiva lo scaricamento dei sottomoduli SDK da Maven durante la compilazione dichiarandoli come dipendenze.

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

I sottomoduli core, AWS SDK e AWS SDK Instrumentor sono tutto ciò che serve per strumentare automaticamente tutte le chiamate downstream effettuate con l'SDK. AWS

Per inoltrare i dati grezzi del segmento all'API X-Ray, è necessario il demone X-Ray per ascoltare il traffico sulla porta UDP 2000. A tal fine, l'applicazione fa funzionare il demone X-Ray in un contenitore distribuito insieme all'applicazione Scorekeep su ECS come contenitore secondario. Per ulteriori informazioni, consulta l'argomento relativo al demone X-Ray.

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

L'X-Ray SDK for Java fornisce una classe denominata AWSXRay che fornisce il registratore globale, TracingHandler che puoi usare per strumentare il tuo codice. Puoi configurare la registrazione globale per personalizzare il AWSXRayServletFilter che crea i segmenti relativi alle chiamate HTTP in entrata. L'esempio include un blocco statico nella classe WebConfig che permette di configurare la registrazione globale con i plug-in e le regole di campionamento.

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

Questo esempio usa il compilatore per caricare le regole di campionamento da un file denominato sampling-rules.json. Le regole di campionamento determinano la frequenza con cui l'SDK registra i segmenti relativi alle richieste in entrata.

{
  "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 regole di campionamento definiscono quattro regole di campionamento personalizzate e la regola di default. Per ogni richiesta in entrata, l'SDK valuta le regole nell'ordine in cui sono definite. L'SDK si applica la prima regola che corrisponde al metodo, al percorso e al nome del servizio della richiesta. Per Scorekeep, la prima regola cattura tutte le richieste POST (chiamate di creazione delle risorse) applicando un obiettivo fisso di una richiesta al secondo e una percentuale di 1,0, o il 100%, delle richieste dopo il raggiungimento dell'obiettivo fisso.

Le altre tre regole personalizzate applicano una percentuale del 5% delle chiamate, senza alcun obiettivo fisso per sessioni, giochi e letture dello stato (richieste GET). Questo riduce al minimo il numero di tracciamenti per le chiamate periodiche che il front-end invoca automaticamente ogni pochi secondi per garantire l'aggiornamento del contenuto. Per tutte le altre richieste, il file definisce un obiettivo di default di una richiesta al secondo e una percentuale del 10% delle chiamate successive.

L'applicazione di esempio mostra anche come utilizzare le funzionalità avanzate come l'analisi manuale del client SDK, la creazione di sottosegmenti aggiuntivi e le chiamate HTTP in uscita. Per ulteriori informazioni, consulta AWS X-Ray applicazione di esempio.

Opzionale: policy con privilegio minimo

I contenitori Scorekeep ECS accedono alle risorse utilizzando policy di accesso complete, come e. AmazonSNSFullAccess AmazonDynamoDBFullAccess L'utilizzo di politiche di accesso completo non è la migliore pratica per le applicazioni di produzione. L'esempio seguente aggiorna la policy IAM di DynamoDB per migliorare la sicurezza dell'applicazione. Per saperne di più sulle best practice di sicurezza nelle policy IAM, consulta Identity and access management for 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"

Per aggiornare la policy, è necessario innanzitutto identificare l'ARN delle risorse DynamoDB. Quindi si utilizza l'ARN in una policy IAM personalizzata. Infine, applichi tale policy al profilo della tua istanza.

Se hai allegato la nuova policy al scorekeepRole ruolo, devi scollegarla prima di eliminare lo CloudFormation stack, poiché questa politica allegata bloccherà l'eliminazione dello stack. La policy può essere rimossa automaticamente eliminando la policy.

Eliminazione

Segui questi passaggi per eliminare le risorse dell'applicazione Scorekeep:

Passaggi successivi

Scopri di più su X-Ray nel prossimo capitolo,. AWS X-Ray concetti

Per strumentare la tua app, scopri di più sull'X-Ray SDK for Java o su uno degli altri SDK X-Ray:

Per eseguire il demone X-Ray localmente o su, vedere. AWSAWS X-Ray demone

Per contribuire all'applicazione di esempio su GitHub, vedere. eb-java-scorekeep