Utilizzo delle espressioni di filtro

Utilizza le espressioni di filtro per visualizzare una o più tracce per una richiesta, un servizio, una connessione tra due servizi (un edge) o richieste che soddisfano una condizione. X-Ray fornisce un linguaggio di espressione di filtro per filtrare richieste, servizi e bordi in base ai dati nelle intestazioni delle richieste, allo stato della risposta e ai campi indicizzati sui segmenti originali.

Quando scegli un periodo di tempo per le tracce da visualizzare nella console X-Ray, potresti ottenere più risultati di quelli che la console può visualizzare. Nell'angolo in alto a destra, la console mostra il numero di tracciamenti individuati e se sono disponibili ulteriori tracciamenti. È possibile utilizzare un'espressione di filtro per restringere i risultati alle sole tracce che si desidera trovare.

Filtraggio dei dettagli delle espressioni

Quando si sceglie un nodo nella mappa di traccia, la console crea un'espressione di filtro in base al nome di servizio del nodo e ai tipi di errore presenti in base alla selezione effettuata. Per individuare tracciamenti che mostrano problemi di prestazioni o che riguardano richieste specifiche, puoi modificare l'espressione generata dalla console oppure crearne una tua. Se aggiungi annotazioni con SDK X-Ray, puoi anche filtrare in base alla presenza di una chiave di annotazione o al valore di una chiave.

Nota

Se scegli un intervallo di tempo relativo nella mappa di traccia e scegli un nodo, la console converte l'intervallo di tempo in un'ora di inizio e di fine assolute. Per garantire che i tracciamenti relativi al nodo vengano visualizzati tra risultati di ricerca, e per evitare la scansione dei periodi di tempo in cui il nodo non era attivo, l'intervallo di tempo include solo i periodi durante i quali il nodo ha inviato dei tracciamenti. Se desideri eseguire una ricerca rispetto all'ora corrente, puoi ripristinare l'intervallo di tempo relativo nella pagina dei tracciamenti ed eseguire nuovamente la scansione.

Se vengono ancora restituiti più risultati di quanti la console possa visualizzare, la console mostra quanti tracciamenti soddisfano il filtro e di quanti è stata eseguita la scansione. La percentuale visualizzata è la percentuale dell'intervallo di tempo selezionato di cui è stata eseguita la scansione. Restringi ulteriormente l'espressione filtro, oppure scegli un intervallo di tempo più breve, in modo da visualizzare tra i risultati tutti i tracciamenti corrispondenti al filtro.

Per disporre prima dei risultati più recenti, la console avvia la scansione partendo dal termine dell'intervallo di tempo e procedendo in senso cronologico inverso. In caso di un numero elevato di tracciamenti, la console suddivide l'intervallo di tempo in blocchi ed esegue le scansioni in parallelo. La barra di avanzamento mostra le porzioni dell'intervallo di tempo relativamente alle quali è stata eseguita la scansione.

Utilizzo delle espressioni filtro con i gruppi

I gruppi costituiscono una raccolta di tracciamenti definiti da un'espressione di filtro. Puoi utilizzare i gruppi per generare grafici di servizio aggiuntivi e fornire CloudWatch metriche Amazon.

I gruppi sono identificati dal loro nome o da un Amazon Resource Name (ARN) e contengono un'espressione di filtro. Il servizio confronta i tracciamenti in entrata con l'espressione e le memorizza di conseguenza.

È possibile creare e modificare i gruppi utilizzando il menu a discesa a sinistra della barra di ricerca delle espressioni filtro.

Nota

Se il servizio rileva un errore nel qualificare un gruppo, tale gruppo non viene più incluso nell'elaborazione dei tracciamenti in entrata e viene registrata un parametro di errore.

Per ulteriori informazioni sui gruppi, consultaConfigurazione dei gruppi.

Sintassi delle espressioni filtro

Le espressioni filtro possono contenere una parola chiave, un operatore unario o binario e un valore per il confronto.

keyword operator value

Sono disponibili diversi operatori per diversi tipi di parola chiave. Ad esempio, responsetime è una parola chiave numerica e può essere confrontata con operatori correlati a numeri.

Esempio — richieste in cui il tempo di risposta è stato superiore a 5 secondi

responsetime > 5

Puoi combinare più espressioni in un'espressione composta mediante gli operatori AND o OR.

Esempio — richieste la cui durata totale era di 5—8 secondi

duration >= 5 AND duration <= 8

