Usare lo strumento Traccia

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

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 analizzare i dettagli di ogni passaggio tramite un flusso proxy API.

Come utilizzare Trace

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

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

   Edge

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

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

   Classic Edge (Private Cloud)

   Per accedere alla pagina dei proxy API utilizzando la UI 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 l'API che vuoi tracciare sia implementata.
4. Fai clic su Trace per passare alla visualizzazione dello strumento Trace.
5. Utilizza il menu a discesa Deployment da tracciare per selezionare l'ambiente di deployment e la revisione del proxy che vuoi tracciare.
6. Fai clic su Avvia sessione di traccia. Quando la sessione di Trace è attiva, il proxy API registra i dettagli di ogni passaggio nella pipeline di elaborazione. Durante l'esecuzione della sessione di tracciamento, i messaggi e i dati contestuali vengono acquisiti dal traffico in tempo reale.
   

   

7. Se non hai traffico live che passa attraverso il proxy, invia semplicemente una richiesta all'API. Puoi utilizzare lo strumento che preferisci per inviare la richiesta, ad esempio curl, Postman o qualsiasi altro strumento che ti è familiare. In alternativa, puoi inviare la richiesta direttamente dallo strumento Traccia. Basta inserire l'URL e fare clic su Invia. Nota:puoi inviare solo una richiesta GET dallo strumento Trace, ma non una richiesta POST.
   
   Nota:una sessione di 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 tracciamento si interrompe automaticamente dopo 10 minuti se non la interrompi manualmente.
   
8. Quando hai acquisito un numero sufficiente di richieste, fai clic su Interrompi sessione di tracciamento.
9. Nel menu a sinistra viene visualizzato un elenco delle transazioni di richiesta/risposta acquisite. Fai clic su una delle transazioni per visualizzare i risultati dettagliati.

Come leggere una traccia

Lo strumento di tracciamento è composto da due parti principali: la mappa delle transazioni e i dettagli delle fasi:

• La mappa delle transazioni utilizza icone per contrassegnare ogni passaggio importante che si verifica durante una transazione proxy API, inclusi l'esecuzione dei criteri, i passaggi condizionali e le transizioni. Passa il mouse sopra qualsiasi icona per visualizzare le 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 nella parte inferiore.
• La sezione Dettagli 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 esempio dello strumento di tracciamento con i segmenti principali di elaborazione del proxy etichettati:

Mappa delle transazioni dello strumento Trace

Legenda della mappa delle transazioni

La tabella seguente descrive lo scopo delle icone che vedrai nella mappa delle transazioni. Queste icone contrassegnano ciascuno dei passaggi di elaborazione importanti nel flusso del proxy.

Icone della 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 presenti quando arriva una richiesta dal client, quando la richiesta viene inviata alla destinazione, quando la risposta torna dalla destinazione e quando la risposta viene inviata di nuovo al client.
	Le barre alte indicano l'inizio di un segmento di flusso nel flusso del proxy API. I segmenti del flusso sono: richiesta ProxyEndpoint, richiesta TargetEndpoint, risposta TargetEndpoint e risposta ProxyEndpoint. Un segmento include PreFlow, Conditional Flows e PostFlow. Per ulteriori informazioni, consulta la sezione Configurazione dei flussi.
	Indica che le azioni di Analytics sono state eseguite in background.
	Un flusso condizionale che restituisce true. Per un'introduzione ai flussi condizionali, vedi Configurazione dei flussi. Tieni presente che alcune condizioni sono generate da Edge. Ad esempio, la seguente è 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, vedi Configurazione dei flussi. Tieni presente che alcune condizioni sono generate da Edge. Ad esempio, la seguente è 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 policy ha un'icona univoca. Questo è per il criterio AssignMessage. Queste icone ti consentono di vedere dove vengono eseguite le policy nell'ordine corretto e se l'esecuzione è riuscita o meno. Puoi fare clic su un'icona della norma per visualizzare i risultati della sua esecuzione e se sono previsti o meno. Ad esempio, puoi vedere se il messaggio è stato trasformato correttamente o se è in fase di memorizzazione nella cache. L'esecuzione corretta delle norme è indicata chiaramente da segni di spunta. In caso di errore, sull'icona viene visualizzato un punto esclamativo rosso. Suggerimento: presta attenzione alla descrizione comando o alla cronologia per vedere se l'applicazione di una norma richiede più tempo del previsto.
	Viene visualizzato quando la destinazione di backend è un'applicazione Node.js. Consulta Panoramica di Node.js su Apigee Edge.
	La destinazione di backend chiamata dal proxy API.
	La cronologia indica la durata (in millisecondi) dell'elaborazione. Il confronto dei segmenti di tempo trascorso ti aiuta a isolare i criteri che richiedono più tempo per l'esecuzione e che rallentano le chiamate API.
	Epsilon indica un intervallo di tempo inferiore a un millisecondo.
	Disabilitata. Viene visualizzata su un'icona di policy quando una policy è disattivata. Un criterio può essere disattivato con l'API pubblica. Consulta il riferimento per la configurazione dei proxy API.
	Errore. Viene visualizzato sull'icona di un criterio quando la condizione del passaggio del criterio restituisce il valore false (vedi Variabili e condizioni del flusso), o sull'icona del criterio RaiseFault ogni volta che viene eseguito un criterio RaiseFault.
	Ignorata. Viene visualizzato su un'icona di policy quando la policy non è stata eseguita perché la condizione del passaggio è stata valutata come false. Per ulteriori informazioni, consulta la sezione Variabili e condizioni del flusso.

