Usare lo strumento Traccia

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Che cos'è lo strumento Trace?

Trace è uno strumento per la risoluzione dei problemi e il monitoraggio dei proxy API in esecuzione su Apigee Edge. Trace consente di esaminare i dettagli di ogni passaggio tramite un flusso proxy API.

Come utilizzare Trace

Trace è semplice da usare. Avvia una sessione di traccia, quindi effettui una chiamata API alla piattaforma Edge e leggi i risultati.

1. Accedi alla pagina dei proxy API, come descritto di seguito.
   

   Perimetrale

   Per accedere alla pagina dei proxy API utilizzando l'interfaccia utente Edge:

   1. Accedi ad apigee.com/edge.
   2. Seleziona Sviluppo > Proxy API nella barra di navigazione a sinistra.

   Classic Edge (private cloud)

   Per accedere alla pagina dei proxy API utilizzando l'interfaccia utente classica di Edge:

   1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
   2. Seleziona API > Proxy API nella barra di navigazione in alto.
2. Seleziona un proxy API dalla pagina Proxy API.
3. Assicurati che sia stato eseguito il deployment dell'API che vuoi tracciare.
4. Fai clic su Trace per andare alla visualizzazione dello strumento Trace.
5. Utilizza il menu a discesa Deployment per tracciare per selezionare l'ambiente di deployment e la revisione del proxy da tracciare.
6. Fai clic su Avvia sessione di traccia. Quando la sessione di traccia è attiva, il proxy API registra i dettagli di ogni passaggio della pipeline di elaborazione. Mentre la sessione di Trace è in esecuzione, i messaggi e i dati contestuali vengono acquisiti dal traffico in tempo reale.
   

   

7. Se non disponi di traffico in tempo reale che passa attraverso il proxy, invia una richiesta all'API. Puoi utilizzare qualsiasi strumento tu voglia inviare la richiesta, ad esempio curl, Postman o qualsiasi strumento familiare. In alternativa, puoi inviare la richiesta direttamente dallo strumento Trace stesso. Inserisci l'URL e fai clic su Invia. Nota: puoi inviare una richiesta GET solo dallo strumento Trace, ma non una richiesta POST.
   
   Nota: una sessione Trace può supportare 10 transazioni di richiesta/risposta per processore di messaggi tramite il proxy API selezionato. Nel cloud Edge, con due processori di messaggi che gestiscono il traffico, sono supportate 20 transazioni di richiesta/risposta. Una sessione di traccia si interrompe automaticamente dopo 10 minuti se non la interrompi manualmente.
   
8. Dopo aver acquisito un numero sufficiente di richieste, fai clic su Interrompi sessione di traccia.
9. Nel menu a sinistra viene visualizzato un elenco delle transazioni di richiesta/risposta acquisite. Fai clic su una transazione per visualizzare i risultati dettagliati.

Come leggere una traccia

Lo strumento traccia ha due parti principali, la mappa transazioni e i dettagli della fase:

• La mappa delle transazioni utilizza icone per contrassegnare ogni passaggio rilevante che si verifica durante una transazione proxy API, tra cui l'esecuzione dei criteri, i passaggi condizionali e le transizioni. Passa il mouse sopra qualsiasi icona per visualizzare informazioni di riepilogo. I passaggi del flusso di richiesta vengono visualizzati nella parte superiore della mappa delle transazioni e i passaggi del flusso di risposta in basso.
• La sezione dei dettagli della fase dello strumento elenca informazioni sull'elaborazione interna del proxy, incluse le variabili impostate o lette, le intestazioni di richiesta e risposta e molto altro ancora. Fai clic su un'icona per visualizzare i dettagli della fase per quel passaggio.

Ecco una mappa di strumento delle tracce di esempio con i principali segmenti di elaborazione proxy etichettati:

Mappa delle transazioni dello strumento Trace

Legenda della mappa delle transazioni

La seguente tabella descrive l'intento delle icone visualizzate nella mappa delle transazioni. Queste icone contrassegnano ogni passaggio di elaborazione importante del flusso del proxy.

