Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Guida introduttiva all'applicazione di esempio Scorekeep
Nota
X-Ray SDK/Daemon Avviso di manutenzione: il 25 febbraio 2026, AWS X-Ray SDKs/Daemon entrerà in modalità manutenzione, che AWS limiterà le versioni di X-Ray SDK e Daemon per risolvere solo i problemi di sicurezza. Per ulteriori informazioni sulla tempistica dell'assistenza, consulta. Cronologia di X-Ray SDK e Daemon Support Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere Migrazione dalla X-Ray strumentazione alla strumentazione. OpenTelemetry
Questo tutorial utilizza il xray-gettingstarted ramo dell'applicazione di esempio Scorekeep, utilizzato CloudFormation per creare e configurare le risorse che eseguono l'applicazione e il demone di esempio su Amazon ECS. X-Ray L'applicazione utilizza il framework Spring per implementare un'API web JSON e per rendere persistenti i dati in Amazon AWS SDK per Java DynamoDB. Un filtro servlet nell'applicazione gestisce tutte le richieste in entrata servite dall'applicazione e un gestore di richieste sul client AWS SDK gestisce le chiamate a valle verso DynamoDB.
Puoi seguire questo tutorial usando il o il. Console di gestione AWS AWS CLI
Sections
Prerequisiti
Questo tutorial serve CloudFormation a creare e configurare le risorse che eseguono l'applicazione e il X-Ray demone di esempio. I seguenti prerequisiti sono necessari per installare ed eseguire il tutorial:
-
Se utilizzi un utente IAM con autorizzazioni limitate, aggiungi le seguenti politiche utente nella console IAM:
-
AWSCloudFormationFullAccess— per accedere e utilizzare CloudFormation -
AmazonS3FullAccess— per caricare un file modello da CloudFormation utilizzare Console di gestione AWS -
IAMFullAccess— per creare i ruoli delle istanze Amazon ECS e Amazon EC2 -
AmazonEC2FullAccess— per creare le risorse Amazon EC2 -
AmazonDynamoDBFullAccess— per creare le tabelle DynamoDB -
AmazonECS_FullAccess— per creare risorse Amazon ECS -
AmazonSNSFullAccess— per creare l'argomento Amazon SNS -
AWSXrayReadOnlyAccess— per ottenere il permesso di visualizzare la mappa delle tracce e le tracce nella console X-Ray
-
-
Per eseguire il tutorial utilizzando il AWS CLI, installa la CLI versione 2.7.9 o successiva e configura la CLI con l'utente del passaggio precedente. Assicurati che la regione sia configurata durante la configurazione con l'utente. AWS CLI Se una regione non è configurata, dovrai aggiungerla
--regiona ogni comando CLI.AWS-REGION -
Assicurati che Git
sia installato, per clonare il repository dell'applicazione di esempio. -
Usa il seguente esempio di codice per clonare il
xray-gettingstartedramo del repository Scorekeep:git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted
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 tracciamento verso X-Ray. Innanzitutto, recupera l'URL dell'app Web utilizzando Console di gestione AWS o: AWS CLI
Usa l'applicazione web per generare dati di tracciamento
-
Scegliere Create (Crea) per creare un utente e una sessione.
-
Digitare un game name (nome del gioco), impostare Rules (Regole) a Tic Tac Toe (Tris) e quindi scegliere Create (Crea) per creare un gioco.
-
Scegliere Play (Gioca) per iniziare il gioco.
-
Scegliere un riquadro per fare una mossa e modificare lo stato del gioco.
Ognuno 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 delle tracce nel Console di gestione AWS
È possibile visualizzare la mappa delle tracce e le tracce generate dall'applicazione di esempio nelle CloudWatch console X-Ray e.
La causa indica che l'indirizzo e-mail fornito in una chiamata a createSubscription invocata nella classe WebConfig non è valido. Nella prossima sezione, risolveremo il problema.
Configurazione delle notifiche Amazon SNS
Scorekeep utilizza Amazon SNS per inviare notifiche quando gli utenti completano una partita. Quando l'applicazione si avvia, tenta di creare un abbonamento per un indirizzo email definito in un CloudFormation parametro dello stack. Quella chiamata non riesce al momento. Configura un'email di notifica per abilitare le notifiche e risolvere gli errori evidenziati nella mappa di tracciamento.
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 l' X-Ray SDK per Java. Quando si distribuisce l'applicazione con il CloudFormation modello, vengono create le tabelle DynamoDB, il cluster Amazon ECS 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 X-Ray pubblico ufficiale. 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 ai percorsi che iniziano con /api all'API.
Per analizzare le richieste HTTP in ingresso, l'applicazione aggiunge il TracingFilter fornito dall'SDK.
Esempio src/main/java/scorekeep/WebConfig.java - filtro servlet
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 per Java Per strumentare queste chiamate, l'applicazione accetta semplicemente i AWS SDK-related sottomoduli come dipendenze e l' X-Ray SDK per Java strumenta automaticamente tutti i client SDK. AWS
L'applicazione utilizza Docker per creare il codice sorgente sull'istanza Gradle Docker Image e il Scorekeep API Dockerfile file per eseguire il JAR eseguibile che Gradle genera al suo interno. ENTRYPOINT
Esempio utilizzo di Docker per creare tramite Gradle Docker Image
docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle buildEsempio PUNTO DI INGRESSO del file Dockerfile
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.
Esempio build.gradle -- 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' X-Ray API, il X-Ray daemon deve ascoltare il traffico sulla porta UDP 2000. A tale scopo, l'applicazione fa eseguire il X-Ray demone in un contenitore che viene distribuito insieme all'applicazione Scorekeep su ECS come contenitore secondario. Per ulteriori informazioni, consulta l'argomento relativo al demone. X-Ray
Esempio X-Ray Definizione del contenitore daemon in una definizione di attività ECS
...
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 per 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.
Esempio src/main/java/scorekeep/WebConfig.java - registratore
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.
Esempio src/main//sampling-rules.json java/resources
{
"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 politiche di accesso completo, 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 politica IAM di DynamoDB per migliorare la sicurezza dell'applicazione. Per saperne di più sulle best practice di sicurezza nelle policy IAM, vedi Identity and access management for. AWS X-Ray
Esempio definizione del modello cf-resources.yaml ECSTaskRole
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 tua policy, devi prima identificare l'ARN delle tue risorse DynamoDB. Quindi si utilizza l'ARN in una policy IAM personalizzata. Infine, applichi tale policy al profilo della tua istanza.
Per identificare l'ARN della tua risorsa DynamoDB:
-
Aprire la console DynamoDB
. -
Scegli Tabelle dalla barra di navigazione a sinistra.
-
Scegliete una delle opzioni
scorekeep-*per visualizzare la pagina dei dettagli della tabella. -
Nella scheda Panoramica, scegli Informazioni aggiuntive per espandere la sezione e visualizzare Amazon Resource Name (ARN). Copia questo valore.
-
Inserisci l'ARN nella seguente policy IAM, sostituendo
AWS_ACCOUNT_IDi valoriAWS_REGIONe con la regione e l'ID dell'account specifici. Questa nuova policy consente solo le azioni specificate, invece dellaAmazonDynamoDBFullAccesspolicy che consente qualsiasi azione.Esempio
Le tabelle create dall'applicazione seguono una convenzione di denominazione coerente. È possibile utilizzare il
scorekeep-*formato per indicare tutte le tabelle Scorekeep.
Cambia la tua politica IAM
-
Apri il ruolo dell'attività Scorekeep (ScorekeepRole) dalla console IAM.
-
Seleziona la casella di controllo accanto alla
AmazonDynamoDBFullAccesspolicy e scegli Rimuovi per rimuovere questa policy. -
Scegli Aggiungi autorizzazioni, quindi Allega politiche e infine Crea policy.
-
Scegli la scheda JSON e incolla la policy creata sopra.
-
Scegli Avanti: Tag nella parte inferiore della pagina.
-
Scegli Avanti: Rivedi nella parte inferiore della pagina.
-
In Nome, assegna un nome alla policy.
-
Scegli Crea policy nella parte inferiore della pagina.
-
Allega la policy appena creata al
scorekeepRoleruolo. Potrebbero essere necessari alcuni minuti prima che la politica allegata abbia effetto.
Se hai allegato il nuovo criterio al scorekeepRole ruolo, devi scollegarlo prima di eliminare lo CloudFormation stack, poiché questo criterio allegato bloccherà l'eliminazione dello stack. La policy può essere rimossa automaticamente eliminando la policy.
Rimuovi la tua policy IAM personalizzata
-
Apri la console IAM
. -
Scegli Policy dalla barra di navigazione a sinistra.
-
Cerca il nome della politica personalizzata che hai creato in precedenza in questa sezione e scegli il pulsante di opzione accanto al nome della politica per evidenziarlo.
-
Scegli il menu a discesa Azioni, quindi scegli Elimina.
-
Digita il nome della politica personalizzata, quindi scegli Elimina per confermare l'eliminazione. Questo scollegherà automaticamente la policy dal
scorekeepRoleruolo.
Eliminazione
Segui questi passaggi per eliminare le risorse dell'applicazione Scorekeep:
Nota
Se hai creato e allegato policy personalizzate utilizzando la sezione precedente di questo tutorial, devi rimuovere la policy dalla scorekeepRole prima di eliminare lo stack. CloudFormation
Fasi successive
Scopri di più X-Ray nel prossimo capitolo,AWS X-Ray concetti.
Per personalizzare la tua app, scopri di più sull' X-Ray SDK per Java o su uno degli altri X-Ray SDK:
-
X-Ray SDK per Java — AWS X-Ray SDK per Java
-
X-Ray SDK per — Node.js AWS X-Ray SDK per Node.js
-
X-Ray SDK per .NET — AWS X-Ray SDK per.NET
Per eseguire il X-Ray demone localmente o acceso AWS, vedi. AWS X-Ray demone
Per contribuire all'applicazione di esempio su GitHub, vedere https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted
