AWS X-Ray agente di strumentazione automatica per Java

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 Distributed Systems Comprehension toolkit, o DISCo. DISCo è un framework open source per la creazione di agenti Java che possono essere utilizzati in sistemi distribuiti. Sebbene non sia necessario conoscere DisCO per utilizzare l'agente X-Ray, puoi saperne di più sul progetto visitando la sua home page 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

Applicazione di esempio

L'applicazione eb-java-scorekeepdi 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.

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, vedere X-Ray daemon.

2. Scarica la distribuzione più recente dell'agente. 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

3. Modifica gli argomenti JVM dell'applicazione includendo quanto segue, che abilita l'agente. Assicuratevi che l'-javaagentargomento sia posto prima dell'-jarargomento, 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:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

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

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

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. Vedi le variabili di ambiente per informazioni sulle proprietà che puoi sovrascrivere. Tutti i campi sono facoltativi.

Nome proprietà	Type	Valori validi	Descrizione	Variabile di ambiente	Proprietà di sistema	Predefinita
serviceName	Stringa	Qualsiasi stringa	Il nome del servizio strumentato così come verrà visualizzato nella console X-Ray.	AWS_XRAY_TRACING_NAME	com.amazonaws.xray.strategy.tracingName	X RayInstrumentedService
contextMissingStrategy	Stringa	LOG_ERROR, IGNORE_ERROR	L'azione intrapresa dall'agente quando tenta di utilizzare il contesto del segmento X-Ray ma non è presente.	AWS_XRAY_CONTEXT_MISSING	com.amazonaws.xray.strategy. contextMissingStrategy	LOG_ERROR
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_XRAY_DAEMON_ADDRESS	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_XRAY_TRACING_ENABLED	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.	N/D	N/D	CENTRALE
traceIdInjectionprefisso	Stringa	Qualsiasi stringa	Include il prefisso fornito prima degli ID di traccia iniettati nei log.	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
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
awsSdkVersion	Numero intero	1, 2	Versione dell'AWS SDK for 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. 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.	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. RegistrazionePer 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 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

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

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 oltre alle annotazioni, ai metadati e agli ID utente durante l'utilizzo dell'agente, 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.

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

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. <NAME >Per verificare che questo sia il tuo 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 Configurare le regole di campionamento in. Esplora la console X-Ray