Le parole chiave e gli operatori semplici individuano problemi solo a livello di tracciamento. Se si verifica un errore a valle, ma è gestito direttamente dall'applicazione e non viene restituito all'utente, una ricerca per error non lo individuerà.

Per individuare tracciamenti che includano problemi con chiamate a valle, puoi utilizzare le parole chiave complesse service() e edge(). Queste parole chiave ti permettono di applicare un'espressione filtro a tutti i nodi a valle, a un singolo nodo a valle o ad un collegamento tra due nodi. Per una maggiore granularità, puoi filtrare servizi ed edge per tipo con la funzione id().

Parole chiave booleane

I valori delle parole chiave booleane sono true o false. Utilizza queste parole chiave per individuare i tracciamenti che hanno generato errori.

Parole chiave booleane

• ok— Il codice di stato della risposta era 2XX Success.

• error— Il codice di stato della risposta era 4XX Client Error.

• throttle— Il codice di stato della risposta era 429 Too Many Requests.

• fault— Il codice di stato della risposta era 5XX Server Error.

• partial— La richiesta ha segmenti incompleti.

• inferred— La richiesta ha segmenti dedotti.

• first— L'elemento è il primo di un elenco enumerato.

• last— L'elemento è l'ultimo di un elenco enumerato.

• remote— L'entità della causa principale è remota.

• root— Il servizio è il punto di ingresso o il segmento principale di una traccia.

Gli operatori booleani individuano i segmenti in cui la chiave specificata è true o false.

Operatori booleani

• nessuno: l'espressione è vera se la parola chiave è vera.

• !— L'espressione è vera se la parola chiave è falsa.

• =, != — Confronta il valore della parola chiave con la stringa true orfalse. Questi operatori agiscono allo stesso modo degli altri operatori, ma sono più espliciti.

Esempio — lo stato della risposta è 2XX OK

ok

Esempio — lo stato della risposta non è 2XX OK

!ok

Esempio — lo stato della risposta non è 2XX OK

ok = false

Esempio — l'ultima traccia di errore enumerata ha il nome di errore «deserializza»

rootcause.fault.entity { last and name = "deserialize" }

Esempio — richieste con segmenti remoti in cui la copertura è maggiore di 0,7 e il nome del servizio è «trace»

rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }

Esempio — richieste con segmenti dedotti in cui il tipo di servizio è «:DynamoDB» AWS

rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }

Esempio — richieste che hanno come radice un segmento denominato «data-plane»

service("data-plane") {root = true and fault = true}

Parole chiave numeriche

Utilizzare le parole chiave numeriche per ricercare le richieste con un tempo di risposta, una durata o un codice di stato della risposta specifici.

Parole chiave numeriche

• responsetime— Tempo impiegato dal server per inviare una risposta.

• duration— Durata totale della richiesta, incluse tutte le chiamate downstream.

• http.status— Codice di stato della risposta.

• index— Posizione di un elemento in un elenco enumerato.

• coverage— Percentuale decimale del tempo di risposta dell'entità rispetto al tempo di risposta del segmento principale. Applicabile solo per le entità causa principale del tempo di risposta.

Operatori numerici

Le parole chiave numeriche utilizzano gli operatori di uguaglianza e di confronto standard.

• =, != — La parola chiave è uguale o diversa da un valore numerico.

• <,<=,>, >= — La parola chiave è minore o maggiore di un valore numerico.

Esempio — lo stato della risposta non è 200 OK

http.status != 200

Esempio — richiesta in cui la durata totale era di 5—8 secondi

duration >= 5 AND duration <= 8

Esempio — richieste completate con successo in meno di 3 secondi, comprese tutte le chiamate a valle

ok !partial duration <3

Esempio — entità di elenco enumerato con un indice maggiore di 5

rootcause.fault.service { index > 5 }

Esempio — richieste in cui l'ultima entità con copertura è superiore a 0,8

rootcause.responsetime.entity { last and coverage > 0.8 }

Parole chiave stringa

Utilizza parole chiave di tipo stringa per trovare tracce con testo specifico nelle intestazioni della richiesta o un utente IDs specifico.

Parole chiave stringa

• http.url— RichiestaURL.

• http.method— Metodo di richiesta.

• http.useragent— Richiedere la stringa dell'agente utente.

• http.clientip— Indirizzo IP del richiedente.

• user— Valore del campo utente su qualsiasi segmento della traccia.

• name— Il nome di un servizio o di un'eccezione.

