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à.
Configurazione di SDK X-Ray per Java
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. È possibile configurare il registratore globale per personalizzare quello AWSXRayServletFilter che crea segmenti per le chiamate in arrivo. HTTP
Sections
Plugin di servizio
pluginsUtilizzatelo per registrare informazioni sul servizio che ospita l'applicazione.
Plug-in
AmazonEC2:
EC2Pluginaggiunge l'ID dell'istanza, la zona di disponibilità e il gruppo di CloudWatch log.Elastic
ElasticBeanstalkPluginBeanstalk: aggiunge il nome dell'ambiente, l'etichetta della versione e l'ID di distribuzione.AmazonECS:
ECSPluginaggiunge l'ID del contenitore.AmazonEKS:
EKSPluginaggiunge l'ID del contenitore, il nome del cluster, l'ID del pod e il gruppo CloudWatch Logs.
Per usare un plugin, chiama withPlugin sul tuo AWSXRayRecorderBuilder.
Esempio src/main/java/scorekeep/ .java - registratore WebConfig
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());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}Utilizza SDK anche le impostazioni del plug-in per impostare il campo sul segmento. origin Indica il tipo di AWS risorsa che esegue l'applicazione. Quando si utilizzano più plugin, SDK utilizza il seguente ordine di risoluzione per determinare l'origine: ElasticBeanstalk > > EKS ECS >EC2.
Regole di campionamento
SDKUtilizza 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 per personalizzare la quantità di dati registrati per ciascuna delle tue applicazioni.
SDKApplica le regole personalizzate nell'ordine in cui sono definite. Se una richiesta corrisponde a più regole personalizzate, si SDK applica solo la prima regola.
Nota
Se non SDK 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 il campionamento APIs delle chiamate o non riesce a connettersi al demone X-Ray, che funge da proxy API per le chiamate TCP effettuate da. SDK
È inoltre possibile configurare SDK per caricare le regole di campionamento da un documento. JSON SDKPossono utilizzare le regole locali come backup per i casi in cui il campionamento a raggi X non è disponibile o utilizzare esclusivamente regole locali.
Esempio 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:
Esempio src/main/java/myapp/ .java - configurazione del registratore WebConfig
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@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.
Esempio 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.strategy.sampling.LocalizedSamplingStrategy;
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) { }
}Esempio WEB- /web.xml INF
...
<listener>
<listener-class>com.myapp.web.Startup</listener-class>
</listener>Per utilizzare solo regole locali, sostituisci CentralizedSamplingStrategy con una LocalizedSamplingStrategy.
builder.withSamplingStrategy(newLocalizedSamplingStrategy(ruleFile));
Registrazione
Per impostazione predefinita, invia messaggi a ERROR livello di SDK output nei registri dell'applicazione. È possibile abilitare la registrazione a livello di debug su SDK per generare log più dettagliati nel file di registro dell'applicazione. I livelli di registro validi sonoDEBUG,,, eINFO. WARN ERROR FATAL FATALil livello di registro silenzia tutti i messaggi di registro perché SDK non esegue la registrazione a livello irreversibile.
Esempio application.properties
Imposta il livello di log tramite la proprietà logging.level.com.amazonaws.xray.
logging.level.com.amazonaws.xray = DEBUGUtilizza i log di debug per identificare i problemi, come ad esempio dei sottosegmenti non chiusi, quando generi dei sottosegmenti manualmente.
Inserimento dell’ID di tracciamento nei log
Per esporre l'ID di traccia completo corrente alle istruzioni di registro, è possibile 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 iniettato nella chiave. MDC AWS-XRAY-TRACE-ID Quando il segmento termina, la chiave viene rimossa da. MDC Questo espone l'ID di tracciamento alla libreria di registrazione in uso. Quando un sottosegmento termina, il relativo ID principale viene iniettato in. MDC
Esempio ID di tracciamento completo
L'ID completo è rappresentato come TraceID@EntityID
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3Questa funzionalità funziona con le applicazioni Java dotate di AWS SDK X-Ray for Java e supporta le seguenti configurazioni di registrazione:
-
SLF4Jfront-end con backend Logback API
-
SLF4Jfront-end con backend Log4J2 API
-
Front-end API Log4J2 con backend Log4J2
Consulta le seguenti schede per le esigenze di ogni front-end e ogni back-end.
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).
Esempio 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.
Esempio 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 segment listener potrebbe consistere nell'aggiungere la stessa annotazione a tutti i sottosegmenti quando vengono creati con onBeginSubsegment, nel registrare un messaggio dopo che ogni segmento è stato inviato al demone utilizzando afterEndSegmento nel registrare le query inviate dagli SQL intercettori utilizzando beforeEndSubsegmentper verificare se il sottosegmento rappresenta una SQL query, aggiungendo metadati aggiuntivi in caso affermativo.
Nell'esempio seguente viene illustrato come aggiungere un'annotazione coerente a tutti i sottosegmenti durante la creazione con onBeginSubsegment e per stampare un messaggio di log alla fine di ogni segmento con afterEndSegment.
Esempio 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.
Esempio AWSXRayRecorderBuilder dichiarazione
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new MySegmentListener());Variabili di ambiente
È possibile utilizzare le variabili di ambiente per configurare X-Ray SDK for Java. SDKSupporta le seguenti variabili.
AWS_XRAY_CONTEXT_MISSING— ImpostaRUNTIME_ERRORper 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, vengono SDK utilizzati sia i dati127.0.0.1:2000di traccia () che il campionamento (UDP). TCP Utilizzate questa variabile se avete configurato il demone per l'ascolto su una porta diversa o se è in esecuzione su un host diverso.Formato
-
Stessa porta —
address:port -
Porte diverse:
tcp:address:portudp: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. -
AWS_XRAY_TRACING_NAME— Imposta un nome di servizio da SDK utilizzare per i segmenti. Sostituisce il nome del servizio impostato sulla strategia di denominazione dei segmenti del filtro servlet.
Le variabili di ambiente sostituiscono i valori equivalenti per le proprietà di sistema e i valori impostati nel codice.
Proprietà di sistema
È possibile utilizzare le proprietà di sistema come alternativa JVM specifica alle variabili di ambiente. SDKSupporta le seguenti proprietà:
-
com.amazonaws.xray.strategy.tracingName— Equivalente aAWS_XRAY_TRACING_NAME. -
com.amazonaws.xray.emitters.daemonAddress— Equivalente aAWS_XRAY_DAEMON_ADDRESS. -
com.amazonaws.xray.strategy.contextMissingStrategy— Equivalente aAWS_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.