Icone mappa delle transazioni

	L'app client che invia una richiesta a ProxyEndpoint del proxy API.
	I cerchi contrassegnano gli endpoint di transizione nel flusso del proxy. Sono disponibili quando arriva una richiesta dal client, quando la richiesta va al target, quando la risposta arriva da quest'ultima e quando la risposta torna al client.
	Le barre alte indicano l'inizio di un segmento di flusso nel flusso proxy API. I segmenti di flusso sono: richiesta ProxyEndpoint, richiesta TargetEndpoint, risposta TargetEndpoint e risposta ProxyEndpoint. Un segmento include PreFlow, Flussi condizionali e PostFlow. Per ulteriori informazioni, consulta Configurazione dei flussi.
	Indica che le azioni di Analytics si sono verificate in background.
	Un flusso condizionale con valore true. Per un'introduzione ai flussi condizionali, consulta Configurazione dei flussi. Tieni presente che alcune condizioni sono generate da Edge. Ad esempio, quanto segue è un'espressione che Edge utilizza per verificare se si è verificato un errore in ProxyEndpoint: ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Un flusso condizionale che restituisce false. Per un'introduzione ai flussi condizionali, consulta Configurazione dei flussi. Tieni presente che alcune condizioni sono generate da Edge. Ad esempio, di seguito è riportata un'espressione che Edge utilizza per verificare se si è verificato un errore in TargetEndpoint: (((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))
	Norme. Ogni tipo di criterio ha un'icona univoca. Questo è per il criterio AssegnaMessage. Queste icone ti consentono di vedere dove vengono eseguiti i criteri nell'ordine corretto e se l'esito è positivo o negativo. Puoi fare clic sull'icona di un criterio per vedere i risultati dell'esecuzione e se sono previsti o meno. Ad esempio, puoi vedere se il messaggio è stato trasformato correttamente o se viene memorizzato nella cache. La corretta esecuzione dei criteri è indicata chiaramente da segni di spunta. In caso di errore, viene visualizzato un punto esclamativo rosso sull'icona. Suggerimento: presta attenzione alla descrizione comando o alla sequenza temporale per verificare se un criterio sta richiedendo più tempo del previsto.
	Viene visualizzato quando la destinazione del backend è un'applicazione Node.js. Vedi Panoramica di Node.js su Apigee Edge.
	La destinazione del backend chiamata dal proxy API.
	La linea temporale indica il tempo (in millisecondi) impiegato per il completamento del tempo di elaborazione. Il confronto dei segmenti di tempo trascorso ti aiuta a isolare i criteri che richiedono più tempo per l'esecuzione e rallentano le chiamate API.
	L'Epsilon indica un intervallo di tempo inferiore a un millisecondo.
	Disabilitata. Viene visualizzato su un'icona di un criterio quando viene disattivato. Un criterio può essere disabilitato con l'API pubblica. Consulta la sezione Riferimento per la configurazione del proxy API.
	Errore. Appare su un'icona del criterio quando la condizione del passaggio del criterio è falsa (vedi Variabili e condizioni di flusso) o sull'icona del criterio AlzaFault ogni volta che viene eseguito un criterio AlzaFault.
	Ignorata. Viene visualizzata su un'icona del criterio quando il criterio non è stato eseguito perché la condizione del passaggio è valutata come falsa. Per ulteriori informazioni, consulta Variabili e condizioni di flusso.

Informazioni sui dettagli della fase

La parte relativa ai dettagli di fase dello strumento fornisce molte informazioni sullo stato del proxy in ogni fase dell'elaborazione. Di seguito sono riportati alcuni dettagli forniti nei dettagli della fase. Fai clic su una qualsiasi icona nello strumento traccia per visualizzare i dettagli del passaggio selezionato oppure utilizza i pulsanti Avanti/Indietro per passare da un passaggio all'altro.

Dettaglio fase	Descrizione
Endpoint proxy	Indica quale flusso ProxyEndpoint è stato selezionato per l'esecuzione. Un proxy API può avere più endpoint proxy denominati.
Variabili	Elenca le variabili di flusso lette e a cui è stato assegnato un valore da un criterio. Consulta anche Gestione dello stato del proxy con le variabili di flusso. Nota: Il segno uguale (=) indica il valore assegnato alla variabile. Un segno di uguale barrato (≠) indica che non è stato possibile assegnare un valore alla variabile perché è di sola lettura oppure si è verificato un errore nell'esecuzione del criterio. Un campo vuoto indica che il valore della variabile è stato letto.
Intestazioni richiesta	Elenca le intestazioni delle richieste HTTP.
Richiedi contenuti	Mostra il corpo della richiesta HTTP.
Proprietà	Le proprietà rappresentano lo stato interno del proxy API. Questi campi non vengono mostrati per impostazione predefinita.
Endpoint di destinazione	Indica quale TargetEndpoint è stato selezionato per l'esecuzione.
Intestazioni della risposta	Elenca le intestazioni della risposta HTTP.
Contenuto della risposta	Mostra il corpo della risposta HTTP.
PostClientFlow	Mostra le informazioni su PostClientFlow, che viene eseguito dopo che la richiesta viene restituita all'app client che ha inviato la richiesta. È possibile collegare solo i criteri MessageLogging a PostClientFlow. Al momento PostClientFlow viene utilizzato principalmente per misurare l'intervallo di tempo tra i timestamp di inizio e fine del messaggio di risposta.

Perfezionare l'acquisizione dei messaggi utilizzando i filtri

Puoi filtrare le richieste da visualizzare nello strumento Trace specificando i valori dell'intestazione e/o dei parametri di query. I filtri ti consentono di scegliere come target chiamate specifiche che potrebbero causare problemi. Ad esempio, potresti dover concentrarti sulle richieste con contenuti specifici o su richieste provenienti da app o partner specifici. Puoi filtrare in base a:

• Intestazioni HTTP: limita la traccia solo alle chiamate che contengono un'intestazione specifica. Si tratta di un buon modo per aiutarti a risolvere i problemi. Puoi inviare un'intestazione allo sviluppatore dell'app e chiedergli di includerla nella chiamata che causa i problemi. Apigee Edge registrerà solo le chiamate con quell'intestazione specifica, in modo che tu possa esaminare i risultati.
• Parametri di query: vengono registrate solo le chiamate con un valore specifico di un parametro.

Informazioni importanti sulla funzionalità Filtro

• Devi riavviare la sessione di Trace dopo aver specificato i parametri di filtro nei campi del filtro.
• I parametri di filtro sono collegati tra loro mediante l'operatore AND. Per una corrispondenza corretta, tutte le coppie di nome/valore della query e/o dell'intestazione devono essere presenti nella richiesta.
• La corrispondenza di pattern non è supportata nello strumento Filtri.
• I parametri e i valori di filtro sono sensibili alle maiuscole.

Come creare un filtro di traccia

1. Se una sessione di traccia è in esecuzione, interrompila facendo clic su Interrompi sessione di traccia.
2. Fai clic su Filtri nell'angolo in alto a sinistra dello strumento Trace per espandere il campo Filtri.
   
   
   
3. Nel campo Filtri, specifica il parametro di ricerca e/o i valori dell'intestazione in base a cui vuoi applicare il filtro. In questo esempio, specifichiamo due parametri di ricerca in base ai quali applicare il filtro. Affinché una corrispondenza vada a buon fine, la richiesta deve contenere entrambi i parametri.
   
   
   
4. Avvia la sessione di traccia.
5. Chiama le API. Solo le richieste che includono tutte le intestazioni e/o i parametri di query specificati generano una corrispondenza riuscita.

Nell'esempio precedente, questa chiamata API verrà visualizzata in Trace:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

Tuttavia, ciò non comporterà quanto segue:

http://docs-test.apigee.net/cats?name=Penny

Debug con Trace

Trace ti consente di visualizzare molti dettagli interni relativi a un proxy API. Ad esempio:

• Puoi vedere rapidamente quali criteri vengono eseguiti correttamente o con problemi.
• Supponiamo che tu abbia notato su una delle dashboard di Analytics che una delle tue API sta riscontrando una diminuzione insolita del rendimento. Ora puoi utilizzare Trace per identificare il punto in cui si verifica il collo di bottiglia. Trace fornisce il tempo, in millisecondi, necessario per il completamento di ogni passaggio di elaborazione. Se noti che un passaggio richiede troppo tempo, puoi intraprendere azioni correttive.
• Esaminando i dettagli della fase, puoi verificare le intestazioni che vengono inviate al backend, visualizzare le variabili impostate dai criteri e così via.
• Verificando il percorso di base, puoi assicurarti che un criterio esegua il routing del messaggio al server corretto.

Selezione delle opzioni di visualizzazione

Scegli le opzioni di visualizzazione per la sessione di traccia.

Opzione	Descrizione
Mostra criteri disattivati	Mostra tutti i criteri disattivati. Un criterio può essere disattivato con l'API pubblica. Consulta la pagina di riferimento sulla configurazione del proxy API.
Mostra fasi ignorate	Mostra le fasi saltate. Si verifica una fase saltata quando il criterio non è stato eseguito perché la condizione del passaggio è valutata come falsa. Per ulteriori informazioni, consulta Variabili e condizioni di flusso.
Mostra tutte le FlowInfo	Rappresentare le transizioni all'interno di un segmento di flusso.
Confronta automaticamente la fase selezionata	Confronta la fase selezionata con quella precedente. Disattiva questa opzione per visualizzare solo la fase selezionata.
Mostra variabili	Mostra o nascondi le variabili lette e/o a cui è stato assegnato un valore.
Mostra proprietà	Le proprietà rappresentano lo stato interno del proxy API. (Nascosto per impostazione predefinita).

Download dei risultati delle tracce in corso...

Puoi scaricare un file XML di risultati delle tracce non elaborati per la visualizzazione e la ricerca offline in un editor di testo. Il file mostra i dettagli completi della sessione di ascolto, compresi i contenuti di tutte le intestazioni, le variabili e i criteri.

Per scaricare, fai clic su Scarica sessione di traccia.

Visualizzazione delle richieste come curl

Dopo aver tracciato una chiamata API effettuata a un server di destinazione, puoi visualizzare la richiesta come comando curl. Questa procedura è particolarmente utile per il debug per due motivi:

• Il proxy API può modificare la richiesta, pertanto è utile vedere come la richiesta dal proxy al server di destinazione differisce dalla richiesta originale. Il comando curl rappresenta la richiesta modificata.
• Per payload di messaggi più grandi, curl consente di visualizzare le intestazioni HTTP e i contenuti dei messaggi in un'unica posizione. Attualmente esiste un limite di circa 1000 caratteri. Per un suggerimento su come superare questo limite, consulta questo post della scheda Community.

Per motivi di sicurezza, la funzionalità curl maschera l'intestazione HTTP Authorization.

Per visualizzare le richieste come curl dopo che una chiamata API arriva in Trace, seleziona la fase "Richiesta inviata al server di destinazione" nel diagramma della mappa delle transazioni, quindi fai clic sul pulsante Mostra curl nella colonna "Richiesta inviata al server di destinazione" nel riquadro dei dettagli della fase.

Supporto Apigee per l'utilizzo di Trace

Per impostazione predefinita, Apigee Edge consente all'assistenza Apigee di utilizzare lo strumento Trace sui proxy API per fornire supporto. Puoi disattivare questa opzione in qualsiasi momento. Tuttavia, la disattivazione di questa opzione potrebbe limitare la capacità dell'assistenza Apigee di fornirti assistenza.

Per impedire all'assistenza Apigee di utilizzare lo strumento Trace:

1. Accedi a https://apigee.com/edge.
2. Seleziona Amministrazione > Privacy e sicurezza nella barra di navigazione a sinistra.
3. Fai clic sul pulsante di attivazione/disattivazione Attiva il supporto di Apigee per tracciare per disabilitare l'utilizzo dello strumento Trace da parte dell'assistenza Apigee.