• type— Tipo di servizio.

• message— Messaggio di eccezione.

• availabilityzone— Valore del campo availabilityzone su qualsiasi segmento della traccia.

• instance.id— Valore del campo ID dell'istanza su qualsiasi segmento della traccia.

• resource.arn— Valore del ARN campo delle risorse su qualsiasi segmento della traccia.

Gli operatori di stringa selezionano valori che sono uguali a, o contengono, un testo specifico. I valori devono essere sempre specificati tra virgolette.

Operatori di stringa

• =, != — La parola chiave è uguale o diversa da un valore numerico.

• CONTAINS— La parola chiave contiene una stringa specifica.

• BEGINSWITH, ENDSWITH — La parola chiave inizia o termina con una stringa specifica.

Esempio — filtro http.url

http.url CONTAINS "/api/game/"

Per verificare se un campo esiste all'interno di un tracciamento, indipendentemente dal suo valore, verificare se contiene la stringa vuota.

Esempio — filtro utente

Trova tutte le tracce con l'utenteIDs.

user CONTAINS ""

Esempio — seleziona le tracce con una causa principale dell'errore che include un servizio chiamato «Auth»

rootcause.fault.service { name = "Auth" }

Esempio — seleziona le tracce con una root cause del tempo di risposta il cui ultimo servizio ha un tipo di DynamoDB

rootcause.responsetime.service { last and type = "AWS::DynamoDB" }

Esempio — seleziona le tracce con una causa principale di errore la cui ultima eccezione è il messaggio «accesso negato per account_id: 1234567890"

rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890" 

Parole chiave complesse

Le parole chiave complesse permettono di selezionare le richieste in base a nome del servizio, nome edge o valore dell'annotazione. Per servizi e collegamenti, puoi specificare un ulteriore espressione filtro che si applica al servizio o al collegamento. Per le annotazioni, puoi filtrare in base al valore di un'annotazione con una specifica chiave utilizzando operatori booleani, numerici o stringa.

Parole chiave complesse

• annotation[key]— Valore di un'annotazione con campo key. Il valore di un'annotazione può essere un valore booleano, un numero o una stringa, quindi puoi utilizzare uno qualsiasi degli operatori di confronto di questi tipi. È possibile utilizzare questa parola chiave in combinazione con la service parola chiave or. edge Una chiave di annotazione che contiene punti (punti) deve essere racchiusa tra parentesi quadre ([]).

• edge(source, destination) {filter}— Connessione tra servizi source e destination. Le parentesi graffe opzionali possono contenere un'espressione di filtro che si applica ai segmenti di questa connessione.

• group.name / group.arn— Il valore dell'espressione di filtro di un gruppo, a cui fa riferimento il nome o il gruppo del gruppo. ARN

• json— oggetto JSON causa principale. Vedi Acquisizione di dati da AWS X-Ray per i passaggi per creare JSON entità a livello di codice.

• service(name) {filter}— Servizio con nome name. Le parentesi graffe opzionali possono contenere un'espressione di filtro che si applica ai segmenti creati dal servizio.

Utilizza la parola chiave service per trovare le tracce delle richieste che raggiungono un determinato nodo sulla mappa di tracciamento.

Gli operatori di parole chiave complesse trovano i segmenti in cui è stata impostata o non è stata impostata la chiave specificata.

Operatori di parole chiave complessi

• nessuno: l'espressione è vera se la parola chiave è impostata. Se la parola chiave è di tipo booleano, restituirà il valore booleano.

• !— L'espressione è vera se la parola chiave non è impostata. Se la parola chiave è di tipo booleano, restituirà il valore booleano.

• =, != — Confronta il valore della parola chiave.

• edge(source, destination) {filter}— Connessione tra servizi source e destination. Le parentesi graffe opzionali possono contenere un'espressione di filtro che si applica ai segmenti di questa connessione.

• annotation[key]— Valore di un'annotazione con campo key. Il valore di un'annotazione può essere un valore booleano, un numero o una stringa, quindi puoi utilizzare uno qualsiasi degli operatori di confronto di questi tipi. È possibile utilizzare questa parola chiave in combinazione con la service parola chiave or. edge

• json— oggetto JSON causa principale. Vedi Acquisizione di dati da AWS X-Ray per i passaggi per creare JSON entità a livello di codice.

Utilizza la parola chiave service per trovare le tracce delle richieste che raggiungono un determinato nodo sulla mappa di tracciamento.