Comprendere i dettagli della fase

La sezione Dettagli fase dello strumento fornisce molte informazioni sullo stato del proxy in ogni fase di elaborazione. Ecco alcuni dei dettagli forniti nei dettagli della fase. Fai clic su qualsiasi icona nello strumento di traccia per visualizzare i dettagli del passaggio selezionato oppure utilizza i pulsanti Avanti/Indietro per spostarti da un passaggio all'altro.

Perfezionare l'acquisizione dei messaggi utilizzando i filtri

Puoi filtrare le richieste visualizzate nello strumento Trace specificando i valori dei parametri di intestazione e/o 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 provenienti da partner o app specifici. Puoi filtrare in base a:

• Intestazioni HTTP: limita la traccia solo alle chiamate che contengono un'intestazione specifica. Questo è 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 problemi. Apigee Edge registra solo le chiamate con quell'intestazione specifica, in modo che tu possa esaminare i risultati.
• Parametri di query: verranno 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 del filtro sono combinati con l'operatore AND. Tutte le coppie query e/o nome/valore dell'intestazione specificate devono essere presenti nella richiesta per una corrispondenza riuscita.
• La corrispondenza dei pattern non è supportata nello strumento Filtri.
• I parametri e i valori dei filtri 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 Traccia per espandere il campo Filtri.
   
   
   
3. Nel campo Filtri, specifica i valori dei parametri di query e/o delle intestazioni in base ai quali vuoi filtrare i risultati. In questo esempio, specifichiamo due parametri di query in base ai quali filtrare. Entrambi i parametri devono essere presenti nella richiesta per una corrispondenza riuscita.
   
   
   
4. Avvia la sessione di traccia.
5. Chiama le tue API. Solo le richieste che includono tutte le intestazioni e/o i parametri di query specificati producono una corrispondenza riuscita.

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

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

Tuttavia, questa operazione non:

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

Debug con Trace

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

• Puoi vedere a colpo d'occhio quali criteri vengono eseguiti correttamente o meno.
• Supponiamo che in una delle dashboard Analytics tu abbia notato che il rendimento di una delle tue API sta diminuendo in modo anomalo. Ora puoi utilizzare Trace per identificare il punto in cui si verifica il collo di bottiglia. La traccia indica il tempo, in millisecondi, necessario per il completamento di ogni fase di elaborazione. Se noti che un passaggio richiede troppo tempo, puoi intraprendere un'azione correttiva.
• Esaminando i dettagli della fase, puoi controllare le intestazioni inviate al backend, visualizzare le variabili impostate dalle policy e così via.
• Verificando il percorso di base, puoi assicurarti che un criterio indirizzi il messaggio al server corretto.

Selezionare le opzioni di visualizzazione

Scegli le opzioni di visualizzazione per la sessione di tracciamento.

Download dei risultati della traccia

Puoi scaricare un file XML dei risultati della traccia non elaborati per visualizzarli e cercarli offline in un editor di testo. Il file mostra i dettagli completi della sessione di ascolto, inclusi i contenuti di tutte le intestazioni, le variabili e le policy.

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. Questo è particolarmente utile per il debug per un paio di motivi:

• Il proxy API può modificare la richiesta, quindi è utile vedere in che modo la richiesta dal proxy al server di destinazione differisce dalla richiesta originale. Il comando curl rappresenta la richiesta modificata.
• Per i payload dei messaggi più grandi, curl ti consente di visualizzare le intestazioni HTTP e i contenuti dei messaggi in un unico posto. Al momento è previsto un limite di circa 1000 caratteri. Per un suggerimento su come superare questo limite, consulta questo post della community.

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

Per visualizzare le richieste come curl dopo che una chiamata API viene visualizzata 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 Dettagli fase.

Utilizzo di Trace da parte dell'assistenza Apigee

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.