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à. # AWS X-Ray applicazione di esempio **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry L'app di [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray)esempio AWS X-Ray, disponibile su GitHub, mostra l'uso dell'SDK AWS X-Ray per monitorare le chiamate HTTP in entrata, i client SDK DynamoDB e i client HTTP. L'app di esempio consente CloudFormation di creare tabelle DynamoDB, compilare codice Java su istanza ed eseguire il demone X-Ray senza alcuna configurazione aggiuntiva. Consulta il [tutorial Scorekeep](scorekeep-tutorial.md) per iniziare a installare e utilizzare un'applicazione di esempio strumentata, utilizzando o il. Console di gestione AWS AWS CLI ![\[Scorekeep utilizza l'SDK AWS X-Ray per monitorare le chiamate HTTP in entrata, i client DynamoDB SDK e i client HTTP\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-flow.png) L'esempio include un'app Web front-end, l'API che chiama e le tabelle DynamoDB che utilizza per archiviare i dati. La strumentazione di base con [filtri](xray-sdk-java-filters.md), [plugin](xray-sdk-java-configuration.md) e client [AWS SDK strumentati](xray-sdk-java-awssdkclients.md) è mostrata nella sezione dedicata al progetto. `xray-gettingstarted` Questo è il ramo che viene distribuito nel [tutorial sulle nozioni di base](scorekeep-tutorial.md). Poiché questo ramo include solo le nozioni di base, puoi eseguire una diff rispetto al ramo `master` per individuare rapidamente le nozioni di base. ![\[Service map showing client interaction with Scorekeep container and related Servizi AWS.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) L'applicazione di esempio illustra l'analisi di base in questi file: + **Filtro di richiesta HTTP: [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java)** + **AWS Strumentazione client SDK** — [https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle](https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle) [Il `xray` ramo dell'applicazione include l'uso di [annotazioni](xray-sdk-java-segment.md), [query SQL [HTTPClient](xray-sdk-java-httpclients.md)](xray-sdk-java-sqlclients.md), [sottosegmenti personalizzati](xray-sdk-java-subsegments.md), una [AWS Lambda](xray-services-lambda.md)funzione strumentata e codice e script di inizializzazione strumentati.](scorekeep-startup.md) Per supportare l'accesso e l' AWS SDK per JavaScript utilizzo degli utenti nel browser, la `xray-cognito` filiale aggiunge Amazon Cognito per supportare l'autenticazione e l'autorizzazione degli utenti. Con le credenziali recuperate da Amazon Cognito, l'app Web invia anche dati di traccia a X-Ray per registrare le informazioni sulla richiesta dal punto di vista del cliente. Il client del browser appare come un nodo a sé stante sulla mappa di tracciamento e registra informazioni aggiuntive, tra cui l'URL della pagina che l'utente sta visualizzando e l'ID dell'utente. Infine, il `xray-worker` ramo aggiunge una funzione Python Lambda strumentata che viene eseguita in modo indipendente, elaborando gli elementi da una coda Amazon SQS. Scorekeep aggiunge un elemento alla coda ogni volta che termina una partita. L'operatore Lambda, attivato da CloudWatch Events, estrae gli elementi dalla coda ogni pochi minuti e li elabora per archiviare i record di gioco in Amazon S3 per l'analisi. **Topics** + [Guida introduttiva all'applicazione di esempio Scorekeep](scorekeep-tutorial.md) + [Strumentazione manuale dei client SDK AWS](scorekeep-sdkclients.md) + [Creazione di sottosegmenti aggiuntivi](scorekeep-subsegments.md) + [Registrazione di annotazioni, metadati e utenti IDs](scorekeep-annotations.md) + [Analisi delle chiamate HTTP in uscita](scorekeep-httpclient.md) + [Analizzare le chiamate a un database PostgresSQL](scorekeep-postgresql.md) + [Funzioni di strumentazione AWS Lambda](scorekeep-lambda.md) + [Analisi del codice di avvio](scorekeep-startup.md) + [Analisi degli script](scorekeep-scripts.md) + [Analisi di un client di app Web](scorekeep-client.md) + [Utilizzo dei client analizzati nei thread worker](scorekeep-workerthreads.md) # Guida introduttiva all'applicazione di esempio Scorekeep **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Questo tutorial utilizza il `xray-gettingstarted` ramo dell'[applicazione di esempio Scorekeep](xray-scorekeep.md), che utilizza 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 per 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. Console di gestione AWS AWS CLI **Topics** + [Prerequisiti](#xray-gettingstarted-prereqs) + [Installa l'applicazione Scorekeep utilizzando CloudFormation](#xray-gettingstarted-deploy) + [Generare i dati di tracciamento](#xray-gettingstarted-generate-traces) + [Visualizza la mappa di tracciamento nel Console di gestione AWS](#xray-gettingstarted-console) + [Configurazione delle notifiche Amazon SNS](#xray-gettingstarted-notifications) + [Esplorare l'applicazione di esempio](#xray-gettingstarted-sample) + [Opzionale: policy con privilegio minimo](#xray-gettingstarted-security) + [Eliminazione](#xray-gettingstarted-cleanup) + [Fasi successive](#xray-gettingstarted-nextsteps) ## Prerequisiti Questo tutorial serve 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: 1. Se utilizzi un utente IAM con autorizzazioni limitate, aggiungi le seguenti politiche utente nella console [IAM](https://console.aws.amazon.com/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 il permesso di visualizzare la mappa di tracciamento e le tracce nella console X-Ray 1. Per eseguire il tutorial utilizzando la AWS CLI, [installa la CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) versione 2.7.9 o successiva e configura [la CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) 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, sarà necessario aggiungerla `--region AWS-REGION` a ogni comando CLI. 1. Assicurati che [Git](https://github.com/git-guides/install-git) sia installato, per clonare il repository dell'applicazione di esempio. 1. Usa il seguente esempio di codice per clonare il `xray-gettingstarted` ramo 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 ------ #### [ Console di gestione AWS ] **Installa l'applicazione di esempio utilizzando il Console di gestione AWS** 1. Apri la [console CloudFormation](https://console.aws.amazon.com/cloudformation/) 1. Scegli **Crea stack**, quindi scegli **Con nuove risorse** dal menu a discesa. 1. Nella sezione **Specify template**(Specifica il modello) scegliere **Upload a template file** (Carica un file modello). 1. Seleziona **Scegli file**, vai alla `xray-scorekeep/cloudformation` cartella che è stata creata quando hai clonato il repository git e scegli il file. `cf-resources.yaml` 1. Seleziona **Successivo** per continuare. 1. Entra `scorekeep` nella casella di testo **Stack name**, quindi scegli **Avanti** nella parte inferiore della pagina per continuare. Nota che il resto di questo tutorial presuppone che lo stack abbia un nome. `scorekeep` 1. Scorri fino alla fine della pagina **Configura le opzioni dello stack** e scegli **Avanti** per continuare. 1. **Scorri fino alla fine della pagina di **revisione**, seleziona la casella di controllo che riconosce che CloudFormation potrebbe creare risorse IAM con nomi personalizzati e scegli Create stack.** 1. Lo CloudFormation stack è ora in fase di creazione. Lo stato dello stack rimarrà `CREATE_IN_PROGRESS` per circa cinque minuti prima di passare a. `CREATE_COMPLETE` Lo stato verrà aggiornato periodicamente oppure puoi aggiornare la pagina. ------ #### [ AWS CLI ] **Installa l'applicazione di esempio utilizzando AWS CLI** 1. Accedete alla `cloudformation` cartella del `xray-scorekeep` repository che avete clonato in precedenza nel tutorial: ``` cd xray-scorekeep/cloudformation/ ``` 1. Immettete il seguente AWS CLI comando per creare lo stack: CloudFormation ``` aws cloudformation create-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Attendi che lo stato dello CloudFormation stack sia raggiunto`CREATE_COMPLETE`, operazione che richiederà circa cinque minuti. Usa il seguente AWS CLI comando per controllare lo stato: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## 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 Console di gestione AWS o: AWS CLI ------ #### [ Console di gestione AWS ] **Trovate l'URL dell'applicazione utilizzando il Console di gestione AWS** 1. Apri la [console CloudFormation](https://console.aws.amazon.com/cloudformation/) 1. Scegliete lo `scorekeep` stack dall'elenco. 1. Scegli la scheda **Output** nella pagina dello `scorekeep` stack e scegli il link `LoadBalancerUrl` URL per aprire l'applicazione web. ------ #### [ AWS CLI ] **Trovate l'URL dell'applicazione utilizzando il AWS CLI** 1. Utilizzate il seguente comando per visualizzare l'URL dell'applicazione Web: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].Outputs[0].OutputValue" ``` 1. Copia questo URL e aprilo in un browser per visualizzare l'applicazione web Scorekeep. ------ **Utilizza l'applicazione Web per generare dati di traccia** 1. Scegliere **Create (Crea)** per creare un utente e una sessione. 1. Digitare un **game name (nome del gioco)**, impostare **Rules (Regole)** a **Tic Tac Toe (Tris)** e quindi scegliere **Create (Crea)** per creare un gioco. 1. Scegliere **Play (Gioca)** per iniziare il gioco. 1. Scegliere un riquadro per fare una mossa e modificare lo stato del gioco. 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 Console di gestione AWS È possibile visualizzare la mappa di traccia e le tracce generate dall'applicazione di esempio negli X-Ray e CloudWatch nelle console. ------ #### [ X-Ray console ] **Usa la console X-Ray** 1. Apri la pagina della mappa di tracciamento della console [X-Ray](https://console.aws.amazon.com/xray/home#/service-map). 1. La console mostra una rappresentazione del grafico del servizio generato da X-Ray dai dati di traccia inviati dall'applicazione. Assicurati di modificare il periodo di tempo della mappa di traccia, se necessario, per assicurarti che mostri tutte le tracce dal primo avvio dell'applicazione web. ![\[Periodo temporale della mappa di tracciamento a raggi X\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/xray-console-time-period-15-minutes.png) La mappa di traccia mostra il client dell'app Web, l'API in esecuzione in Amazon ECS e ogni tabella DynamoDB utilizzata dall'applicazione. Ogni richiesta all'applicazione, fino a un numero massimo configurabile di richieste al secondo, viene tracciata non appena viene ricevuta dall'API, genera le richieste verso i servizi a valle e si conclude. Puoi scegliere qualsiasi nodo del grafo del servizio per visualizzare i dati di tracciamento per le richieste che hanno generato il traffico verso tale nodo. Attualmente, il nodo Amazon SNS è giallo. Approfondisci l'esplorazione per scoprire perché. ![\[Pagina della mappa di tracciamento della console X-Ray\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) **Per trovare la causa dell'errore** 1. Scegliere il nodo denominato **SNS**. Viene visualizzato il pannello dei dettagli del nodo. 1. Scegliere **View traces (Visualizza tracciamenti)** per accedere alla schermata **Trace overview (Panoramica tracciamenti)**. 1. Scegliere il tracciamento dalla **Trace list (Elenco tracciamenti)**. A questo tracciamento non sono associati metodo o URL perché è stato registrato durante l'avvio anziché in risposta a una richiesta in entrata. ![\[Scegliere un tracciamento dall'elenco dei tracciamenti\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-tracelist-sns.png) 1. Scegli l'icona dello stato dell'errore all'interno del segmento Amazon SNS nella parte inferiore della pagina per aprire la pagina **Eccezioni** per il sottosegmento SNS. ![\[Scegli l'icona dello stato dell'errore per aprire la pagina Eccezioni per il sottosegmento Amazon SNS\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-timeline-sns-ecs.png) 1. L'SDK X-Ray acquisisce automaticamente le eccezioni generate dai client AWS SDK strumentati e registra la traccia dello stack. ![\[La scheda Exceptions (Eccezioni) mostra le eccezioni acquisite e memorizza lo stack trace\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-exception.png) ------ #### [ CloudWatch console ] **Usa la console CloudWatch** 1. Apri la pagina della [mappa di tracciamento X-Ray](https://console.aws.amazon.com/cloudwatch/home#xray:service-map/map) della CloudWatch console. 1. La console mostra una rappresentazione del grafico del servizio generato da X-Ray dai dati di traccia inviati dall'applicazione. Assicurati di modificare il periodo di tempo della mappa di traccia, se necessario, per assicurarti che mostri tutte le tracce dal primo avvio dell'applicazione web. ![\[CloudWatch periodo di tempo della mappa di tracciamento\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/cw-console-service-map-time-period-15-minutes.png) La mappa di traccia mostra il client dell'app Web, l'API in esecuzione in Amazon EC2 e ogni tabella DynamoDB utilizzata dall'applicazione. Ogni richiesta all'applicazione, fino a un numero massimo configurabile di richieste al secondo, viene tracciata non appena viene ricevuta dall'API, genera le richieste verso i servizi a valle e si conclude. Puoi scegliere qualsiasi nodo del grafo del servizio per visualizzare i dati di tracciamento per le richieste che hanno generato il traffico verso tale nodo. Attualmente, il nodo Amazon SNS è arancione. Approfondisci l'esplorazione per scoprire perché. ![\[Pagina della mappa di tracciamento della console X-Ray\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-before-ECS.png) **Per trovare la causa dell'errore** 1. Scegliere il nodo denominato **SNS**. Il pannello dei dettagli del nodo SNS viene visualizzato sotto la mappa. 1. Scegli **Visualizza tracce** per accedere alla pagina **Traces**. 1. Aggiungi la parte inferiore della pagina, scegli la traccia dall'elenco **Tracce**. A questo tracciamento non sono associati metodo o URL perché è stato registrato durante l'avvio anziché in risposta a una richiesta in entrata. ![\[Scegliere un tracciamento dall'elenco dei tracciamenti\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-cw-tracelist-sns-ecs.png) 1. Scegli il sottosegmento Amazon SNS nella parte inferiore della cronologia dei segmenti e scegli la scheda **Eccezioni** per il sottosegmento SNS per visualizzare i dettagli dell'eccezione. ![\[Visualizza la scheda Eccezioni per il sottosegmento Amazon SNS\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png) ------ 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. ------ #### [ Console di gestione AWS ] **Per configurare le notifiche di Amazon SNS utilizzando Console di gestione AWS** 1. Apri la [console CloudFormation](https://console.aws.amazon.com/cloudformation/) 1. **Scegli il pulsante di opzione accanto al nome dello `scorekeep` stack nell'elenco, quindi scegli Aggiorna.** 1. Assicurati che sia selezionata **l'opzione Usa modello corrente**, quindi fai clic su **Avanti** nella pagina **Aggiorna stack**. 1. Individuate il parametro **Email** nell'elenco e sostituite il valore predefinito con un indirizzo e-mail valido. ![\[Aggiorna la configurazione dell'e-mail\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-cf-email-update.png) 1. Scorri fino alla parte inferiore della pagina e scegli **Next** (Avanti). 1. Scorri fino alla fine della pagina di **revisione**, seleziona la casella di controllo che conferma che CloudFormation potrebbe creare risorse IAM con nomi personalizzati e scegli **Update** stack. 1. Lo CloudFormation stack è ora in fase di aggiornamento. Lo stato dello stack rimarrà `UPDATE_IN_PROGRESS` per circa cinque minuti prima di passare a. `UPDATE_COMPLETE` Lo stato verrà aggiornato periodicamente oppure puoi aggiornare la pagina. ------ #### [ AWS CLI ] **Per configurare le notifiche di Amazon SNS utilizzando AWS CLI** 1. Accedi alla `xray-scorekeep/cloudformation/` cartella creata in precedenza e apri il `cf-resources.yaml` file in un editor di testo. 1. Trovate il `Default` valore all'interno del parametro **Email** e modificatelo *UPDATE\$1ME* in un indirizzo e-mail valido. ``` Parameters: Email: Type: String Default: UPDATE_ME # <- change to a valid abc@def.xyz email address ``` 1. Dalla `cloudformation` cartella, aggiorna lo CloudFormation stack con il seguente AWS CLI comando: ``` aws cloudformation update-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Attendi che lo stato dello CloudFormation stack sia `UPDATE_COMPLETE` raggiunto, operazione che richiederà alcuni minuti. Usa il seguente AWS CLI comando per controllare lo stato: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ 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 verso l'API. Per analizzare le richieste HTTP in ingresso, l'applicazione aggiunge il `TracingFilter` fornito dall'SDK. **Example src/main/java/scorekeep/WebConfig.java - filtro servlet** ``` import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); ... @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 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` **Example uso 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 build ``` **Example PUNTO DI INGRESSO DEL FILE DOCKER** ``` 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. **Example 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'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](xray-daemon.md). **Example Definizione del contenitore X-Ray 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 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. **Example 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. **Example src/main/java/resources/sampling-regole.json** ``` { "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](xray-scorekeep.md). ## 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 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](security-iam.md). **Example Modello cf-resources.yaml Definizione del ruolo ECSTask** ``` 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. **Per identificare l'ARN della tua risorsa DynamoDB:** 1. Aprire la [console DynamoDB](https://console.aws.amazon.com/dynamodbv2). 1. Scegli **Tabelle dalla barra** di navigazione a sinistra. 1. Scegli una delle opzioni `scorekeep-*` per visualizzare la pagina dei dettagli della tabella. 1. Nella scheda **Panoramica**, scegli **Informazioni aggiuntive** per espandere la sezione e visualizzare Amazon Resource Name (ARN). Copia questo valore. 1. Inserisci l'ARN nella seguente politica IAM, sostituendo `AWS_ACCOUNT_ID` i valori `AWS_REGION` and con la regione e l'ID dell'account specifici. Questa nuova politica consente solo le azioni specificate, anziché la `AmazonDynamoDBFullAccess` politica che consente qualsiasi azione. **Example** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query" ], "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/scorekeep-*" } ] } ``` ------ 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** 1. Apri il [ruolo dell'attività Scorekeep (ScorekeepRole) dalla console IAM.](https://console.aws.amazon.com/iamv2/home#/roles/details/scorekeepRole) 1. **Seleziona la casella di controllo accanto alla `AmazonDynamoDBFullAccess` politica e scegli Rimuovi per rimuovere questa politica.** 1. Scegli **Aggiungi autorizzazioni**, quindi **Allega politiche** e infine **Crea politica**. 1. Scegli la scheda **JSON** e incolla la politica creata sopra. 1. Scegli **Avanti: Tag** nella parte inferiore della pagina. 1. Scegli **Avanti: revisione** nella parte inferiore della pagina. 1. Per **Nome**, assegna un nome alla politica. 1. Scegli **Crea politica** nella parte inferiore della pagina. 1. Allega la politica appena creata al `scorekeepRole` ruolo. Potrebbero essere necessari alcuni minuti prima che la policy allegata abbia effetto. 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. **Rimuovi la tua policy IAM personalizzata** 1. Apri la [console IAM](https://console.aws.amazon.com/iam). 1. Scegli **Policies** dalla barra di navigazione a sinistra. 1. 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. 1. **Scegli il menu a discesa **Azioni**, quindi scegli Elimina.** 1. Digita il nome della politica personalizzata, quindi scegli **Elimina per confermare l'eliminazione**. Ciò scollegherà automaticamente la politica dal `scorekeepRole` ruolo. ## Eliminazione Segui questi passaggi per eliminare le risorse dell'applicazione Scorekeep: **Nota** Se hai creato e allegato politiche personalizzate utilizzando la sezione precedente di questo tutorial, devi rimuovere la politica `scorekeepRole` prima di eliminare lo stack. CloudFormation ------ #### [ Console di gestione AWS ] **Eliminare l'applicazione di esempio utilizzando il Console di gestione AWS** 1. Apri la [console CloudFormation](https://console.aws.amazon.com/cloudformation/) 1. Scegliete il pulsante di opzione accanto al nome `scorekeep` dello stack nell'elenco, quindi scegliete **Elimina**. 1. Lo CloudFormation stack viene ora eliminato. Lo stato dello stack rimarrà valido `DELETE_IN_PROGRESS` per alcuni minuti fino all'eliminazione di tutte le risorse. Lo stato verrà aggiornato periodicamente oppure puoi aggiornare la pagina. ------ #### [ AWS CLI ] **Eliminare l'applicazione di esempio utilizzando il AWS CLI** 1. Immettete il seguente AWS CLI comando per eliminare lo CloudFormation stack: ``` aws cloudformation delete-stack --stack-name scorekeep ``` 1. Attendi che lo CloudFormation stack non esista più, l'operazione richiederà circa cinque minuti. Usa il seguente AWS CLI comando per controllare lo stato: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## Fasi successive Scopri di più su X-Ray nel prossimo capitolo,. [AWS X-Ray concetti](xray-concepts.md) Per strumentare la tua app, scopri di più sull'X-Ray SDK for Java o su uno degli altri X-Ray: SDKs + **X-Ray SDK** per Java — [AWS X-Ray SDK per Java](xray-sdk-java.md) + **X-Ray SDK** per Node.js — [AWS X-Ray SDK per Node.js](xray-sdk-nodejs.md) + **X-Ray SDK** per.NET — [AWS X-Ray SDK per.NET](xray-sdk-dotnet.md) Per eseguire il demone X-Ray localmente o su, vedere. AWS[AWS X-Ray demone](xray-daemon.md) Per contribuire all'applicazione di esempio su GitHub, vedere. [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted) # Strumentazione manuale dei client SDK AWS **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry L'X-Ray SDK for Java strumenta automaticamente tutti i client SDK quando [includi il AWS sottomodulo SDK Instrumentor nelle AWS dipendenze di compilazione](xray-sdk-java.md#xray-sdk-java-dependencies). Puoi disabilitare l'analisi automatica del client rimuovendo il sottomodulo Instrumentor. In questo modo puoi analizzare manualmente alcuni client escludendone altri, oppure utilizzare diversi gestori del tracciamento su diversi client. Per illustrare il supporto per la strumentazione di client AWS SDK specifici, l'applicazione passa un gestore di tracciamento come gestore di richieste nel modello utente, di gioco e di `AmazonDynamoDBClientBuilder` sessione. Questa modifica al codice indica all'SDK di strumentare tutte le chiamate a DynamoDB utilizzando tali client. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java)— Strumentazione manuale del client SDK AWS** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); public class SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client); ``` Se rimuovi il sottomodulo AWS SDK Instrumentor dalle dipendenze del progetto, nella mappa di traccia vengono visualizzati solo i client SDK con strumentazione AWS manuale. # Creazione di sottosegmenti aggiuntivi **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Nella classe del modello utente, l'applicazione crea manualmente dei sottosegmenti per raggruppare tutte le chiamate a valle effettuate all'interno della funzione `saveUser` e aggiunge i metadati. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java) - Sottosegmenti personalizzati** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` # Registrazione di annotazioni, metadati e utenti IDs **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Nella classe game model, l'applicazione registra `Game` gli oggetti in un blocco di [metadati](xray-sdk-java-segment.md#xray-sdk-java-segment-metadata) ogni volta che salva un gioco in DynamoDB. [Separatamente, l'applicazione registra il gioco IDs in [annotazioni](xray-sdk-java-segment.md#xray-sdk-java-segment-annotations) da utilizzare con le espressioni di filtro.](xray-console-filters.md) **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java)— Annotazioni e metadati** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` Nel controller di spostamento, l'applicazione registra l'[utente IDs](xray-sdk-java-segment.md#xray-sdk-java-segment-userid) con. `setUser` IDsGli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati con la ricerca. **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — ID utente** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` # Analisi delle chiamate HTTP in uscita **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry La classe user factory mostra come l'applicazione utilizza la versione X-Ray SDK per Java per `HTTPClientBuilder` strumentare le chiamate HTTP in uscita. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java) HTTPClient — strumentazione** ``` import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://uinames.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` Se al momento utilizzi `org.apache.http.impl.client.HttpClientBuilder`, è possibile sostituire l'istruzione di importazione della classe con una che includa `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder`. # Analizzare le chiamate a un database PostgresSQL **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Il `application-pgsql.properties` file aggiunge l'intercettore di tracciamento X-Ray PostgreSQL all'origine dati creata in. [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java) **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties)— Strumentazione del database PostgreSQL** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Nota** Per ulteriori informazioni su come aggiungere un database PostgreSQL all'ambiente dell'applicazione, consulta [Configurazione dei database con Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.managing.db.html) nella *Guida per lo sviluppatore di AWS Elastic Beanstalk *. La pagina dimostrativa di X-Ray nella `xray` filiale include una demo che utilizza la fonte di dati strumentata per generare tracce che mostrano informazioni sulle query SQL che genera. Vai al `/#/xray` percorso nell'applicazione in esecuzione o scegli **Powered by AWS X-Ray** nella barra di navigazione per visualizzare la pagina dimostrativa. ![\[AWS X-Ray integration demo page showing game session tracing and SQL query tracing options.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-demo.png) Scegli **Trace SQL queries (Traccia query SQL)** per simulare le sessioni di gioco e memorizzare i risultati nel database collegato. Quindi, scegli **Visualizza le tracce in AWS X-Ray** per visualizzare un elenco filtrato di tracce che raggiungono il percorso dell'API. `/api/history` Scegli uno dei tracciamenti nell'elenco per visualizzare la sequenza temporale, inclusa la query SQL. ![\[Timeline view of a trace showing method, response, duration, and age for a GET request.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-trace-sql.png) # Funzioni di strumentazione AWS Lambda **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry AWS Lambda Scorekeep utilizza due funzioni. La prima è una funzione Node.js del ramo `lambda` che genera nomi casuali per i nuovi utenti. Quando un utente crea una sessione senza immettere un nome, l'applicazione chiama una funzione denominata `random-name` con il AWS SDK per Java. L'X-Ray SDK for Java registra le informazioni sulla chiamata a Lambda in un sottosegmento come qualsiasi altra chiamata effettuata con un client SDK strumentato. AWS **Nota** L'esecuzione della funzione `random-name` Lambda richiede la creazione di risorse aggiuntive all'esterno dell'ambiente Elastic Beanstalk. Per ulteriori informazioni e istruzioni, consulta il file readme: [AWS Lambda Integration](https://github.com/awslabs/eb-java-scorekeep/tree/xray/README.md#aws-lambda-integration). La seconda funzione, `scorekeep-worker`, è una funzione Python che viene eseguita indipendentemente dall'API Scorekeep. Quando una partita termina, l'API scrive l'ID della sessione e l'ID della partita su una coda SQS. La funzione worker legge gli elementi dalla coda e chiama l'API Scorekeep per creare record completi di ogni sessione di gioco da archiviare in Amazon S3. Scorekeep include CloudFormation modelli e script per creare entrambe le funzioni. Poiché è necessario raggruppare X-Ray SDK con il codice della funzione, i modelli creano le funzioni senza alcun codice. Quando distribuisci Scorekeep, un file di configurazione incluso nella cartella `.ebextensions` crea un pacchetto di codice sorgente che include l'SDK e aggiorna il codice della funzione e la configurazione con AWS Command Line Interface. **Topics** + [Nome casuale](#scorekeep-lambda-randomname) + [Worker](#scorekeep-lambda-worker) ## Nome casuale Scorekeep richiama la funzione di generazione del nome casuale quando un utente avvia una sessione di gioco senza aver eseguito l'accesso oppure senza aver specificato un nome utente. Quando Lambda elabora la chiamata a`random-name`, legge l'[intestazione di tracciamento](xray-concepts.md#xray-concepts-tracingheader), che contiene l'ID di traccia e la decisione di campionamento scritta da X-Ray SDK for Java. Per ogni richiesta campionata, Lambda esegue il demone X-Ray e scrive due segmenti. Il primo segmento registra informazioni sulla chiamata a Lambda che richiama la funzione. Questo segmento contiene le stesse informazioni del sottosegmento registrato da Scorekeep, ma dal punto di vista Lambda. Il secondo segmento rappresenta l'attività svolta dalla funzione. Lambda passa il segmento di funzione a X-Ray SDK tramite il contesto della funzione. Quando si strumenta una funzione Lambda, non si utilizza l'SDK per [creare un segmento per](xray-sdk-nodejs-middleware.md) le richieste in arrivo. Lambda fornisce il segmento e tu usi l'SDK per strumentare i client e scrivere sottosegmenti. ![\[Mappa di traccia che mostra come scorekeep chiama una funzione Lambda per ottenere nomi casuali per i nuovi utenti\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-servicemap-lambda-node.png) La funzione `random-name` è implementata in Node.js Utilizza l'SDK per Node.js per JavaScript inviare notifiche con Amazon SNS e l'SDK X-Ray per Node.js per strumentare il client SDK. AWS Per scrivere annotazioni, la funzione crea una sottosegmento personalizzato con `AWSXRay.captureFunc` e scrive le annotazioni nella funzione analizzata. In Lambda, non puoi scrivere annotazioni direttamente sul segmento di funzione, ma solo su un sottosegmento che crei. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js) - Funzione Lambda nome casuale** ``` var AWSXRay = require('aws-xray-sdk-core'); var AWS = AWSXRay.captureAWS(require('aws-sdk')); AWS.config.update({region: process.env.AWS_REGION}); var Chance = require('chance'); var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first(); AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); }); // Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } }); }; exports.handler = myFunction; ``` Questa funzione viene creata automaticamente quando distribuisci l'applicazione di esempio su Elastic Beanstalk. Il `xray` ramo include uno script per creare una funzione Lambda vuota. I file di configurazione nella `.ebextensions` cartella creano il pacchetto di funzioni con `npm install` durante la distribuzione, quindi aggiornano la funzione Lambda con la CLI AWS . ## Worker La funzione worker analizzata viene fornito nel suo ramo, `xray-worker`, poiché non può essere eseguita a meno che non si creino prima la funzione worker e le relative risorse. Per le istruzioni, consulta [il readme del ramo](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/README.md). La funzione viene attivata da un evento Amazon CloudWatch Events in bundle ogni 5 minuti. Quando viene eseguita, la funzione estrae un elemento da una coda Amazon SQS gestita da Scorekeep. Ogni messaggio contiene informazioni su una partita completata. Il worker preleva il record della partita e i documenti dalle altre tabelle a cui il record della partita fa riferimento. Ad esempio, il record di gioco in DynamoDB include un elenco di mosse eseguite durante il gioco. L'elenco non contiene le mosse stesse, ma piuttosto IDs le mosse memorizzate in una tabella separata. Anche le sessioni e gli stati sono memorizzati come riferimenti. In questo modo si evita che le voci nella tabella delle partite diventino troppo grandi ma sono necessarie chiamate aggiuntive per recuperare tutte le informazioni sulla partita. L'operatore dereferenzia tutte queste voci e crea un record completo del gioco come documento singolo in Amazon S3. Se desideri eseguire analisi sui dati, puoi eseguire query su di essi direttamente in Amazon S3 con Amazon Athena senza eseguire migrazioni di dati impegnative in lettura per estrarre i dati da DynamoDB. ![\[Mappa di traccia che mostra come la funzione scorekeep worker utilizza Amazon SQS, Amazon S3 e l'API scorekeep.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-servicemap-lambdaworker-node.png) La funzione worker dispone del tracciamento attivo abilitato nella sua configurazione in AWS Lambda. A differenza della funzione random name, l'operatore non riceve una richiesta da un'applicazione strumentata, quindi AWS Lambda non riceve un'intestazione di tracciamento. Con il tracciamento attivo, Lambda crea l'ID di traccia e prende decisioni di campionamento. L'X-Ray SDK per Python si trova a poche righe all'inizio della funzione che importa l'SDK ed esegue la sua `patch_all` funzione per applicare le patch e HTTclients che usa per chiamare Amazon SQS AWS SDK per Python (Boto) e Amazon S3. Quando il worker richiama l'API Scorekeep, l'SDK aggiunge l'[intestazione di tracciamento](xray-concepts.md#xray-concepts-tracingheader) alla richiesta per tracciare le chiamate tramite l'API. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py) -- Funzione worker Lambda** ``` import os import boto3 import json import requests import time from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all patch_all() queue_url = os.environ['WORKER_QUEUE'] def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3') # Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ... ``` # Analisi del codice di avvio **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry L'X-Ray SDK for Java crea automaticamente segmenti per le richieste in arrivo. Se una richiesta rientra nell'ambito, puoi utilizzare i client analizzati e registrare i sottosegmenti senza problemi. Se provi a utilizzare un client con strumenti nel codice di avvio, tuttavia, otterrai un. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html) Il codice di avvio viene eseguito al di fuori del request/response flusso standard di un'applicazione Web, quindi è necessario creare segmenti manualmente per strumentarlo. Scorekeep mostra l'analisi del codice di avvio nel suo file `WebConfig`. Scorekeep chiama un database SQL e Amazon SNS durante l'avvio. ![\[Diagram showing client requests to Scorekeeper-init, which connects to SQL database and SNS.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-servicemap-init.png) La `WebConfig` classe predefinita crea un abbonamento Amazon SNS per le notifiche. Per fornire un segmento su cui scrivere all'SDK X-Ray quando viene utilizzato il client Amazon SNS, le chiamate Scorekeep e sul registratore globale. `beginSegment` `endSegment` **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49)— Client SDK con strumentazione nel codice di avvio AWS** ``` AWSXRay.beginSegment("Scorekeep-init"); if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); } } AWSXRay.endSegment(); ``` In`RdsWebConfig`, che Scorekeep utilizza quando è connesso un database Amazon RDS, la configurazione crea anche un segmento per il client SQL che Hibernate utilizza quando applica lo schema del database durante l'avvio. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83)— Client di database SQL strumentato nel codice di avvio** ``` @PostConstruct public void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor); AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment(); } ``` `SchemaExport` viene eseguito automaticamente e utilizza un client SQL. Poiché il client è analizzato, Scorekeep deve sostituire l'impostazione predefinita e fornire un segmento che l'SDK possa utilizzare quando il client viene richiamato. # Analisi degli script **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Puoi anche analizzare del codice che non fa parte della tua applicazione. Quando il demone X-Ray è in esecuzione, inoltrerà tutti i segmenti che riceve a X-Ray, anche se non sono generati dall'SDK X-Ray. Scorekeep usa i propri script per analizzare il processo di build che compila l'applicazione durante la distribuzione. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh)— Script di compilazione con strumenti** ``` SEGMENT=$(python bin/xray_start.py) gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$? if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1 fi python bin/xray_success.py "$SEGMENT" ``` [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py), [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py) e [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py) sono semplici script Python che costruiscono oggetti segmenti, li convertono in documenti in formato JSON e li inviano al daemon su UDP. Se la build di Gradle fallisce, puoi trovare il messaggio di errore facendo clic sul **nodo scorekeep-build** nella mappa di traccia della console X-Ray. ![\[Diagram showing client connection to Scorekeep-build with average time of 14.6s and 0.07/min.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-servicemap-builderror.png) ![\[Timeline view showing Scorekeep-build process with 14.6 second duration and warning icon.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-timeline-builderror.png) ![\[Error message showing build failure due to missing ElasticBeanstalkPlugin symbol in RdsWebConfig class.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-exception-builderror.png) # Analisi di un client di app Web **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Nella [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito)filiale, Scorekeep utilizza Amazon Cognito per consentire agli utenti di creare un account e di accedere con esso per recuperare le informazioni utente da un pool di utenti Amazon Cognito. Quando un utente accede, Scorekeep utilizza un pool di identità Amazon Cognito per ottenere credenziali AWS temporanee da utilizzare con. AWS SDK per JavaScript Il pool di identità viene configurato per garantire agli utenti che accedono l'accesso in scrittura ai dati di tracciamento verso AWS X-Ray. L'applicazione web utilizza queste credenziali per registrare l'ID utente dell'utente cha ha eseguito l'accesso, il percorso del browser e la vista del client delle chiamate all'API di Scorekeep. La maggior parte del lavoro è effettuato in una classe denominata `xray`. Questa classe di servizio fornisce metodi per generare gli identificatori richiesti, creare segmenti in corso, finalizzare segmenti e inviare documenti di segmento all'API X-Ray. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js)— Registrazione e caricamento di segmenti** ``` ... service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24); var id = service.getHexId(16); var startTime = service.getEpochTime(); segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } }; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; } service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); } service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) } ``` Questi metodi sono chiamati nell'intestazione e nelle funzioni `transformResponse` nei servizi della risorsa che l'app web Scorekeep utilizza per chiamare l'API. Per includere il segmento client nella stessa traccia del segmento generato dall'API, l'app Web deve includere l'ID di traccia e l'ID del segmento in un'[intestazione di tracciamento](xray-concepts.md#xray-concepts-tracingheader) (`X-Amzn-Trace-Id`) leggibile dall'SDK X-Ray. Quando l'applicazione Java con strumentazione riceve una richiesta con questa intestazione, X-Ray SDK for Java utilizza lo stesso ID di traccia e rende il segmento del client dell'app Web il principale del segmento. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js)— Registrazione di segmenti per chiamate di risorse angolari e scrittura di intestazioni di tracciamento** ``` var module = angular.module('scorekeep'); module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {}, get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, }, ... ``` La mappa di traccia risultante include un nodo per il client dell'app Web. ![\[\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-servicemap-client.png) I tracciamenti che includono segmenti dall'app web mostrano l'URL che l'utente visualizza all'interno del browser (percorso che inizia con `/#/`). Senza l'analisi del client, ricevi solo l'URL dell'API della risorsa che l'app web chiama (percorsi che iniziano con `/api/`). ![\[\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-traces-client.png) # Utilizzo dei client analizzati nei thread worker **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Scorekeep utilizza un thread di lavoro per pubblicare una notifica su Amazon SNS quando un utente vince una partita. La pubblicazione della notifica richiede più tempo del resto delle operazioni di richiesta sommate e non ha effetto sul client o sull'utente. Pertanto, eseguire l'attività in modo asincrono è un buon modo per migliorare i tempi di risposta. Tuttavia, l'X-Ray SDK for Java non sa quale segmento era attivo al momento della creazione del thread. Di conseguenza, quando si tenta di utilizzare il AWS SDK per Java client strumentato all'interno del thread, viene generato un `SegmentNotFoundException` messaggio che blocca il thread. **Example Web-1.error.log** ``` Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) ... ``` Per risolvere questo problema, l'applicazione utilizza la funzione di `GetTraceEntity` ottenere un riferimento al segmento nel thread principale e `Entity.run()` di eseguire in sicurezza il codice del thread di lavoro con accesso al contesto del segmento. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70)— Passaggio del contesto di traccia a un thread di lavoro** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html); import [com.amazonaws.xray.entities.Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Entity segment = recorder.getTraceEntity(); Thread comm = new Thread() { public void run() { segment.run(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); } } ``` Poiché la richiesta è ora risolta prima della chiamata ad Amazon SNS, l'applicazione crea un sottosegmento separato per il thread. Ciò impedisce all'SDK X-Ray di chiudere il segmento prima di registrare la risposta da Amazon SNS. Se nessun sottosegmento è aperto quando Scorekeep ha risolto la richiesta, la risposta di Amazon SNS potrebbe andare persa. ![\[\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-workerthread.png) Per ulteriori informazioni sul multithreading, consulta [Passaggio del contesto del segmento tra thread in un'applicazione multithread](xray-sdk-java-multithreading.md).