Esempio — Filtro di servizio

Richieste che includevano una chiamata a api.example.com e che si sono concluse con un malfunzionamento (errore serie 500).

service("api.example.com") { fault }

Puoi escludere il nome del servizio per applicare un'espressione filtro a tutti i nodi della tua mappa del servizio.

Esempio — filtro di servizio

Richieste che hanno causato un errore in qualsiasi punto della mappa di tracciamento.

service() { fault }

La parola chiave edge applica un'espressione filtro a una connessione tra due nodi.

Esempio — filtro perimetrale

Richiesta in cui il servizio api.example.com ha eseguito una chiamata verso backend.example.com che si è conclusa con un errore.

edge("api.example.com", "backend.example.com") { error }

Puoi inoltre utilizzare l'operatore ! con le parole chiave service ed edge per escludere un servizio o un collegamento dai risultati di un'altra espressione filtro.

Esempio — filtro di servizio e richiesta

Richiesta in cui URL inizia http://api.example.com/ e contiene /v2/ ma non raggiunge un servizio denominatoapi.example.com.

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")

Esempio — filtro del servizio e del tempo di risposta

Trova le tracce dove http url è impostato e il tempo di risposta è superiore a 2 secondi.

http.url AND responseTime > 2

Per le annotazioni, puoi richiamare tutte le tracce in cui annotation[key] è impostato o utilizzare gli operatori di confronto che corrispondono al tipo di valore.

Esempio — annotazione con valore di stringa

Richieste con un'annotazione denominata gameid con valore stringa "817DL6VO".

annotation[gameid] = "817DL6VO"

Esempio — l'annotazione è impostata

Richieste con un'annotazione denominata age set.

annotation[age]

Esempio — l'annotazione non è impostata

Richieste senza un'annotazione denominata age set.

!annotation[age]

Esempio — annotazione con valore numerico

Richieste con annotazione age con valore numerico maggiore di 29.

annotation[age] > 29

Esempio — annotazione in combinazione con service o edge

service { annotation[request.id] = "917DL6VO" }

edge { source.annotation[request.id] = "916DL6VO" }

edge { destination.annotation[request.id] = "918DL6VO" }

Esempio — gruppo con utente

Richiede in cui le tracce soddisfano il filtro di high_response_time gruppo (ad esempioresponseTime > 3) e l'utente si chiama Alice.

group.name = "high_response_time" AND user = "alice"

Esempio — JSON con entità causa principale

Le richieste con entità causa principale corrispondenti.

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

funzione id

Quando indichi un nome di servizio per le parole chiave service o edge, ottieni risultati per tutti i nodi con tale nome. Per una maggiore precisione del filtraggio, puoi utilizzare la funzione id per specificare un tipo di servizio in aggiunta ad un nome per distinguere tra nodi con lo stesso nome.

Utilizza la account.id funzione per specificare un particolare account per il servizio, quando visualizzi le tracce di più account in un account di monitoraggio.

id(name: "service-name", type:"service::type", account.id:"account-ID")

Puoi utilizzare la funzione id al posto di un nome di servizio nei filtri service ed edge.

service(id(name: "service-name", type:"service::type")) { filter }

edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

Ad esempio, AWS Lambda le funzioni generano due nodi nella mappa di traccia, uno per la chiamata della funzione e uno per il servizio Lambda. I due nodi hanno lo stesso nome ma appartengono a tipi diversi. Un filtro sul servizio standard troverà i tracciamenti relativi a entrambi.

Esempio — filtro di servizio

Richieste che includono un errore su qualsiasi servizio denominato random-name.

service("function-name") { error }

Utilizza la funzione id per restringere la ricerca a errori sulla funzione stessa, escludendo gli errori del servizio.

Esempio — filtro di servizio con funzione id

Richieste che includono un errore su un servizio denominato random-name di tipo AWS::Lambda::Function.

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

Per ricercare i nodi in base al tipo, puoi anche omettere completamente il nome.

Esempio — filtro di servizio con funzione id e tipo di servizio

Richieste che includono un errore su un servizio di tipo AWS::Lambda::Function.

service(id(type: "AWS::Lambda::Function")) { error }

Per cercare i nodi per un particolare Account AWS, specifica un ID account.

Esempio — filtro di servizio con funzione id e ID account

Richieste che includono un servizio all'interno di un ID account specificoAWS::Lambda::Function.

service(id(account.id: "account-id"))