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à.
# Utilizzo di Java
**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
Esistono due modi per strumentare un'applicazione Java per inviare tracce a X-Ray:
+ [AWS Distro for OpenTelemetry Java](xray-java-opentel-sdk.md): una AWS distribuzione che fornisce un set di librerie open source per l'invio di metriche e tracce correlate a più soluzioni di AWS monitoraggio, tra cui Amazon AWS X-Ray e Amazon OpenSearch Service CloudWatch, tramite [AWS Distro](https://aws-otel.github.io/docs/getting-started/collector) for Collector. OpenTelemetry
+ [AWS X-Ray SDK for](xray-sdk-java.md) [Java: un set di librerie per la generazione e l'invio di tracce a X-Ray tramite il demone X-Ray.](xray-daemon.md)
Per ulteriori informazioni, consulta [Scelta tra AWS Distro for OpenTelemetry e X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro per Java OpenTelemetry
Con AWS Distro for OpenTelemetry (ADOT) Java, puoi strumentare le tue applicazioni una sola volta e inviare metriche e tracce correlate a più AWS soluzioni di monitoraggio tra cui Amazon AWS X-Ray e Amazon CloudWatch Service. OpenSearch L'utilizzo di X-Ray con ADOT richiede due componenti: un *OpenTelemetry SDK* abilitato per l'uso con X-Ray e *AWS Distro for OpenTelemetry Collector* abilitato per l'uso con X-Ray. ADOT Java include il supporto per la strumentazione automatica, che consente all'applicazione di inviare tracce senza modifiche al codice.
Per iniziare, consultate la documentazione di [AWS Distro](https://aws-otel.github.io/docs/getting-started/java-sdk) for Java. OpenTelemetry
[Per ulteriori informazioni sull'utilizzo di AWS Distro for OpenTelemetry AWS X-Ray e altro Servizi AWS, consulta [AWS Distro for OpenTelemetry o Distro for Documentation](https://aws-otel.github.io/)AWS . OpenTelemetry ](https://aws-otel.github.io/docs/introduction)
[Per ulteriori informazioni sul supporto e l'utilizzo della lingua, vedere AWS Observability on. GitHub](https://github.com/aws-observability)
# AWS X-Ray SDK per Java
**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 è un insieme di librerie per applicazioni Web Java che forniscono classi e metodi per generare e inviare dati di traccia al demone X-Ray. I dati di traccia includono informazioni sulle richieste HTTP in entrata fornite dall'applicazione e sulle chiamate effettuate dall'applicazione ai servizi downstream utilizzando l' AWS SDK, i client HTTP o un connettore di database SQL. Puoi anche possibile creare manualmente dei segmenti e aggiungere informazioni di debug in annotazioni e metadati.
X-Ray SDK for Java è un progetto open source. [Puoi seguire il progetto e inviare problemi e richieste pull su GitHub: github. com/aws/aws- xray-sdk-java](https://github.com/aws/aws-xray-sdk-java)
Inizia [aggiungendo `AWSXRayServletFilter` come filtro del servlet](xray-sdk-java-filters.md) per tracciare le richieste in entrata. Un filtro servlet crea un [segmento](xray-concepts.md#xray-concepts-segments). Fino a che il segmento è aperto, puoi usare i metodi del client dell'SDK per aggiungere informazioni al segmento e creare sottosegmenti per tracciare le chiamate a valle. L'SDK, inoltre, registra automaticamente le eccezioni sollevate dall'applicazione per il tempo durante il quale il segmento è aperto.
A partire dalla versione 1.3, è possibile analizzare l'applicazione utilizzando il sistema [aspect-oriented programming (AOP) in Spring](xray-sdk-java-aop-spring.md). Ciò significa che è possibile strumentare l'applicazione mentre è in esecuzione AWS, senza aggiungere alcun codice al runtime dell'applicazione.
Successivamente, utilizzate l'SDK X-Ray per Java per strumentare AWS SDK per Java i vostri client [includendo il sottomodulo SDK Instrumentor nella](#xray-sdk-java-dependencies) configurazione di build. Ogni volta che effettui una chiamata a un downstream Servizio AWS o a una risorsa con un client strumentato, l'SDK registra le informazioni sulla chiamata in un sottosegmento. Servizi AWS e le risorse a cui accedi all'interno dei servizi vengono visualizzate come nodi a valle sulla mappa di traccia per aiutarti a identificare errori e problemi di limitazione sulle singole connessioni.
Se non vuoi strumentalizzare tutte le chiamate downstream Servizi AWS, puoi tralasciare il sottomodulo Instrumentor e scegliere quali client strumentare. Strumenta i singoli client [aggiungendo un](xray-sdk-java-awssdkclients.md) client di servizio `TracingHandler` SDK. AWS
Altri sottomoduli X-Ray SDK for Java forniscono la strumentazione per le chiamate downstream ai database HTTP Web e SQL. APIs È possibile [utilizzare le versioni X-Ray SDK for Java di `HTTPClient` e `HTTPClientBuilder`](xray-sdk-java-httpclients.md) nel sottomodulo HTTP Apache per strumentare i client HTTP Apache. Per analizzare le query SQL, [aggiungi lo strumento di intercettazione dell'SDK all'origine dei dati](xray-sdk-java-sqlclients.md).
Dopo aver iniziato a utilizzare l'SDK, personalizzane il comportamento [configurando](xray-sdk-java-configuration.md) il registratore e il filtro servlet. Puoi aggiungere dei plugin per memorizzare i dati sulle risorse di elaborazione sulle quali è eseguita la tua applicazione, personalizzare il comportamento di campionamento definendo regole di campionatura e impostare il livello di log per visualizzare più o meno informazioni generate dall'SDK nei log dell'applicazione.
Registra ulteriori informazioni sulle richieste e sull'attività svolta dalla tua applicazione in [annotazioni e metadati](xray-sdk-java-segment.md). Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con [espressioni filtro](xray-console-filters.md), in modo da poter cercare tracce che contengono dati specifici. Le immissioni di metadati sono meno restrittive e possono registrare interi oggetti e array, ovvero tutto ciò che può essere serializzato in JSON.
**Annotazioni e metadata**
Le annotazioni e i metadati sono testo arbitrario che aggiungi ai segmenti con X-Ray SDK. Le annotazioni vengono indicizzate per essere utilizzate con le espressioni di filtro. I metadati non sono indicizzati, ma possono essere visualizzati nel segmento non elaborato con la console X-Ray o l'API. Chiunque conceda l'accesso in lettura a X-Ray può visualizzare questi dati.
Quando disponi di una notevole quantità di client analizzati nel tuo codice, un singolo segmento per la richiesta può contenere molti sottosegmenti, uno per ciascuna delle chiamate effettuate con un client analizzato. Puoi organizzare e raggruppare i sottosegmenti inglobando le chiamate del client [sottosegmenti personalizzati](xray-sdk-java-subsegments.md). Puoi creare un sottosegmento personalizzato per un'intera funzione o qualsiasi porzione di codice, e memorizzare metadati e annotazioni sul sottosegmento invece di scrivere tutto all'interno del segmento padre.
## Sottomoduli
Puoi scaricare l'X-Ray SDK per Java da Maven. L'X-Ray SDK for Java è suddiviso in sottomoduli per caso d'uso, con una distinta dei materiali per la gestione delle versioni:
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/)(obbligatorio): funzionalità di base per la creazione e la trasmissione di segmenti. Include `AWSXRayServletFilter` per l'analisi delle richieste in entrata.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— Instruments: chiamate da Servizi AWS effettuare con AWS SDK per Java i clienti aggiungendo un client di tracciamento come gestore delle richieste.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— Chiamate Instruments Servizi AWS effettuate con client AWS SDK per Java 2.2 e versioni successive aggiungendo un client di tracciamento come intercettore delle richieste.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— Con`aws-xray-recorder-sdk-aws-sdk`, Instruments tutti i client vengono automaticamente. AWS SDK per Java
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— Con`aws-xray-recorder-sdk-aws-sdk-v2`, instruments tutti i client AWS SDK per Java 2.2 e versioni successive automaticamente.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/)— Chiamate HTTP in uscita di Instruments effettuate con client HTTP Apache.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/)— Fornisce intercettori per le applicazioni Spring AOP Framework.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/)— Instruments: chiamate in uscita a un database PostgreSQL realizzate con JDBC.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/)— Chiamate in uscita di Instruments a un database MySQL realizzate con JDBC.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/)— Fornisce una distinta dei materiali che è possibile utilizzare per specificare la versione da utilizzare per tutti i sottomoduli.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— Pubblica CloudWatch metriche Amazon non campionate dai segmenti X-Ray raccolti.
Se usi Maven o Gradle per creare la tua applicazione, aggiungi [l'X-Ray SDK for Java](#xray-sdk-java-dependencies) alla configurazione di build.
Per la documentazione di riferimento sulle classi e sui metodi dell'SDK, consulta [AWS X-Ray SDK for Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc) API Reference.
## Requisiti
L'X-Ray SDK per Java richiede Java 8 o versione successiva, Servlet API 3, l' AWS SDK e Jackson.
L'SDK dipende dalle seguenti librerie per la compilazione e il runtime:
+ AWS SDK for Java versione 1.11.398 o successiva
+ API Servlet 3.1.0
Queste dipendenze sono dichiarate nel file `pom.xml` dell'SDK e vengono automaticamente incluse se compili utilizzando Maven o Gradle.
Se si utilizza una libreria inclusa in X-Ray SDK for Java, è necessario utilizzare la versione inclusa. Ad esempio, se fai già affidamento su Jackson in fase di runtime e includi dei file JAR nella distribuzione per tale dipendenza, devi rimuovere i file JAR perché il JAR dell'SDK include le proprie versioni delle librerie Jackson.
## Gestione delle dipendenze
L'X-Ray SDK per Java è disponibile presso Maven:
+ **Gruppo —** `com.amazonaws`
+ **Artefatto** — `aws-xray-recorder-sdk-bom`
+ **Version** (Versione): `2.11.0`
Se utilizzi Maven per compilare l'applicazione, aggiungi l'SDK come dipendenza nel tuo file `pom.xml`.
**Example pom.xml - dipendenze**
```
com.amazonaws
aws-xray-recorder-sdk-bom
2.11.0
pom
import
com.amazonaws
aws-xray-recorder-sdk-core
com.amazonaws
aws-xray-recorder-sdk-apache-http
com.amazonaws
aws-xray-recorder-sdk-aws-sdk
com.amazonaws
aws-xray-recorder-sdk-aws-sdk-instrumentor
com.amazonaws
aws-xray-recorder-sdk-sql-postgres
com.amazonaws
aws-xray-recorder-sdk-sql-mysql
```
Nel caso di Gradle, aggiungi l'SDK come dipendenza in fase di compilazione nel tuo file `build.gradle`.
**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")
compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
testCompile("junit:junit:4.11")
}
dependencyManagement {
imports {
mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
}
}
```
Se utilizzi Elastic Beanstalk per distribuire la tua applicazione, puoi usare Maven o Gradle per creare su istanza ogni volta che esegui la distribuzione, invece di creare e caricare un archivio di grandi dimensioni che include tutte le tue dipendenze. Vedi [l'applicazione di esempio](xray-scorekeep.md) per un esempio che utilizza Gradle.
# AWS X-Ray agente di strumentazione automatica per Java
**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'agente di AWS X-Ray strumentazione automatica per Java è una soluzione di tracciamento che strumenta le applicazioni Web Java con uno sforzo di sviluppo minimo. L'agente consente il tracciamento per le applicazioni basate su servlet e tutte le richieste downstream dell'agente effettuate con framework e librerie supportati. Ciò include le richieste HTTP Apache downstream, le richieste AWS SDK e le query SQL eseguite utilizzando un driver JDBC. L'agente propaga il contesto X-Ray, inclusi tutti i segmenti e i sottosegmenti attivi, tra i thread. Tutte le configurazioni e la versatilità dell'SDK X-Ray sono ancora disponibili con l'agente Java. Sono state scelte impostazioni predefinite adeguate per garantire che l'agente funzioni con il minimo sforzo.
La soluzione X-Ray Agent è la soluzione ideale per server di applicazioni Web Java basati su servlet e richiesta-risposta. Se la tua applicazione utilizza un framework asincrono o non è ben modellata come servizio di richiesta-risposta, potresti prendere in considerazione la strumentazione manuale con l'SDK.
L'agente X-Ray è costruito utilizzando il toolkit Distributed Systems Comprehension, o Di. SCo Di SCo è un framework open source per la creazione di agenti Java che possono essere utilizzati in sistemi distribuiti. Sebbene non sia necessario conoscere Di SCo per utilizzare l'agente X-Ray, puoi saperne di più sul progetto visitando la sua [home page](https://github.com/awslabs/disco) all'indirizzo. GitHub L'agente X-Ray è inoltre completamente open source. [Per visualizzare il codice sorgente, contribuire o sollevare problemi sull'agente, visita il suo repository su. GitHub](https://github.com/aws/aws-xray-java-agent)
## Applicazione di esempio
L'applicazione [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)di esempio è adattata per essere strumentata con l'agente X-Ray. Questo ramo non contiene alcuna configurazione del filtro servlet o del registratore, poiché queste funzioni vengono eseguite dall'agente. Per eseguire l'applicazione localmente o utilizzando AWS le risorse, seguite i passaggi nel file readme dell'applicazione di esempio. Le istruzioni per utilizzare l'app di esempio per generare tracce X-Ray si trovano nel tutorial dell'[app di esempio](xray-scorekeep.md).
## Nozioni di base
Per iniziare a usare l'agente Java per la strumentazione automatica X-Ray nella tua applicazione, segui questi passaggi.
1. Esegui il demone X-Ray nel tuo ambiente. Per ulteriori informazioni, consulta [AWS X-Ray demone](xray-daemon.md).
1. Scarica la [distribuzione più recente dell'agente.](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip) Decomprimi l'archivio e annota la sua posizione nel file system. Il suo contenuto dovrebbe essere simile al seguente.
```
disco
├── disco-java-agent.jar
└── disco-plugins
├── aws-xray-agent-plugin.jar
├── disco-java-agent-aws-plugin.jar
├── disco-java-agent-sql-plugin.jar
└── disco-java-agent-web-plugin.jar
```
1. Modifica gli argomenti JVM dell'applicazione includendo quanto segue, che abilita l'agente. Assicuratevi che l'`-javaagent`argomento sia posto *prima dell'*`-jar`argomento, se applicabile. Il processo di modifica degli argomenti JVM varia a seconda degli strumenti e dei framework utilizzati per avviare il server Java. Consultate la documentazione del framework del vostro server per indicazioni specifiche.
```
-javaagent://disco-java-agent.jar=pluginPath=//disco-plugins
```
1. Per specificare la modalità di visualizzazione del nome dell'applicazione sulla console X-Ray, impostate la variabile di `AWS_XRAY_TRACING_NAME` ambiente o la proprietà di `com.amazonaws.xray.strategy.tracingName` sistema. Se non viene fornito alcun nome, viene utilizzato un nome predefinito.
1. Riavvia il server o il contenitore. Le richieste in arrivo e le relative chiamate a valle vengono ora tracciate. Se non vedi i risultati previsti, consulta. [Risoluzione dei problemi](#XRayAutoInstrumentationAgent-Troubleshooting)
## Configurazione
L'agente X-Ray è configurato da un file JSON esterno fornito dall'utente. Per impostazione predefinita, questo file si trova nella radice del percorso di classe dell'utente (ad esempio, nella sua directory) denominato. `resources` `xray-agent.json` È possibile configurare una posizione personalizzata per il file di configurazione impostando la proprietà `com.amazonaws.xray.configFile` system sul percorso assoluto del file di configurazione.
Di seguito viene mostrato un file di configurazione di esempio.
```
{
"serviceName": "XRayInstrumentedService",
"contextMissingStrategy": "LOG_ERROR",
"daemonAddress": "127.0.0.1:2000",
"tracingEnabled": true,
"samplingStrategy": "CENTRAL",
"traceIdInjectionPrefix": "prefix",
"samplingRulesManifest": "/path/to/manifest",
"awsServiceHandlerManifest": "/path/to/manifest",
"awsSdkVersion": 2,
"maxStackTraceLength": 50,
"streamingThreshold": 100,
"traceIdInjection": true,
"pluginsEnabled": true,
"collectSqlQueries": false
}
```
### Specificazione di configurazione
La tabella seguente descrive i valori validi per ogni proprietà. I nomi delle proprietà fanno distinzione tra maiuscole e minuscole, ma le relative chiavi no. Per le proprietà che possono essere sostituite dalle variabili di ambiente e dalle proprietà di sistema, l'ordine di priorità è sempre la variabile di ambiente, quindi la proprietà di sistema e quindi il file di configurazione. Per informazioni sulle proprietà che è possibile sostituire, vedere. [Variabili di ambiente](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) Tutti i campi sono facoltativi.
| Nome proprietà | Tipo | Valori validi | Description | Variabile di ambiente | Proprietà del sistema | Predefinita |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | Stringa | Qualsiasi stringa | Il nome del servizio strumentato così come verrà visualizzato nella console X-Ray. | AWS\$1XRAY\$1NOME\$1TRACCIAMENTO | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | Stringa | LOG\$1ERROR, IGNORE\$1ERROR | L'azione intrapresa dall'agente quando tenta di utilizzare il contesto del segmento X-Ray ma non è presente. | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\$1ERROR |
| Indirizzo del demone | Stringa | Indirizzo IP e porta formattati o elenco di indirizzi TCP e UDP | L'indirizzo utilizzato dall'agente per comunicare con il demone X-Ray. | AWS\$1XRAY\$1INDIRIZZO\$1DEMONE | indirizzo com.amazonaws.xray.emitter.daemon | 1270.0. 1:2000 |
| Tracciamento abilitato | Booleano | Vero, falso | Abilita la strumentazione da parte dell'agente X-Ray. | AWS\$1XRAY\$1TRACING\$1ENABLED | com.amazonaws.xray.tracingEnabled | TRUE |
| Strategia di campionamento | Stringa | CENTRALE, LOCALE, NESSUNO, TUTTO | La strategia di campionamento utilizzata dall'agente. ALL acquisisce tutte le richieste, NONE non acquisisce alcuna richiesta. Vedi le regole di [campionamento](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | N/D | N/D | CENTRALE |
| traceIdInjectionprefisso | Stringa | Qualsiasi stringa | Include il prefisso fornito prima della traccia IDs iniettata nei registri. | N/D | N/D | Nessuno (stringa vuota) |
| samplingRulesManifest | Stringa | Un percorso di file assoluto | Il percorso di un file di regole di campionamento personalizzato da utilizzare come origine delle regole di campionamento per la strategia di campionamento locale o delle regole di fallback per la strategia centrale. | N/D | N/D | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) |
| awsServiceHandlerManifesto | Stringa | Un percorso di file assoluto | Il percorso di un elenco di parametri consentiti personalizzato, che acquisisce informazioni aggiuntive dai client AWS SDK. | N/D | N/D | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) |
| awsSdkVersion | Numero intero | 1, 2 | Versione dell'[AWS SDK for](https://docs.aws.amazon.com/sdk-for-java/index.html) Java che stai utilizzando. Ignorata se non `awsServiceHandlerManifest` è impostata anche questa opzione. | N/D | N/D | 2 |
| maxStackTraceLunghezza | Numero intero | Numeri interi non negativi | Il numero massimo di righe di una traccia dello stack da registrare in una traccia. | N/D | N/D | 50 |
| StreamingThreshold | Numero intero | Numeri interi non negativi | Dopo aver chiuso almeno questo numero di sottosegmenti, questi vengono trasmessi in streaming al demone per evitare che i blocchi siano troppo out-of-band grandi. | N/D | N/D | 100 |
| traceIdInjection | Booleano | Vero, falso | Abilita l'iniezione di X-Ray Trace ID nei log se vengono aggiunte anche le dipendenze e la configurazione descritte nella configurazione [di registrazione](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging). Altrimenti, non fa nulla. | N/D | N/D | TRUE |
| Plugin abilitati | Booleano | Vero, falso | Abilita i plugin che registrano i metadati sugli AWS ambienti in cui operi. [Vedi i plugin.](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins) | N/D | N/D | TRUE |
| collectSqlQueries | Booleano | Vero, falso | Registra al meglio le stringhe di query SQL nei sottosegmenti SQL. | N/D | N/D | FALSE |
| Propagazione del contesto | Booleano | Vero, falso | Se vero, propaga automaticamente il contesto X-Ray tra i thread. Altrimenti, utilizza Thread Local per memorizzare il contesto ed è necessaria la propagazione manuale tra i thread. | N/D | N/D | TRUE |
### Configurazione della registrazione
Il livello di registro dell'agente X-Ray può essere configurato allo stesso modo dell'X-Ray SDK for Java. [Registrazione dei log](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)Per ulteriori informazioni sulla configurazione della registrazione con X-Ray SDK for Java, vedere.
### Strumentazione manuale
Se desideri eseguire la strumentazione manuale oltre alla strumentazione automatica dell'agente, aggiungi l'SDK X-Ray come dipendenza dal tuo progetto. Tieni presente che i filtri servlet personalizzati dell'SDK menzionati in [Tracing Incoming Requests](xray-sdk-java-filters.md) non sono compatibili con l'agente X-Ray.
**Nota**
È necessario utilizzare la versione più recente di X-Ray SDK per eseguire la strumentazione manuale utilizzando anche l'agente.
Se stai lavorando a un progetto Maven, aggiungi le seguenti dipendenze al tuo file. `pom.xml`
```
com.amazonaws
aws-xray-recorder-sdk-core
2.11.0
```
Se stai lavorando su un progetto Gradle, aggiungi le seguenti dipendenze al tuo file. `build.gradle`
```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'
```
Puoi aggiungere [sottosegmenti personalizzati](xray-sdk-java-subsegments.md) oltre alle [annotazioni, ai metadati e all'utente IDs durante l'utilizzo dell'agente,](xray-sdk-java-segment.md) proprio come faresti con il normale SDK. L'agente propaga automaticamente il contesto tra i thread, quindi non dovrebbero essere necessarie soluzioni alternative per propagare il contesto quando si lavora con applicazioni multithread.
## Risoluzione dei problemi
Poiché l'agente offre una strumentazione completamente automatica, può essere difficile identificare la causa principale di un problema quando si verificano problemi. Se l'agente X-Ray non funziona come previsto, esamina i seguenti problemi e soluzioni. L'agente X-Ray e l'SDK utilizzano Jakarta Commons Logging (JCL). Per visualizzare l'output di registrazione, assicurati che un bridge che collega JCL al tuo backend di registrazione si trovi sul classpath, come nell'esempio seguente: o. `log4j-jcl` `jcl-over-slf4j`
### Problema: ho abilitato l'agente Java sulla mia applicazione ma non vedo nulla sulla console X-Ray
**Il demone X-Ray è in esecuzione sulla stessa macchina?**
In caso contrario, consultate la [documentazione del demone X-Ray per configurarlo](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html).
**Nei registri delle applicazioni, viene visualizzato un messaggio del tipo «Inizializzazione del registratore dell'agente X-Ray»?**
Se l'agente è stato aggiunto correttamente all'applicazione, questo messaggio viene registrato a livello INFO all'avvio dell'applicazione, prima che inizi a ricevere le richieste. Se questo messaggio non è presente, l'agente Java non è in esecuzione con il processo Java. Assicurati di aver seguito correttamente tutti i passaggi di configurazione senza errori di battitura.
**Nei registri delle applicazioni, vedi diversi messaggi di errore che dicono qualcosa come «Soppressione dell'eccezione mancante AWS X-Ray nel contesto»?**
Questi errori si verificano perché l'agente sta cercando di strumentare le richieste a valle, come le richieste AWS SDK o le query SQL, ma non è riuscito a creare automaticamente un segmento. Se riscontri molti di questi errori, l'agente potrebbe non essere lo strumento migliore per il tuo caso d'uso e potresti prendere in considerazione la strumentazione manuale con X-Ray SDK. In alternativa, puoi abilitare i [log di debug di X-Ray SDK per visualizzare la traccia dello stack in cui si verificano le eccezioni mancanti](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) nel contesto. Puoi racchiudere queste parti del codice con segmenti personalizzati, che dovrebbero risolvere questi errori. [Per un esempio di avvolgimento delle richieste downstream con segmenti personalizzati, consulta il codice di esempio in Strumenting Startup Code.](scorekeep-startup.md)
### Problema: alcuni segmenti che prevedo non vengono visualizzati sulla console X-Ray
**La tua applicazione utilizza il multithreading?**
Se alcuni segmenti che prevedi di creare non vengono visualizzati nella console, la causa potrebbe essere la presenza di thread in background nell'applicazione. Se la tua applicazione esegue attività utilizzando thread in background che sono «spara e dimentica», come effettuare una chiamata una tantum a una funzione Lambda con l' AWS SDK o eseguire periodicamente il polling di alcuni endpoint HTTP, ciò potrebbe confondere l'agente mentre propaga il contesto tra i thread. Per verificare che questo sia il problema, abilita i log di debug di X-Ray SDK e verifica la presenza di messaggi come: *Non emettere segmenti denominati in quanto generano i sottosegmenti* in corso. Per ovviare a questo problema, puoi provare a unire i thread in background prima che il server ritorni, per assicurarti che tutto il lavoro svolto in essi venga registrato. In alternativa, puoi impostare la `contextPropagation` configurazione dell'agente in modo da `false` disabilitare la propagazione del contesto nei thread in background. Se lo fai, dovrai strumentare manualmente quei thread con segmenti personalizzati o ignorare le eccezioni mancanti nel contesto che generano.
**Hai impostato delle regole di campionamento?**
Se sulla console X-Ray compaiono segmenti apparentemente casuali o inaspettati, o se i segmenti che si prevede siano presenti sulla console non lo sono, è possibile che si tratti di un problema di campionamento. L'agente X-Ray applica il campionamento centralizzato a tutti i segmenti che crea, utilizzando le regole della console X-Ray. La regola predefinita prevede il campionamento di 1 segmento al secondo, più il 5% dei segmenti che vengono successivamente campionati. Ciò significa che i segmenti creati rapidamente con l'agente potrebbero non essere campionati. Per risolvere questo problema, è necessario creare regole di campionamento personalizzate sulla console X-Ray che campionino in modo appropriato i segmenti desiderati. [Per ulteriori informazioni, vedere campionamento.](xray-console-sampling.md)
# Configurazione dell'X-Ray SDK per Java
**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 include una classe denominata `AWSXRay` che fornisce il registratore globale. Questo è un `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.
**Topics**
+ [Plugin di servizio](#xray-sdk-java-configuration-plugins)
+ [Regole di campionamento](#xray-sdk-java-configuration-sampling)
+ [Registrazione dei log](#xray-sdk-java-configuration-logging)
+ [Listener di segmenti](#xray-sdk-java-configuration-listeners)
+ [Variabili di ambiente](#xray-sdk-java-configuration-envvars)
+ [Proprietà di sistema](#xray-sdk-java-configuration-sysprops)
## Plugin di servizio
`plugins`Utilizzatelo per registrare informazioni sul servizio che ospita l'applicazione.
**Plugin**
+ Amazon EC2: `EC2Plugin` aggiunge l'ID dell'istanza, la zona di disponibilità e il gruppo di CloudWatch log.
+ Elastic `ElasticBeanstalkPlugin` Beanstalk: aggiunge il nome dell'ambiente, l'etichetta della versione e l'ID di distribuzione.
+ Amazon ECS: `ECSPlugin` aggiunge l'ID del contenitore.
+ Amazon EKS: `EKSPlugin` aggiunge l'ID del contenitore, il nome del cluster, l'ID del pod e il gruppo CloudWatch Logs.
![\[Segmenta i dati delle risorse con i plug-in Amazon EC2 ed Elastic Beanstalk.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png)
Per usare un plugin, chiama `withPlugin` sul tuo `AWSXRayRecorderBuilder`.
**Example src/main/java/scorekeep/WebConfig.java - registratore**
```
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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
L'SDK utilizza anche le impostazioni del plug-in per impostare il `origin` campo sul segmento. Indica il tipo di AWS risorsa che esegue l'applicazione. Quando utilizzi più plugin, l'SDK utilizza il seguente ordine di risoluzione per determinare l'origine: ElasticBeanstalk > EKS > ECS > EC2.
## Regole di campionamento
L'SDK utilizza le regole di campionamento definite nella console X-Ray per determinare quali richieste registrare. La regola predefinita tiene traccia della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive su tutti i servizi che inviano tracce a X-Ray. [Crea regole aggiuntive nella console X-Ray](xray-console-sampling.md) per personalizzare la quantità di dati registrati per ciascuna delle tue applicazioni.
L'SDK applica le regole personalizzate nell'ordine in cui sono definite. Se una richiesta corrisponde a più regole personalizzate, l'SDK applica solo la prima regola.
**Nota**
Se l'SDK non riesce a contattare X-Ray per ottenere le regole di campionamento, torna a una regola locale predefinita della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive per host. Ciò può verificarsi se l'host non dispone dell'autorizzazione per chiamare sampling APIs o non riesce a connettersi al demone X-Ray, che funge da proxy TCP per le chiamate API effettuate dall'SDK.
Puoi anche configurare l'SDK per caricare le regole di campionamento da un documento JSON. L'SDK può utilizzare le regole locali come backup per i casi in cui il campionamento a raggi X non è disponibile o utilizzare esclusivamente regole locali.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
Questo esempio definisce una regola personalizzata e una regola predefinita. La regola personalizzata applica una frequenza di campionamento del cinque percento senza alcun numero minimo di richieste da tracciare per i percorsi. `/api/move/` La regola predefinita tiene traccia della prima richiesta ogni secondo e del 10% delle richieste aggiuntive.
Lo svantaggio della definizione locale delle regole è che l'obiettivo fisso viene applicato da ciascuna istanza del registratore in modo indipendente, anziché essere gestito dal servizio X-Ray. Man mano che si installano più host, la tariffa fissa si moltiplica, rendendo più difficile il controllo della quantità di dati registrati.
Sì AWS Lambda, non è possibile modificare la frequenza di campionamento. Se la funzione viene chiamata da un servizio strumentato, le chiamate che hanno generato richieste campionate da quel servizio verranno registrate da Lambda. Se il tracciamento attivo è abilitato e non è presente alcuna intestazione di tracciamento, Lambda prende la decisione di campionamento.
Per fornire le regole di backup in Spring, configura il registratore globale con un codice `CentralizedSamplingStrategy` in una classe di configurazione:
**Example src/main/java/myapp/WebConfig.java - configurazione del registratore**
```
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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
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);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
```
Per Tomcat, aggiungi un listener che estenda `ServletContextListener` e registra il listener nel descrittore della distribuzione.
**Example src/com/myapp/web/Startup.java**
```
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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent event) {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
@Override
public void contextDestroyed(ServletContextEvent event) { }
}
```
**Example WEB-INF/web.xml**
```
...
com.myapp.web.Startup
```
Per utilizzare solo regole locali, sostituisci `CentralizedSamplingStrategy` con una `LocalizedSamplingStrategy`.
```
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
```
## Registrazione dei log
Per impostazione predefinita, l'SDK invia messaggi a `ERROR` livello di file nei log delle applicazioni. È possibile abilitare la registrazione a livello di debug sull'SDK per generare log più dettagliati nel file di registro dell'applicazione. I livelli di registro validi sono`DEBUG`,,, e. `INFO` `WARN` `ERROR` `FATAL` `FATAL`il livello di registro silenzia tutti i messaggi di registro perché l'SDK non esegue la registrazione a un livello irreversibile.
**Example application.properties**
Imposta il livello di log tramite la proprietà `logging.level.com.amazonaws.xray`.
```
logging.level.com.amazonaws.xray = DEBUG
```
Utilizza i log di debug per identificare i problemi, come ad esempio dei sottosegmenti non chiusi, quando [generi dei sottosegmenti manualmente](xray-sdk-java-subsegments.md).
### Inserimento dell’ID di tracciamento nei log
Per esporre l'ID di tracciamento completo corrente alle istruzioni di log, puoi inserire l'ID nel contesto diagnostico mappato (MDC). Utilizzando l'interfaccia `SegmentListener`, i metodi vengono chiamati dal registratore di X-Ray durante gli eventi del ciclo di vita del segmento. Quando inizia un segmento o un sottosegmento, l'ID di traccia qualificato viene inserito nell'MDC con la chiave `AWS-XRAY-TRACE-ID`. Quando tale segmento termina, la chiave viene rimossa dall'MDC. Questo espone l'ID di tracciamento alla libreria di registrazione in uso. Quando un sottosegmento termina, il relativo ID padre viene inserito nell'MDC.
**Example ID di tracciamento completo**
L'ID completo è rappresentato come `TraceID@EntityID`
```
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3
```
Questa funzionalità funziona con le applicazioni Java dotate di AWS X-Ray SDK for Java e supporta le seguenti configurazioni di registrazione:
+ SLF4API front-end J con backend Logback
+ SLF4API front-end J con backend Log4J2
+ API front-end Log4J2 con backend Log4J2
Consulta le seguenti schede per le esigenze di ogni front-end e ogni back-end.
------
#### [ SLF4J Frontend ]
1. Aggiungi la seguente dipendenza Maven al tuo progetto.
```
com.amazonaws
aws-xray-recorder-sdk-slf4j
2.11.0
```
1. Includi il metodo `withSegmentListener` durante la costruzione di `AWSXRayRecorder`. Questo aggiunge una `SegmentListener` classe, che inserisce automaticamente una nuova traccia nel J MDC. IDs SLF4
`SegmentListener` accetta una stringa facoltativa come parametro per configurare il prefisso dell'istruzione di log. Il prefisso può essere configurato nei seguenti modi:
+ **Nessuno**: utilizza il prefisso predefinito`AWS-XRAY-TRACE-ID`.
+ **Vuoto**: utilizza una stringa vuota (ad esempio`""`).
+ **Personalizzato**: utilizza un prefisso personalizzato come definito nella stringa.
**Example Dichiarazione `AWSXRayRecorderBuilder`**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Log4J2 front end ]
1. Aggiungi la seguente dipendenza Maven al tuo progetto.
```
com.amazonaws
aws-xray-recorder-sdk-log4j
2.11.0
```
1. Includi il metodo `withSegmentListener` durante la costruzione di `AWSXRayRecorder`. Ciò aggiungerà una `SegmentListener` classe che inietta automaticamente una nuova traccia completamente qualificata IDs nel SLF4 J MDC.
`SegmentListener` accetta una stringa facoltativa come parametro per configurare il prefisso dell'istruzione di log. Il prefisso può essere configurato nei seguenti modi:
+ **Nessuno**: utilizza il prefisso predefinito`AWS-XRAY-TRACE-ID`.
+ **Vuoto**: utilizza una stringa vuota (ad esempio`""`) e rimuove il prefisso.
+ **Personalizzato**: utilizza il prefisso personalizzato definito nella stringa.
**Example Dichiarazione `AWSXRayRecorderBuilder`**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Logback backend ]
Per inserire l'ID di tracciamento negli eventi di registro, è necessario modificare il logger `PatternLayout`, che formatta ogni istruzione di registrazione.
1. Trova dove è configurato `patternLayout`. Puoi farlo a livello di codice o tramite un file di configurazione XML. Per ulteriori informazioni, consulta [configurazione di Logback](http://logback.qos.ch/manual/configuration.html).
1. Inserisci `%X{AWS-XRAY-TRACE-ID}` in punto qualsiasi di `patternLayout` per inserire l'ID di tracciamento nelle istruzioni di registrazione future. `%X{}` indica che si sta recuperando un valore con la chiave fornita dall’MDC. Per ulteriori informazioni su PatternLayouts Logback, consulta. [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout)
------
#### [ Log4J2 backend ]
1. Trova dove è configurato `patternLayout`. Puoi eseguire questa operazione a livello di codice o tramite un file di configurazione scritto in formato XML, JSON, YAML o proprietà.
Per ulteriori informazioni sulla configurazione di Log4J2 tramite un file di configurazione, consulta [Configurazione](https://logging.apache.org/log4j/2.x/manual/configuration.html).
Per ulteriori informazioni sulla configurazione di Log4J2 a livello di codice, consulta [Configurazione programmatica](https://logging.apache.org/log4j/2.x/manual/customconfig.html).
1. Inserisci `%X{AWS-XRAY-TRACE-ID}` in punto qualsiasi di `PatternLayout` per inserire l'ID di tracciamento nelle istruzioni di registrazione future. `%X{}` indica che si sta recuperando un valore con la chiave fornita dall’MDC. [Per ulteriori informazioni su PatternLayouts Log4J2, vedi Pattern Layout.](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout)
------
**Esempio di inserimento dell’ID di tracciamento**
Di seguito viene mostrata una stringa `PatternLayout` modificata per includere l'ID di tracciamento. L'ID di tracciamento viene stampato dopo il nome del thread (`%t`) e prima del livello di log (`%-5p`).
**Example `PatternLayout` con inserimento dell’ID**
```
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n
```
AWS X-Ray stampa automaticamente la chiave e l'ID di traccia nell'istruzione di registro per una facile analisi. Di seguito viene illustrata un'istruzione log utilizzando la modifica `PatternLayout`.
**Example Istruzione log con inserimento dell’ID**
```
2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here
```
Il messaggio di registrazione stesso è alloggiato nel modello `%m` e viene impostato quando si chiama il logger.
## Listener di segmenti
I segment listener sono un'interfaccia per intercettare eventi del ciclo di vita come l'inizio e la fine dei segmenti prodotti da. `AWSXRayRecorder` L'implementazione di una funzione evento listener di segmenti potrebbe essere quella di aggiungere la stessa annotazione a tutti i sottosegmenti quando vengono creati con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-), registrare un messaggio dopo che ogni segmento è stato inviato al daemon utilizzando [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-), o per registrare le query inviate dagli intercettori SQL che utilizzano [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) per verificare se il sottosegmento rappresenta una query SQL e, in tal caso, aggiungendo ulteriori metadati.
Per visualizzare l'elenco completo delle `SegmentListener` funzioni, consulta la documentazione dell'API [AWS X-Ray Recorder SDK for](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html) Java.
Nell'esempio seguente viene illustrato come aggiungere un'annotazione coerente a tutti i sottosegmenti durante la creazione con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) e per stampare un messaggio di log alla fine di ogni segmento con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-).
**Example MySegmentListener.java**
```
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;
public class MySegmentListener implements SegmentListener {
.....
@Override
public void onBeginSubsegment(Subsegment subsegment) {
subsegment.putAnnotation("annotationKey", "annotationValue");
}
@Override
public void afterEndSegment(Segment segment) {
// Be mindful not to mutate the segment
logger.info("Segment with ID " + segment.getId());
}
}
```
Durante la creazione di `AWSXRayRecorder`, viene fatto quindi riferimento a questo listener.
**Example AWSXRayRecorderBuilder dichiarazione**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new MySegmentListener());
```
## Variabili di ambiente
È possibile utilizzare le variabili di ambiente per configurare l'X-Ray SDK for Java. L'SDK supporta le seguenti variabili.
+ `AWS_XRAY_CONTEXT_MISSING`— Imposta per `RUNTIME_ERROR` generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.
**Valori validi**
+ `RUNTIME_ERROR`— Genera un'eccezione di runtime.
+ `LOG_ERROR`— Registra un errore e continua (impostazione predefinita).
+ `IGNORE_ERROR`— Ignora l'errore e continua.
Gli errori relativi a segmenti o sottosegmenti mancanti possono verificarsi quando si tenta di utilizzare un client con strumenti nel codice di avvio che viene eseguito quando non è aperta alcuna richiesta o nel codice che genera un nuovo thread.
+ `AWS_XRAY_DAEMON_ADDRESS`— Imposta l'host e la porta del demone X-Ray. Per impostazione predefinita, l'SDK utilizza `127.0.0.1:2000` sia i dati di traccia (UDP) che il campionamento (TCP). Utilizzate questa variabile se avete configurato il demone per l'[ascolto su una porta diversa](xray-daemon-configuration.md) o se è in esecuzione su un host diverso.
**Formato**
+ **Stessa porta** — `address:port`
+ **Porte diverse**: `tcp:address:port udp:address:port`
+ `AWS_LOG_GROUP`— Imposta il nome di un gruppo di log sul gruppo di log associato all'applicazione. Se il gruppo di log utilizza lo stesso AWS account e la stessa regione dell'applicazione, X-Ray cercherà automaticamente i dati del segmento dell'applicazione utilizzando questo gruppo di log specificato. Per ulteriori informazioni sui gruppi di log, consulta [Lavorare con gruppi di log e flussi](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
+ `AWS_XRAY_TRACING_NAME`— Imposta un nome di servizio che l'SDK utilizza per i segmenti. Sostituisce il nome del servizio impostato sulla [strategia di denominazione dei segmenti](xray-sdk-java-filters.md#xray-sdk-java-filters-naming) del filtro servlet.
Le variabili di ambiente sostituiscono i valori equivalenti per le [proprietà di sistema](#xray-sdk-java-configuration-sysprops) e i valori impostati nel codice.
## Proprietà di sistema
Puoi utilizzare le proprietà del sistema come alternativa alle [variabili d'ambiente](#xray-sdk-java-configuration-envvars) per una specifica JVM. L'SDK supporta le seguenti proprietà.
+ `com.amazonaws.xray.strategy.tracingName`— Equivalente a. `AWS_XRAY_TRACING_NAME`
+ `com.amazonaws.xray.emitters.daemonAddress`— Equivalente a`AWS_XRAY_DAEMON_ADDRESS`.
+ `com.amazonaws.xray.strategy.contextMissingStrategy`— Equivalente a`AWS_XRAY_CONTEXT_MISSING`.
Se sono impostate sia una proprietà di sistema che la variabili di ambiente equivalente, sono utilizzati i valori della variabile di ambiente. Entrambi i metodi sostituiscono i valori impostati nel codice.
# Tracciamento delle richieste in arrivo con X-Ray SDK for Java
**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 utilizzare l'SDK X-Ray per tracciare le richieste HTTP in entrata che la tua applicazione serve su un'istanza EC2 in Amazon EC2 o Amazon ECS. AWS Elastic Beanstalk
Utilizza un `Filter` per analizzare le richieste HTTP in entrata. Quando aggiungete il filtro servlet X-Ray all'applicazione, l'X-Ray SDK for Java crea un segmento per ogni richiesta campionata. Questo segmento include durata, metodo e conclusione della richiesta HTTP. Analisi ulteriori creano sottosegmenti associati a questo segmento.
**Nota**
Per quanto riguarda AWS Lambda le funzioni, Lambda crea un segmento per ogni richiesta campionata. Per ulteriori informazioni, consulta [AWS Lambda e AWS X-Ray](xray-services-lambda.md).
Ogni segmento ha un nome che identifica l'applicazione nella mappa dei servizi. Il segmento può essere denominato staticamente oppure è possibile configurare l'SDK per denominarlo dinamicamente in base all'intestazione dell'host nella richiesta in entrata. La denominazione dinamica consente di raggruppare le tracce in base al nome di dominio nella richiesta e di applicare un nome predefinito se il nome non corrisponde a uno schema previsto (ad esempio, se l'intestazione dell'host è falsificata).
**Richieste inoltrate**
Se un sistema di bilanciamento del carico o un altro intermediario inoltra una richiesta all'applicazione, X-Ray prende l'IP del client dall'`X-Forwarded-For`intestazione della richiesta anziché dall'IP di origine nel pacchetto IP. L'IP del client registrato per una richiesta inoltrata può essere falsificato, quindi non dovrebbe essere considerato attendibile.
Quando viene inoltrata una richiesta, l'SDK imposta un campo aggiuntivo nel segmento per indicarlo. Se il segmento contiene il campo `x_forwarded_for` impostato su`true`, l'IP del client è stato preso dall'`X-Forwarded-For`intestazione della richiesta HTTP.
Il gestore dei messaggi crea un segmento per ogni richiesta in entrata con un blocco `http` che contiene le informazioni riportate qui di seguito:
+ **Metodo HTTP**: GET, POST, PUT, DELETE, ecc.
+ **Indirizzo client**: l'indirizzo IP del client che ha inviato la richiesta.
+ **Codice di risposta**: il codice di risposta HTTP per la richiesta completata.
+ **Tempistica**: l'ora di inizio (quando è stata ricevuta la richiesta) e l'ora di fine (quando è stata inviata la risposta).
+ **Agente utente**: il `user-agent` codice della richiesta.
+ **Lunghezza del contenuto**: il `content-length` risultato della risposta.
**Topics**
+ [Aggiunta di un filtro di tracciamento all'applicazione (Tomcat)](#xray-sdk-java-filters-tomcat)
+ [Aggiunta di un filtro di tracciamento all'applicazione (Spring)](#xray-sdk-java-filters-spring)
+ [Configurazione di una strategia di denominazione dei segmenti](#xray-sdk-java-filters-naming)
## Aggiunta di un filtro di tracciamento all'applicazione (Tomcat)
Per Tomcat, aggiungere un `` al file `web.xml` del progetto. Utilizza il parametro `fixedName` per specificare un [nome di servizio](#xray-sdk-java-filters-naming) da applicare ai segmenti creati per le richieste in entrata.
**Example WEB-INF/web.xml - Tomcat**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
fixedName
MyApp
AWSXRayServletFilter
*
```
## Aggiunta di un filtro di tracciamento all'applicazione (Spring)
Per Spring, aggiungere un `Filter` alla classe `WebConfig`. Passare il nome del segmento al costruttore [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) come valore di tipo stringa.
**Example src/main/java/myapp/WebConfig.java - primavera**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
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");
}
}
```
## Configurazione di una strategia di denominazione dei segmenti
AWS X-Ray utilizza un *nome di servizio* per identificare l'applicazione e distinguerla dalle altre applicazioni, database, risorse esterne APIs e AWS risorse utilizzate dall'applicazione. [Quando X-Ray SDK genera segmenti per le richieste in entrata, registra il nome del servizio dell'applicazione nel campo del nome del segmento.](xray-api-segmentdocuments.md#api-segmentdocuments-fields)
L'X-Ray SDK può denominare i segmenti dopo il nome host nell'intestazione della richiesta HTTP. Tuttavia, questa intestazione può essere falsificata, il che potrebbe causare nodi imprevisti nella mappa dei servizi. Per evitare che l'SDK nomini i segmenti in modo errato a causa di richieste con intestazioni host contraffatte, è necessario specificare un nome predefinito per le richieste in entrata.
Se la tua applicazione soddisfa le richieste per più domini, puoi configurare l'SDK in modo che utilizzi una strategia di denominazione dinamica che rifletta questo aspetto nei nomi dei segmenti. Una strategia di denominazione dinamica consente all'SDK di utilizzare il nome host per le richieste che corrispondono a uno schema previsto e di applicare il nome predefinito alle richieste che non lo fanno.
Ad esempio, potresti avere una singola applicazione che serve le richieste a tre sottodomini:, e. `www.example.com` `api.example.com` `static.example.com` È possibile utilizzare una strategia di denominazione dinamica con lo schema `*.example.com` per identificare i segmenti per ogni sottodominio con un nome diverso, ottenendo tre nodi di servizio sulla mappa dei servizi. Se l'applicazione riceve richieste con un nome host che non corrisponde allo schema, sulla mappa dei servizi verrà visualizzato un quarto nodo con un nome di fallback specificato dall'utente.
Per utilizzare lo stesso nome per tutti i segmenti della richiesta, specifica il nome della tua applicazione quando inizializzi il filtro servlet, come illustrato nella [sezione precedente](#xray-sdk-java-filters-tomcat). Ciò ha lo stesso effetto della creazione di una correzione [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)chiamandola `SegmentNamingStrategy.fixed()` e passandola al [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)costruttore.
**Nota**
È possibile sovrascrivere il nome di servizio predefinito definito nel codice con la variabile di `AWS_XRAY_TRACING_NAME` [ambiente](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars).
Una strategia di denominazione dinamica definisce un modello al quale devono corrispondere i nomi degli host e un nome di default per l'utilizzo qualora il nome dell'host nella richiesta HTTP non corrisponda al modello. Per denominare segmenti in modo dinamico in Tomcat, utilizzare la `dynamicNamingRecognizedHosts` e `dynamicNamingFallbackName` per definire rispettivamente i modelli e il nome di default.
**Example WEB-INF/web.xml - Filtro Servlet con assegnazione dinamica dei nomi**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
dynamicNamingRecognizedHosts
*.example.com
dynamicNamingFallbackName
MyApp
AWSXRayServletFilter
*
```
Per Spring, crea una dinamica [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)`SegmentNamingStrategy.dynamic()`chiamando e passala al `AWSXRayServletFilter` costruttore.
**Example src/main/java/myapp/WebConfig.java - filtro servlet con denominazione dinamica**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
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);
import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com"));
}
}
```
# Tracciamento delle chiamate AWS SDK con X-Ray SDK for Java
**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
[Quando l'applicazione effettua chiamate per Servizi AWS archiviare dati, scrivere in una coda o inviare notifiche, X-Ray SDK for Java tiene traccia delle chiamate downstream in sottosegmenti.](xray-sdk-java-subsegments.md) Le risorse tracciate Servizi AWS e a cui accedi all'interno di tali servizi (ad esempio, un bucket Amazon S3 o una coda Amazon SQS) vengono visualizzate come nodi downstream sulla mappa di traccia nella console X-Ray.
[L'SDK X-Ray per Java strumenta automaticamente tutti i client SDK AWS quando includi i sottomoduli `aws-sdk` e un `aws-sdk-instrumentor` nella build.](xray-sdk-java.md#xray-sdk-java-submodules) Se non includi il modulo Instrumentor, puoi scegliere di analizzare alcuni client escludendo gli altri.
Per strumentare i singoli client, rimuovi il `aws-sdk-instrumentor` sottomodulo dalla build e aggiungi un client `XRayClient` as a `TracingHandler` sul tuo AWS SDK utilizzando il client builder del servizio.
Ad esempio, per analizzare un client `AmazonDynamoDB`, passa un gestore del tracciamento `AmazonDynamoDBClientBuilder`.
**Example MyModel.java - Client DynamoDB**
```
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 MyModel {
private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.fromName(System.getenv("AWS_REGION")))
.withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
.build();
...
```
Per tutti i servizi, puoi vedere il nome dell'API richiamata nella console X-Ray. Per un sottoinsieme di servizi, l'SDK X-Ray aggiunge informazioni al segmento per fornire una maggiore granularità nella mappa dei servizi.
Ad esempio, quando si effettua una chiamata con un client DynamoDB con strumentazione, l'SDK aggiunge il nome della tabella al segmento per le chiamate destinate a una tabella. Nella console, ogni tabella appare come un nodo separato nella mappa dei servizi, con un nodo DynamoDB generico per le chiamate che non hanno come destinazione una tabella.
**Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Quando si accede alle risorse con nome, le chiamate ai seguenti servizi creano ulteriori nodi della mappa del servizio. Le chiamate che non sono hanno come obiettivo risorse specifiche creano un nodo generico per il servizio.
+ **Amazon DynamoDB**: nome della tabella
+ **Amazon Simple Storage Service**: nome del bucket e della chiave
+ **Amazon Simple Queue Service**: nome della coda
Per strumentare le chiamate downstream a Servizi AWS with AWS SDK per Java 2.2 e versioni successive, puoi omettere il `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` modulo dalla configurazione di build. Al suo posto, includi il `aws-xray-recorder-sdk-aws-sdk-v2 module`, quindi analizza i singoli client configurandoli con un `TracingInterceptor`.
**Example AWS SDK per Java 2.2 e versioni successive - tracing interceptor**
```
import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...
```
# Tracciamento delle chiamate ai servizi Web HTTP downstream con X-Ray SDK for Java
**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
Quando l'applicazione effettua chiamate a microservizi o a HTTP pubblico APIs, è possibile utilizzare la versione `HttpClient` di X-Ray SDK per Java per strumentare tali chiamate e aggiungere l'API al service graph come servizio downstream.
L'X-Ray SDK for Java include `DefaultHttpClient` `HttpClientBuilder` classi che possono essere utilizzate al posto degli HttpComponents equivalenti di Apache per strumentare le chiamate HTTP in uscita.
+ `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient`
+ `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder`
Queste librerie sono contenute nel sottomodulo [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md).
È possibile sostituire le istruzioni di importazione esistenti con l'equivalente X-Ray di Instrument all client o utilizzare il nome completo quando si inizializza un client su client specifici dello strumento.
**Example HttpClientBuilder**
```
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
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://names.example.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();
}
}
```
Quando si effettua una chiamata a un'API Web downstream, l'X-Ray SDK for Java registra un sottosegmento con informazioni sulla richiesta e sulla risposta HTTP. X-Ray utilizza il sottosegmento per generare un segmento dedotto per l'API remota.
**Example Sottosegmento per una chiamata HTTP a valle**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento dedotto per una chiamata HTTP a valle**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Tracciamento delle query SQL con X-Ray SDK for Java
**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
## Interceptori SQL
Strumenta le query del database SQL aggiungendo l'interceptor JDBC X-Ray SDK for Java alla configurazione dell'origine dati.
+ **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor`
+ **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor`
Questi collettori si trovano rispettivamente nei [sottomoduli `aws-xray-recorder-sql-postgres` e `aws-xray-recorder-sql-mysql`](xray-sdk-java.md). Implementano `org.apache.tomcat.jdbc.pool.JdbcInterceptor` e sono compatibili con i pool di connessione di Tomcat.
**Nota**
Gli intercettori SQL non registrano la query SQL stessa all'interno dei sottosegmenti per scopi di sicurezza.
Nel caso di Spring, aggiungi il collettore in un file delle proprietà e compila la sorgente dati con il `DataSourceBuilder` di Spring Boot.
**Example `src/main/java/resources/application.properties` - PostgreSQL JDBC Interceptor**
```
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
```
**Example `src/main/java/myapp/WebConfig.java` - Origine dati**
```
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import javax.servlet.Filter;
import javax.sql.DataSource;
import java.net.URL;
@Configuration
@EnableAutoConfiguration
@EnableJpaRepositories("myapp")
public class RdsWebConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource")
public DataSource dataSource() {
logger.info("Initializing PostgreSQL datasource");
return DataSourceBuilder.create()
.driverClassName("org.postgresql.Driver")
.url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb")
.username(System.getenv("RDS_USERNAME"))
.password(System.getenv("RDS_PASSWORD"))
.build();
}
...
}
```
Per Tomcat, `setJdbcInterceptors` richiamate l'origine dati JDBC con un riferimento alla classe X-Ray SDK for Java.
**Example `src/main/myapp/model.java` - Origine dati**
```
import org.apache.tomcat.jdbc.pool.DataSource;
...
DataSource source = new DataSource();
source.setUrl(url);
source.setUsername(user);
source.setPassword(password);
source.setDriverClassName("com.mysql.jdbc.Driver");
source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");
```
La libreria Tomcat JDBC Data Source è inclusa nell'X-Ray SDK for Java, ma è possibile dichiararla come dipendenza fornita dal documento che la si utilizza.
**Example `pom.xml`- Origine dati JDBC**
```
org.apache.tomcat
tomcat-jdbc
8.0.36
provided
```
## Decoratore di tracciamento SQL nativo
+ Aggiungilo [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)alle tue dipendenze.
+ Decora l'origine dati, la connessione o la dichiarazione del database.
```
dataSource = TracingDataSource.decorate(dataSource)
connection = TracingConnection.decorate(connection)
statement = TracingStatement.decorateStatement(statement)
preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql)
callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql)
```
# Generazione di sottosegmenti personalizzati con X-Ray SDK for Java
**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
I sottosegmenti estendono il [segmento](xray-concepts.md#xray-concepts-segments) di una traccia con dettagli sul lavoro svolto per soddisfare una richiesta. Ogni volta che si effettua una chiamata con un client dotato di strumentazione, l'X-Ray SDK registra le informazioni generate in un sottosegmento. È possibile creare sottosegmenti aggiuntivi per raggruppare altri sottosegmenti, misurare le prestazioni di una sezione di codice o registrare annotazioni e metadati.
Per gestire i sottosegmenti, utilizza i metodi `beginSubsegment` e `endSubsegment`.
**Example GameModel.java - sottosegmento personalizzato**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("Save Game");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
In questo esempio, il codice all'interno del sottosegmento carica la sessione del gioco da DynamoDB con un metodo sul modello di sessione e utilizza il mapper DynamoDB per salvare il AWS SDK per Java gioco. Inserendo questo codice in un sottosegmento, le chiamate DynamoDB sono figli del `Save Game` sottosegmento nella vista trace della console.
![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png)
Se il codice nel tuo sottosegmento genera eccezioni gestite, eseguine il wrapping in un blocco `try` e chiama `AWSXRay.endSubsegment()` in un blocco `finally` per assicurare che il sottosegmento sia sempre chiuso. Se un sottosegmento non è chiuso, il segmento principale non può essere completato e non verrà inviato a X-Ray.
Per il codice che non genera eccezioni controllate, puoi passare il codice a `AWSXRay.CreateSubsegment` come funzione Lambda.
**Example Funzione Lambda del sottosegmento**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
AWSXRay.createSubsegment("getMovies", (subsegment) -> {
// function code
});
```
Quando si crea un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK for Java genera un ID per tale sottosegmento e registra l'ora di inizio e l'ora di fine.
**Example Sottosegmento con metadati**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
Per la programmazione asincrona e multithread, è necessario passare manualmente il sottosegmento al `endSubsegment()` metodo per assicurarsi che sia chiuso correttamente, poiché il contesto X-Ray può essere modificato durante l'esecuzione asincrona. Se un sottosegmento asincrono viene chiuso dopo la chiusura del segmento principale, questo metodo trasmetterà automaticamente l'intero segmento al demone X-Ray.
**Example Sottosegmento asincrono**
```
@GetMapping("/api")
public ResponseEntity api() {
CompletableFuture.runAsync(() -> {
Subsegment subsegment = AWSXRay.beginSubsegment("Async Work");
try {
Thread.sleep(3000);
} catch (InterruptedException e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment(subsegment);
}
});
return ResponseEntity.ok().build();
}
```
# Aggiungi annotazioni e metadati ai segmenti con X-Ray SDK for Java
**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
È possibile registrare informazioni aggiuntive sulle richieste, sull'ambiente o sull'applicazione con annotazioni e metadati. È possibile aggiungere annotazioni e metadati ai segmenti creati da X-Ray SDK o ai sottosegmenti personalizzati creati dall'utente.
**Le annotazioni sono coppie** chiave-valore con stringhe, numeri o valori booleani. [Le annotazioni sono indicizzate per essere utilizzate con le espressioni di filtro.](xray-console-filters.md) Utilizzale per registrare i dati che desideri utilizzare per raggruppare le tracce nella console oppure per chiamare l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
I **metadati** sono coppie chiave-valore che possono avere valori di qualsiasi tipo, inclusi oggetti ed elenchi, ma non sono indicizzati per essere utilizzati con le espressioni di filtro. Utilizzate i metadati per registrare dati aggiuntivi che desiderate archiviare nella traccia ma che non è necessario utilizzare con la ricerca.
Oltre ad annotazioni e metadati, sui segmenti puoi anche [registrare le stringhe degli ID utente](#xray-sdk-java-segment-userid). IDs Gli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati nella ricerca.
**Topics**
+ [Registrazione delle annotazioni con X-Ray SDK for Java](#xray-sdk-java-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK for Java](#xray-sdk-java-segment-metadata)
+ [Utente che registra IDs con X-Ray SDK for Java](#xray-sdk-java-segment-userid)
## Registrazione delle annotazioni con X-Ray SDK for Java
Utilizza le annotazioni per memorizzare le informazioni su segmenti o sottosegmenti che desideri siano indicizzate per la ricerca.
**Requisiti per le annotazioni**
+ **Chiavi**: la chiave per un'annotazione a raggi X può contenere fino a 500 caratteri alfanumerici. Non è possibile utilizzare spazi o simboli diversi da un punto o un punto (.)
+ **Valori**: il valore di un'annotazione X-Ray può contenere fino a 1.000 caratteri Unicode.
+ Il numero di **annotazioni**: è possibile utilizzare fino a 50 annotazioni per traccia.
**Per registrare le annotazioni**
1. Ottenere un riferimento al segmento o sottosegmento corrente da `AWSXRay`.
```
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);
...
Segment document = AWSXRay.getCurrentSegment();
```
or
```
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);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. Chiamare `putAnnotation` con una chiave di tipo Stringa e un valore booleano, numerico o di tipo Stringa.
```
document.putAnnotation("mykey", "my value");
```
L'esempio seguente mostra come effettuare una chiamata `putAnnotation` con una chiave String che include un punto e un valore booleano, numerico o stringa.
```
document.putAnnotation("testkey.test", "my value");
```
L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `putAnnotation` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto.
Per trovare tracciamenti con annotazioni contenenti valori specifici, utilizza la parola chiave `annotation[key]` in un'[espressione 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();
}
}
```
## Registrazione di metadati con X-Ray SDK for Java
Utilizza i metadati per memorizzare le informazioni su segmenti o sottosegmenti che non è necessario che siano indicizzate per la ricerca. I valori dei metadati possono essere stringhe, numeri, valori booleani o qualsiasi oggetto che possa essere serializzato in un oggetto o in un vettore JSON.
**Per registrare i metadati**
1. Ottenere un riferimento al segmento o sottosegmento corrente da `AWSXRay`.
```
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);
...
Segment document = AWSXRay.getCurrentSegment();
```
or
```
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);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. Chiamare `putMetadata` con un namespace di tipo stringa, una chiave di tipo Stringa e un valore booleano, numerico, di tipo Stringa o di tipo oggetto.
```
document.putMetadata("my namespace", "my key", "my value");
```
or
Invocare `putMetadata` semplicemente con una chiave e un valore.
```
document.putMetadata("my key", "my value");
```
Se non specifichi un namespace, l'SDK utilizza `default`. Se chiami `putMetadata` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto.
**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();
}
}
```
## Utente che registra IDs con X-Ray SDK for Java
Registra i segmenti dell'utente IDs su richiesta per identificare l'utente che ha inviato la richiesta.
**Per registrare l'utente IDs**
1. Ottenere un riferimento al segmento corrente da `AWSXRay`.
```
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);
...
Segment document = AWSXRay.getCurrentSegment();
```
1. Chiamare `setUser` con una stringa che rappresenta l'ID dell'utente che ha inviato la richiesta.
```
document.setUser("U12345");
```
Puoi chiamare `setUser` nel tuo controller per registrare l'ID utente non appena l'applicazione inizia ad elaborare una richiesta. Se usi il segmento solo per impostare l'ID utente, puoi concatenare le chiamate in un'unica riga.
**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);
}
```
Per trovare tracciamenti associati ad un ID utente, utilizza la parola chiave `user` in un'[espressione filtro](xray-console-filters.md).
## AWS X-Ray metriche per X-Ray SDK for Java
**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 argomento descrive lo spazio dei nomi, le metriche e le dimensioni. AWS X-Ray Puoi utilizzare X-Ray SDK for Java per pubblicare metriche CloudWatch Amazon non campionate dai segmenti X-Ray raccolti. Questi parametri sono derivati dall'ora di inizio e di fine del segmento e dai flag di stato di errore, errore e limitazione. Utilizzare questi parametri di tracciamento per esporre tentativi e problemi di dipendenza all'interno di sottosegmenti.
CloudWatch è un archivio di metriche. Una metrica è il concetto fondamentale CloudWatch e rappresenta un insieme di punti dati ordinati nel tempo. Pubblichi (o Servizi AWS) punti dati delle metriche CloudWatch e recuperi le statistiche su tali punti dati come un insieme ordinato di dati di serie temporali.
I parametri sono definiti in modo univoco da un nome, un namespace e una o più dimensioni. A ogni punto dati è associato un timestamp e, facoltativamente, un'unità di misura. Quando si richiedono statistiche, il flusso di dati restituito viene identificato da namespace, nome parametro e dimensione.
Per ulteriori informazioni CloudWatch, consulta la [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/).
### Metriche X-Ray CloudWatch
Lo spazio dei nomi `ServiceMetrics/SDK` include le metriche descritte di seguito.
| Metrica | Statistiche disponibili | Description | unità |
| --- | --- | --- | --- |
| `Latency` | Media, Minimo, Massimo, Conteggio | La differenza tra l'ora di inizio e di fine. Media, minima e massima descrivono la latenza operativa. Il conteggio descrive il conteggio delle chiamate. | Millisecondi |
| `ErrorRate` | Average (Media), Sum (Somma) | La percentuale di richieste non riuscite con un codice di stato `4xx Client Error`, causando un errore. | Percentuale |
| `FaultRate` | Average (Media), Sum (Somma) | Il tasso di tracciamenti non riusciti con un codice di stato `5xx Server Error`, causando un errore. | Percentuale |
| `ThrottleRate` | Average (Media), Sum (Somma) | La velocità di tracciamento limitate che restituiscono un codice di stato `429`. Questo è un sottoinsieme della metrica `ErrorRate`. | Percentuale |
| `OkRate` | Average (Media), Sum (Somma) | Il tasso di richieste tracciate risultante in un codice di stato `OK`. | Percentuale |
### Dimensioni dei raggi X CloudWatch
Utilizzate le dimensioni nella tabella seguente per rifinire le metriche restituite per le vostre applicazioni con strumentazione a raggi X. Java
| Dimensione | Description |
| --- | --- |
| `ServiceType` | Il tipo di servizio, ad esempio, `AWS::EC2::Instance` o `NONE`, se non noto. |
| `ServiceName` | Il nome canonico del servizio. |
### Abilita le metriche X-Ray CloudWatch
Utilizzate la seguente procedura per abilitare le metriche di traccia nella vostra applicazione strumentata. Java
**Per configurare i parametri di tracciamento**
1. Aggiungi il `aws-xray-recorder-sdk-metrics` pacchetto come dipendenza. Apache Maven Per ulteriori informazioni, vedere [X-Ray SDK](#xray-sdk-java-submodules) for Java Submodules.
1. Attiva un nuovo `MetricsSegmentListener()` come parte della build del registratore globale.
**Example src/com/myapp/web/Startup.java**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard()
.withPlugin(new EC2Plugin())
.withPlugin(new ElasticBeanstalkPlugin())
.withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
1. Implementa l' CloudWatch agente per raccogliere i parametri utilizzando Amazon Elastic Compute Cloud (Amazon) EC2, Amazon Elastic Container Service (Amazon ECS) o Amazon Elastic Kubernetes Service (Amazon EKS):
+ Per configurare Amazon EC2, consulta [Installazione dell' CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html).
+ Per configurare Amazon ECS, consulta [Monitorare i contenitori Amazon ECS utilizzando Container](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html) Insights.
+ Per configurare Amazon EKS, consulta [Installare l' CloudWatch agente utilizzando il componente aggiuntivo Amazon CloudWatch Observability EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html).
1. Configura l'SDK per comunicare con l'agente. CloudWatch Per impostazione predefinita, l'SDK comunica con l' CloudWatch agente sull'indirizzo. `127.0.0.1` Puoi configurare indirizzi alternativi impostando la variabile di ambiente o la proprietà Java su `address:port`.
**Example Variabile di ambiente**
```
AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
```
**Example Proprietà Java**
```
com.amazonaws.xray.metrics.daemonAddress=address:port
```
**Per convalidare la configurazione**
1. Accedi a Console di gestione AWS e apri la CloudWatch console all'indirizzo. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)
1. Apri la scheda **Metrics (Parametri)** per osservare l'afflusso dei tuoi parametri.
1. (Facoltativo) Nella CloudWatch console, nella scheda **Registri**, apri il gruppo di `ServiceMetricsSDK` log. Cerca un flusso di log che corrisponda ai parametri host e conferma i messaggi di registro.
# Passaggio del contesto del segmento tra thread in un'applicazione multithread
**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
Quando crei un nuovo thread nella tua applicazione, l'`AWSXRayRecorder` non mantenere un riferimento all'[Entità](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html) del segmento o sottosegmento correnti. Se utilizzi un client dotato di strumenti nel nuovo thread, l'SDK tenta di scrivere su un segmento che non esiste, causando un. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)
Per evitare di generare eccezioni durante lo sviluppo, puoi configurare il registratore con un comando [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)che gli indichi invece di registrare un errore. [È possibile configurare la strategia in codice con [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy))o configurare opzioni equivalenti con una [variabile di ambiente o una proprietà](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) di sistema.](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)
Un modo di risolvere l'errore è utilizzare un nuovo segmento chiamando [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) quando inizia il thread e [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--) quando viene chiuso. Questo funziona se si sta analizzando una porzione di codice che non viene eseguita in risposta ad una richiesta HTTP, come il codice eseguito all'avvio dell'applicazione.
Se utilizzi più thread per gestire le richieste in entrata, puoi passare il segmento o il sottosegmento correnti al nuovo thread e fornirli al registratore globale. In questo modo le informazioni registrate all'interno del nuovo thread sono associate allo stesso segmento delle altre informazioni registrate sulla richiesta. Una volta che il segmento è disponibile nel nuovo thread, puoi eseguire qualsiasi eseguibile con accesso al contesto di quel segmento utilizzando il `segment.run(() -> { ... })` metodo.
Consulta [Utilizzo dei client analizzati nei thread worker](scorekeep-workerthreads.md) per un esempio.
## Utilizzo di X-Ray con programmazione asincrona
L'X-Ray SDK for Java può essere utilizzato in programmi Java asincroni con. [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) SegmentContextExecutor Implementa l'interfaccia Executor, il che significa che può essere passata a tutte le operazioni asincrone di un. [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) Ciò garantisce che qualsiasi operazione asincrona venga eseguita con il segmento corretto nel suo contesto.
**Example Esempio App.java: passaggio a SegmentContextExecutor CompletableFuture**
```
DynamoDbAsyncClient client = DynamoDbAsyncClient.create();
AWSXRay.beginSegment();
// ...
client.getItem(request).thenComposeAsync(response -> {
// If we did not provide the segment context executor, this request would not be traced correctly.
return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());
```
# AOP con Spring e X-Ray SDK per Java
**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 argomento descrive come utilizzare X-Ray SDK e Spring Framework per strumentare l'applicazione senza modificarne la logica di base. Ciò significa che ora esiste un modo non invasivo per strumentare le applicazioni in esecuzione in remoto. AWS
**Per abilitare AOP in Spring**
1. [Configurare Spring](#xray-sdk-java-aop-spring-configuration)
1. [Aggiungi un filtro di tracciamento alla tua applicazione](#xray-sdk-java-aop-filters-spring)
1. [Annotare il codice o implementare un'interfaccia](#xray-sdk-java-aop-annotate-or-implement)
1. [Attivare X-Ray nell'applicazione](#xray-sdk-java-aop-activate-xray)
## Configurazione di Spring
Per configurare Spring affinché utilizzi AOP per l'analisi della tua applicazione, puoi utilizzare Maven o Gradle.
Se utilizzi Maven per compilare l'applicazione, aggiungi la seguente dipendenza nel file `pom.xml`.
```
com.amazonaws
aws-xray-recorder-sdk-spring
2.11.0
```
Se utilizzi Gradle, aggiungi la seguente dipendenze nel file `build.gradle`.
```
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0'
```
## Configurazione di Spring Boot
Oltre alla dipendenza Spring descritta nella sezione precedente, se stai usando Spring Boot, aggiungi la seguente dipendenza se non è già nel tuo classpath.
Maven:
```
org.springframework.boot
spring-boot-starter-aop
2.5.2
```
Gradle:
```
compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2'
```
## Aggiungere un filtro di tracciamento all'applicazione
Aggiungi un `Filter` alla tua `WebConfig` classe. Passare il nome del segmento al costruttore [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) come valore di tipo stringa. Per ulteriori informazioni sul tracciamento dei filtri e sulla strumentazione delle richieste in arrivo, consulta. [Tracciamento delle richieste in arrivo con X-Ray SDK for Java](xray-sdk-java-filters.md)
**Example src/main/java/myapp/WebConfig.java - primavera**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
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");
}
}
```
## Jakarta Support
Spring 6 utilizza [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) anziché Javax per la sua Enterprise Edition. Per supportare questo nuovo spazio dei nomi, X-Ray ha creato un set parallelo di classi che risiedono nel proprio spazio dei nomi di Jakarta.
Per le classi di filtro, sostituirle con. `javax` `jakarta` Quando configurate una strategia di denominazione dei segmenti, aggiungete `jakarta` prima del nome della classe di strategia di denominazione, come nell'esempio seguente:
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import jakarta.servlet.Filter;
import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy;
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep"));
}
}
```
## Annotazione del codice o implementazione di un'interfaccia
Le tue classi devono essere annotate con l'`@XRayEnabled`annotazione o implementare l'interfaccia. `XRayTraced` Questo indica al sistema AOP di eseguire il wrapping delle funzioni della classe interessata per l'analisi di X-Ray.
## Attivazione di X-Ray nell'applicazione
Per attivare il tracciamento X-Ray nell'applicazione, il codice deve estendere la classe astratta `BaseAbstractXRayInterceptor` sovrascrivendo i seguenti metodi.
+ `generateMetadata`—Questa funzione consente la personalizzazione dei metadati allegati alla traccia della funzione corrente. Per impostazione predefinita, il nome della classe della funzione in esecuzione viene registrato nei metadati. Puoi aggiungere altri dati se hai bisogno di informazioni aggiuntive.
+ `xrayEnabledClasses`—Questa funzione è vuota e dovrebbe rimanere tale. Serve come host per un pointcut che indica ai collettori di quali metodi effettuare il wrapping. Definisci il pointcut specificando quali delle classi che annotate con `@XRayEnabled` tracciare. La seguente istruzione pointcut indica al collettore di eseguire il wrapping di tutti i bean controller annotati con l'annotazione `@XRayEnabled`.
```
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
```
Se il tuo progetto utilizza Spring Data JPA, valuta la possibilità di estendere from `AbstractXRayInterceptor` anziché. `BaseAbstractXRayInterceptor`
## Esempio
Il codice seguente estende la classe astratta. `BaseAbstractXRayInterceptor`
```
@Aspect
@Component
public class XRayInspector extends BaseAbstractXRayInterceptor {
@Override
protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception {
return super.generateMetadata(proceedingJoinPoint, subsegment);
}
@Override
@Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)")
public void xrayEnabledClasses() {}
}
```
Il codice seguente è una classe che sarà analizzata da X-Ray.
```
@Service
@XRayEnabled
public class MyServiceImpl implements MyService {
private final MyEntityRepository myEntityRepository;
@Autowired
public MyServiceImpl(MyEntityRepository myEntityRepository) {
this.myEntityRepository = myEntityRepository;
}
@Transactional(readOnly = true)
public List getMyEntities(){
try(Stream entityStream = this.myEntityRepository.streamAll()){
return entityStream.sorted().collect(Collectors.toList());
}
}
}
```
Se hai configurato la tua applicazione correttamente, dovresti vedere l'intero stack di chiamate dell'applicazione, dai controller fino alle chiamate al servizio, come illustrato nella seguente schermata della console.
![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/aop-spring-console.png)