Utilizzo del debug

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa sezione descrive come creare e gestire le sessioni di debug e visualizzare i dati di richiesta e risposta utilizzando l'interfaccia utente e l'API Apigee.

Utilizza Debug offline per visualizzare e analizzare le sessioni di debug scaricate in precedenza.

Creazione di una sessione di debug

Lo strumento di debug è semplice da usare. Avvia una sessione di debug, quindi effettua una chiamata API ad Apigee e visualizza i dati della richiesta e della risposta nell'interfaccia utente.

Crea una sessione di debug utilizzando la UI o l'API Apigee, come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per creare una sessione di debug:

  1. Nella console Google Cloud , vai alla pagina Apigee > Sviluppo proxy > Proxy API.

    Vai a Proxy API

  2. Seleziona il proxy API di cui vuoi eseguire il debug. Viene visualizzato il riquadro Panoramica dell'editor proxy.
  3. Fai clic sulla scheda Debug.
  4. Fai clic su Avvia sessione di debug. Viene visualizzato il riquadro Avvia sessione di debug.

  5. Nel riquadro Avvia sessione di debug:

    1. Seleziona l'ambiente in cui vuoi eseguire la sessione di debug.

    2. (Facoltativo) Dall'elenco a discesa Filtro, seleziona un filtro da applicare a tutte le transazioni nella sessione di debug che stai creando. Il valore predefinito è None (All transactions), che include tutte le transazioni nei dati di debug.

      Per informazioni sull'utilizzo dei filtri, consulta Utilizzo dei filtri in una sessione di debug. Per informazioni sui filtri integrati, consulta Utilizzo dei filtri predefiniti.

    3. Fai clic su Avvia.

La UI di Apigee ora mostra il riquadro Sessione di debug in corso.

Fai clic per ingrandire l'immagine nuova sessione di debug

La sessione di debug registra le richieste per 10 minuti o fino a quando non vengono acquisite 15 richieste. Puoi modificare il limite di 10 minuti se crei la sessione di debug utilizzando l'API. Il campo Termina tra mostra il tempo rimanente della sessione.

Non vedrai alcuna informazione nel riquadro Debug finché non invii una richiesta al proxy di cui stai eseguendo il debug nell'ambiente selezionato per la sessione di debug.

Dopo aver inviato la richiesta, questa viene visualizzata nel riquadro dell'elenco Transazioni. L'elenco Transazioni viene aggiornato ogni cinque secondi.

Fai clic per ingrandire l'immagine richiesta nell'elenco delle transazioni

Per visualizzare o copiare l'output della transazione:

  1. Nell'elenco Transazioni, fai clic su Visualizza output della transazione. Viene visualizzato il riquadro Output transazione.
  2. Fai clic su una singola transazione o su Tutte le transazioni.
  3. Fai clic su Copia per copiare l'output della transazione negli appunti.
  4. Fai clic su Chiudi.

API

Per creare una sessione di debug utilizzando l'API, invia una richiesta POST alla seguente risorsa: 

https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/debugsessions

In via facoltativa, puoi:

L'esempio seguente mostra come creare una sessione di debug utilizzando l'API.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions" \
      -X POST \
      -H "Authorization: Bearer $TOKEN"

Dove $TOKEN è impostato sul tuo token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente che puoi utilizzare, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

Di seguito è riportato un esempio di risposta:

{
      "name":"56382416-c4ed-4242-6381-591bbf2788cf",
      "validity":300,
      "count":10,
      "tracesize":5120,
      "timeout":"600"
    }

Le richieste successive al proxy API (fino al raggiungimento della durata della sessione o del numero massimo di richieste) verranno valutate e potenzialmente archiviate nei dati della sessione di debug.

Per saperne di più, consulta l'API Create debug session.

Impostazione della durata di una sessione di debug utilizzando l'API

Per impostare la durata di una sessione di debug utilizzando l'API, includi quanto segue come payload nella richiesta di creazione della sessione di debug:

{
      "timeout":"debug_session_length_in_seconds"
    }

L'esempio seguente crea una sessione di debug di soli 42 secondi:

curl https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions"
      -X "POST" \
      -H "Authorization: Bearer $TOKEN" \
      -d ' {
        "timeout":"42"
      } '

Puoi impostare la timeout di una sessione solo nelle richieste di creazione di sessioni di debug; non puoi modificare la durata di una sessione dopo averla creata.

Il valore predefinito di timeout è 300 (5 minuti). Il valore massimo è 600 secondi (10 minuti).

Copia l'URL del proxy

L'URL del proxy viene utilizzato per inviare richieste al proxy API.

Per trovare e copiare l'URL del proxy:

  1. Nel riquadro Debug session (Sessione di debug), campo URL, fai clic su Copy (Copia).
  2. Se non è aperta una sessione di debug:

    1. Nella console Google Cloud , vai alla pagina Apigee > Gestione > Ambienti > Gruppi di ambienti.

      Vai a Gruppi di ambiente

    2. L'URL è il nome host del rispettivo ambiente con cui vuoi eseguire la sessione di debug. Selezionalo e poi copialo.

Per selezionare un URL proxy diverso:

  1. Nel riquadro Sessione di debug, campo URL, fai clic su Modifica.
  2. Apporta le modifiche che vuoi e fai clic su Aggiorna.
  3. Se non è aperta una sessione di debug:
    1. Trova l'URL del proxy.
    2. Fai clic su Altro, quindi su Modifica.
    3. Apporta le modifiche che vuoi e fai clic su Aggiorna.

Avvio di un'altra sessione di debug nella UI

Puoi creare un numero qualsiasi di sessioni di debug nell'interfaccia utente.

Durante una sessione di debug attiva, puoi avviare un'altra sessione nella UI di Apigee. Per farlo, fai clic su Chiudi nel riquadro Sessione di debug:

Fai clic per ingrandire l'immagine Chiudi e torna al riquadro Avvia una sessione di debug

La UI torna al riquadro Avvia una sessione di debug, dove puoi avviare una nuova sessione di debug.

Quando termina una sessione di debug?

Non puoi semplicemente interrompere una sessione di debug attiva. Tuttavia, puoi eliminare i dati di una sessione attiva, come descritto in Eliminare i dati della sessione di debug.

Quando crei una sessione di debug, due proprietà determinano quando termina:

  • timeout: il periodo di tempo durante il quale raccogli i dati durante una sessione. La durata predefinita dipende da come hai avviato la sessione (tramite l'interfaccia utente o l'API). Il valore massimo è 600 secondi (o 10 minuti).
  • count: il numero massimo di richieste registrate in una singola sessione per processore di messaggi. Poiché il numero di processori di messaggi nella maggior parte dei cluster è variabile, gli effetti del conteggio possono essere imprevedibili. Apigee non consiglia di personalizzare questa impostazione.

Quando viene raggiunto il timeout o il conteggio, la sessione di debug per quel processore di messaggi termina.

I seguenti termini vengono utilizzati per descrivere lo stato di una sessione di debug:

  • Una sessione attiva è una sessione di debug che non ha ancora raggiunto il timeout o superato il conteggio. Una sessione attiva continua a registrare i dati delle richieste che non vengono filtrate.
  • Una sessione completata è una sessione di debug che ha raggiunto il timeout o ha superato il conteggio. Una sessione completata non registra più i dati relativi alle nuove richieste e i relativi dati vengono eliminati entro 24 ore dal momento in cui la sessione è terminata.

Come leggere una sessione di debug

Questa sezione fornisce una panoramica di una sessione di debug.

Vedi anche:

Lo strumento di debug è composto da due parti principali: il riquadro delle transazioni e i dettagli della fase:

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

Riquadro delle transazioni

Il riquadro della transazione mostra i passaggi della richiesta e della risposta.

Di seguito è riportato un riquadro di transazione di esempio dello strumento di debug con i principali segmenti di elaborazione del proxy etichettati:

Fai clic per ingrandire l'immagine Diagramma di debug che mostra l'inizio della richiesta proxy, l'inizio della richiesta di destinazione, l'inizio della risposta di destinazione, l'inizio della risposta proxy e l'inizio del flusso client post-proxy

Legenda del riquadro delle transazioni

Di seguito sono descritte le icone nel riquadro delle transazioni:

Questa sezione descrive le icone nel riquadro delle transazioni:

Icone delle norme

Ogni tipo di policy ha un'icona univoca. Queste icone ti consentono di vedere dove vengono eseguite le policy nell'ordine corretto e se l'esecuzione è andata a buon fine o meno. Puoi fare clic sull'icona di una policy per visualizzare i risultati della sua esecuzione e verificare se sono quelli previsti o meno. Ad esempio, puoi vedere se il messaggio è stato trasformato correttamente o se è stato memorizzato nella cache.

Le policy standard migliorano le API per controllare il traffico, migliorare le prestazioni, applicare le misure di sicurezza e aumentare l'utilità delle API, senza richiedere la scrittura di codice o la modifica dei servizi di backend.

Le policy estensibili ti consentono di aggiungere logica personalizzata ai proxy API. Puoi utilizzare queste policy per aggiungere funzionalità non fornite dalle policy standard.

Per saperne di più su policy e categorie, consulta Panoramica di riferimento delle policy.

Per filtrare la tabella:

  • Seleziona un tipo di policy e/o una categoria di policy.
  • Fai clic sull'intestazione della colonna Nome per ordinare la tabella in base al nome della policy.
  • Digita una parola chiave per cercare il nome di una policy.

Tipo di criterio

Categoria norma

Icona Nome Tipo Categoria
Icona della policy LLMTokenQuota Policy LLMTokenQuota Estensibile AI
chat_spark Policy PromptTokenLimit Estensibile AI
shield_spark Policy SanitizeUserPrompt Estensibile AI
shield_spark Policy SanitizeModelResponse Estensibile AI
async Policy SemanticCacheLookup Estensibile AI
async Policy SemanticCachePopulate Estensibile AI
manage_search Politica di analisi del flusso di dialogo Estensibile Dialog flow
chat_add_on Imposta la policy di risposta del flusso di dialogo Estensibile Flusso di dialogo
stacked_line_chart Policy DataCapture Estensibile Estensione
display_external_input Policy ExternalCallout Standard Estensione
flowsheet Policy FlowCallout Estensibile Estensione
automation Policy IntegrationCallout Estensibile Estensione
Icona della policy JavaCallout Policy JavaCallout Estensibile Estensione
Icona delle norme relative a JavaScript Policy JavaScript Estensibile Estensione
add_notes Policy MessageLogging Estensibile Estensione
chat_paste_go Policy PublishMessage Standard Estensione
Icona della policy PythonScript Policy PythonScript Estensibile Estensione
integration_instructions Policy ServiceCallout Estensibile Estensione
automation Policy SetIntegrationRequest Estensibile Estensione
waterfall_chart Policy TraceCapture Estensibile Estensione
cloud_done Policy AccessEntity Estensibile Mediazione
account_tree Policy AsseretCondition Standard Mediazione
edit_square Policy AssignMessage Estensibile Mediazione
login Policy ExtractVariables Estensibile Mediazione
Icona della policy GraphQL Policy GraphQL Standard Mediazione
sync_alt Policy HTTPModifier Standard Mediazione
sync_alt Policy JSONtoXML Standard Mediazione
account_tree Policy KeyValueMapOperations Estensibile Mediazione
sync_alt Policy MonetizationLimitsCheck Estensibile Mediazione
cloud_done Policy OASValidation Standard Mediazione
report Policy RaiseFault Standard Mediazione
sync_alt Policy ReadPropertySet Standard Mediazione
cloud_done Policy SOAPMessageValidation Standard Mediazione
sync_alt Policy XMLtoJSON Standard Mediazione
cloud_done Policy XSLTransform Estensibile Mediazione
lock Policy AccessControl Standard Sicurezza
security Policy BasicAuthentication Estensibile Sicurezza
connect_without_contact Policy CORS Standard Sicurezza
lock Policy DecodeJWS Estensibile Sicurezza
lock Policy DecodeJWT Standard Sicurezza
passkey Policy DeleteOAuthV2Info Estensibile Sicurezza
lock Policy GenerateSamlAssertion Estensibile Sicurezza
lock Policy GenerateJWS Estensibile Sicurezza
lock Policy GenerateJWT Estensibile Sicurezza
passkey Policy GetOAuthV2Info Estensibile Sicurezza
lock Policy HMAC Standard Sicurezza
security Policy JSONThreatProtection Estensibile Sicurezza
passkey Policy OAuthV2 Estensibile Sicurezza
security Policy RegularExpressionProtection Estensibile Sicurezza
passkey Policy RevokeOAuthV2 Estensibile Sicurezza
passkey Policy SetOAuthV2Info Estensibile Sicurezza
lock Policy ValidateSamlAssertion Estensibile Sicurezza
chiave Policy VerifyAPIKey Estensibile Sicurezza
passkey Verifica la policy IAM Estensibile Sicurezza
lock Policy VerifyJWS Estensibile Sicurezza
lock Policy VerifyJWT Standard Sicurezza
security Policy XMLThreatProtection Estensibile Sicurezza
cached Policy InvalidateCache Estensibile Gestione del traffico
cached Policy LookupCache Estensibile Gestione del traffico
cached Policy PopulateCache Estensibile Gestione del traffico
icona delle norme relative alle quote Criteri per le quote Estensibile Gestione del traffico
repartition Policy ResetQuota Estensibile Gestione del traffico
cached Policy ResponseCache Estensibile Gestione del traffico
emergency_home Policy SpikeArrest Standard Gestione del traffico

Altre icone

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

Per filtrare la tabella:

  • Seleziona un tipo di icona.
  • Fai clic sull'intestazione della colonna Nome per ordinare la tabella in base al nome dell'icona.
  • Digita una parola chiave per cercare il nome di un'icona.

Tipo di icona

Icona Nome Tipo Descrizione
monitor App client Transazione standard L'app client che invia una richiesta al ProxyEndpoint del proxy API.
Cerchia Endpoint di transizione Transazione standard Il cerchio contrassegna gli endpoint di transizione nel flusso del proxy. Sono presenti quando una richiesta proviene dal client, quando la richiesta va alla destinazione, quando la risposta torna dalla destinazione e quando la risposta torna al client.
stat_0 Segmento di flusso Transazione standard

Il rombo indica l'inizio di un segmento di flusso nel flusso del 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 Flussi condizionali.

icona di condizione vera Flusso condizionale true Transazione standard

Un flusso condizionale che restituisce true (come un'istruzione if che ha restituito true). Per un'introduzione ai flussi condizionali, consulta Flussi condizionali.

Tieni presente che alcune condizioni sono generate da Apigee. Ad esempio, di seguito è riportata un'espressione utilizzata da Apigee per verificare se si è verificato un errore nel ProxyEndpoint:

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

icona di condizione falsa Flusso condizionale falso Transazione standard

Un flusso condizionale che restituisce false. Per un'introduzione ai flussi condizionali, consulta Flussi condizionali.

Tieni presente che alcune condizioni sono generate da Apigee. Ad esempio, la seguente è un'espressione utilizzata da Apigee 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)))

icona informazioni sul flusso Informazioni sul flusso Transazione standard Rappresenta le informazioni contestuali sull'esecuzione del proxy API, che variano a seconda del punto del flusso. Sono inclusi i dettagli sulla configurazione del proxy, lo stato di esecuzione corrente (ad es. PreFlow, PostFlow, flow hook), i dettagli sull'esecuzione delle policy e le variabili compilate durante l'esecuzione delle policy, per indicare lo stato specifico del proxy in quel momento.
done_all Esecuzione flusso Transazione standard Contrassegna l'inizio o la fine dell'esecuzione di un flusso, indicando il periodo di tempo di un segmento di flusso distinto, per delimitare visivamente i confini del flusso e indicare la sequenza di esecuzione del flusso.
commit Elaborazione del flusso Transazione standard Indica l'elaborazione attiva all'interno di un flusso, che rappresenta il periodo durante il quale vengono eseguite le policy e la logica del flusso.
bar_chart Dati acquisiti dall'analisi di Apigee Transazione standard Indica che le azioni di Analytics si sono verificate in background.
location_on Servizio di backend Transazione standard Servizio di backend che riceve la richiesta. Il target di backend chiamato dal proxy API.
icona disattivata Disabilitato Stato passaggio Viene visualizzato sull'icona di una policy quando questa è disabilitata. Un criterio può essere disattivato con l'API pubblica. Consulta il riferimento alla configurazione del proxy API.
icona di errore Errore Stato passaggio Viene visualizzato sull'icona di una policy quando la condizione del passaggio della policy restituisce false (consulta Condizioni con variabili di flusso) o sull'icona della policy RaiseFault ogni volta che viene eseguita una policy RaiseFault.
icona di salto Ignorato Stato passaggio Viene visualizzato su un'icona della policy quando la policy non è stata eseguita perché la condizione del passaggio è stata valutata come falsa. Per ulteriori informazioni, consulta Condizioni con variabili di flusso.

Riquadro dei dettagli della fase

Il riquadro dei dettagli della fase fornisce informazioni sullo stato del proxy in ogni fase di elaborazione.

Il riquadro dei dettagli della fase fornisce molte informazioni sullo stato del proxy in ogni fase di elaborazione. Ecco alcuni dei dettagli forniti. Fai clic su un'icona qualsiasi nello strumento di debug per visualizzare i dettagli del passaggio selezionato oppure utilizza i pulsanti > Avanti o < Indietro per passare da un passaggio all'altro.

La tabella seguente descrive i dettagli forniti nel riquadro dei dettagli della fase.

Dettagli della fase Descrizione
Variabili

Elenca le variabili di flusso che sono state lette e a cui è stato assegnato un valore da una policy. Consulta anche Utilizzo delle variabili di flusso.

Intestazioni delle richieste 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 non vengono mostrati per impostazione predefinita.
Endpoint di destinazione Indica quale TargetEndpoint è stato selezionato per l'esecuzione.
Intestazioni delle risposte Elenca le intestazioni della risposta HTTP.
Contenuto della risposta Mostra il corpo della risposta HTTP.

Cronologia

La cronologia indica il tempo di elaborazione (in millisecondi) necessario per il completamento. Il confronto dei segmenti di tempo trascorso ti aiuta a isolare le policy che richiedono più tempo per l'esecuzione e che rallentano le chiamate API.

Epsilon indica un intervallo di tempo inferiore a un millisecondo.

Fai clic per ingrandire l'immagine Timeline nell'interfaccia utente di Debug v2

Espansione e compressione dei gruppi

Questa sezione descrive come espandere e comprimere i gruppi nel riquadro Transazione.

I passaggi della transazione, sia per la richiesta che per la risposta, sono raggruppati in base a come sono stati configurati in precedenza nella scheda Sviluppa, per flusso condiviso. Ad esempio: pre-proxy, post-proxy, pre-target e post-target.

Ogni raggruppamento mostra chiaramente le policy, le condizioni, i flussi condivisi e le informazioni sui flussi pertinenti.

I flussi condivisi sono raggruppati e compressi per impostazione predefinita.

Nel riquadro Transazione sono disponibili le seguenti azioni:

Elemento Nome Descrizione
cursore espandi tutto
<img <="" alt="collapse all slider" class="screenshot" src="/static/apigee/docs/api-platform/debug/images/collapse_all_slider.png" td="" width="" /> 		Espandi tutto
Comprimi tutto		 Espandi o comprimi tutti i gruppi.
icona Espandi gruppo
icona Comprimi gruppo 		Espandi
Comprimi		 Espandere o comprimere un gruppo.

Vedi anche:

La ricerca ti consente di trovare una parola o una frase nella richiesta o nella risposta.

La ricerca ti consente di trovare una parola o una frase nella richiesta o nella risposta.

Tieni presente quanto segue:

  • La ricerca non distingue tra maiuscole e minuscole
  • La ricerca si applica a una singola transazione, ovvero non esegue la ricerca in tutte le transazioni dell'intera sessione di debug.
  • La ricerca espande le sezioni compresse, ma non mostra informazioni sui nodi esclusi dalle selezioni di Opzioni di visualizzazione.

Per effettuare una ricerca:

  1. Digita il testo nella casella di ricerca.

  2. Premi Invio.

    I risultati di ricerca sono evidenziati nel riquadro Transazione e nel riquadro Dettagli fase.

  3. Fai clic su keyboard_arrow_up Indietro o keyboard_arrow_down Avanti per passare al passaggio successivo o precedente.
Fai clic per ingrandire l'immagine Risultati di ricerca nell'interfaccia utente di Debug v2

Zoom

Lo zoom ti consente di controllare la visualizzazione del riquadro Transazione.

Lo zoom controlla la visualizzazione del riquadro Transazione come segue:

Fai clic per ingrandire l'immagine Controlli di zoom di Debug v2
Icona Descrizione
100% Livello di zoom attuale. Il valore predefinito è 100%.
fit_screen Adatta allo schermo
zoom_in Aumenta zoom
zoom_out Diminuisci lo zoom
youtube_searched_for Reimpostazione zoom

Debug con lo strumento di debug

Il debug ti consente di visualizzare molti dettagli interni su un proxy API. Ad esempio:

  • Puoi vedere a colpo d'occhio quali policy vengono eseguite correttamente o non vanno a buon fine.
  • Supponiamo che tu abbia notato tramite una delle dashboard di Analytics che una delle tue API sta riscontrando un calo insolito delle prestazioni. Ora puoi utilizzare Debug per identificare dove si verifica il collo di bottiglia. Il debug indica il tempo, in millisecondi, necessario per il completamento di ogni passaggio di elaborazione. Se un passaggio richiede troppo tempo, puoi intraprendere un'azione correttiva.
  • Puoi controllare le intestazioni inviate al backend, visualizzare le variabili impostate dalle policy e così via.
  • Verificando il percorso di base, puoi assicurarti che una policy indirizzi il messaggio al server corretto.

Filtrare i dati in una sessione di debug

Quando crei una sessione di debug, puoi aggiungere un filtro alla sessione in modo che Apigee restituisca solo i dati che ti interessano. Un filtro è un'istruzione condizionale che Apigee valuta rispetto ai messaggi di richiesta e risposta per determinare se i dati di debug devono essere inclusi nella sessione di debug. Ad esempio, puoi filtrare tutte le richieste con un codice di risposta HTTP inferiore a 599 o confrontare i valori della richiesta con variabili personalizzate.

Tieni presente quanto segue:

  • Le richieste che non sono incluse in una sessione di debug perché filtrate non vengono conteggiate ai fini del numero massimo di transazioni nella sessione di debug.
  • Apigee non supporta l'aggiunta di filtri nella stringa di query.
  • Non puoi aggiungere un filtro a una sessione di debug una volta avviata. Per aggiungere un filtro, devi creare una sessione di debug.

Utilizzo dei filtri

Utilizza un filtro quando crei una sessione di debug utilizzando l'interfaccia utente o l'API Apigee, come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Quando crei una sessione di debug nell'interfaccia utente, nell'elenco a discesa Filtri puoi scegliere un filtro predefinito da applicare nel riquadro Avvia una sessione di debug o scegliere Filtro personalizzato e crearne uno tuo con la sintassi del filtro.

API

Per creare una sessione di debug con un filtro utilizzando l'API, includi quanto segue come payload nella richiesta di creazione della sessione di debug:

{
  "filter":"filter_body"
}

Per informazioni sulla creazione dei filtri, consulta Sintassi dei filtri.

L'esempio seguente crea una sessione di debug che include solo le transazioni in cui l'intestazione A è uguale a 42 e l'intestazione B è uguale a 43 oppure il codice di errore è ExpectedEOF:

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

Puoi definire un filtro solo nelle richieste di creazione di sessioni di debug; non puoi aggiungere un filtro a una sessione di debug esistente e non puoi rimuovere un filtro da una sessione di debug attiva.

Sintassi filtro

I filtri supportano la stessa sintassi utilizzata dalle condizioni Apigee, come descritto in Riferimento per le condizioni. È incluso quanto segue:

Inoltre, i filtri possono accedere a tutte le variabili di flusso descritte nel Riferimento per le variabili di flusso, nonché alle variabili personalizzate. I seguenti esempi mostrano solo alcune delle possibili variabili di flusso che puoi utilizzare nei filtri:

# Response codes:
  response.status.code <= 599
  response.status.code >=301 && response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') && request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed'
  fault.name == 'IPDeniedAccess'

Per informazioni sull'utilizzo delle variabili personalizzate, consulta Come utilizzare gli attributi personalizzati in Apigee nella community di Apigee.

Filtri UI predefiniti

La UI di Apigee fornisce un insieme di filtri comuni, in modo che tu non debba scrivere i tuoi filtri personalizzati. I filtri predefiniti sono riassunti nella tabella seguente.

Nome filtro Descrizione
Response Time Greater Than

Controlla la presenza di problemi di latenza quando:

  • target.duration è la latenza target, ovvero il tempo, in millisecondi, necessario per l'invio e la ricezione di una richiesta dal target (calcolato come differenza tra target.received.end.timestamp e target.sent.start.timestamp)
  • client.duration è la latenza del client, ovvero il tempo, in millisecondi, necessario per l'invio e la ricezione di una richiesta dal client (calcolato come la differenza tra client.received.end.timestamp e client.sent.start.timestamp)

Ad esempio:

target.duration > 420 && client.duration > 1000

Per saperne di più, consulta client e target nel riferimento alle variabili di flusso.
Response Code

Controlla se il codice di risposta HTTP corrisponde al valore specificato, ad esempio:

response.status.code <= 599
Header

Controlla se l'intestazione della richiesta specificata è uguale al valore specificato, ad esempio:

request.header.cache-control.1 == "16544"
Path

Controlla se la richiesta corrisponde al percorso specificato. Puoi utilizzare la corrispondenza con caratteri jolly nel valore, ad esempio:

request.path == /myproxy/customer/4*
Query Param

Controlla se il parametro di query della richiesta specificato è uguale al valore specificato, ad esempio:

request.queryparam.lang == "language:en-us"
Custom

Consente di inserire le tue espressioni. Puoi utilizzare qualsiasi oggetto nel Riferimento per le variabili di flusso e la sintassi nel Riferimento per le condizioni. Inoltre, puoi utilizzare variabili personalizzate.

Per saperne di più sulla creazione di filtri personalizzati, consulta Sintassi dei filtri.
 

Visualizzazione delle sessioni di debug

Apigee salva i dati della sessione di debug per 24 ore. Non puoi configurare questo valore; dopo 24 ore, i dati non saranno più disponibili. Prima di allora, puoi visualizzare le sessioni di debug.

Visualizza le sessioni di debug recenti utilizzando la UI o l'API Apigee, come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per visualizzare le sessioni di debug utilizzando la console Google Cloud

  1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

    Vai a Proxy API

  2. Fai clic sul proxy di cui vuoi eseguire il debug.
  3. Fai clic sulla scheda Debug.
  4. La sezione Sessioni di debug recenti mostra un elenco delle sessioni di debug disponibili.

  5. Fai clic sul link della sessione che vuoi visualizzare.

API

Con l'API è possibile:

Visualizza tutte le sessioni di debug utilizzando l'API

Per visualizzare tutte le sessioni di debug recenti definite per una revisione del proxy API in un ambiente, invia una richiesta GET alla seguente risorsa: 

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions

Se vuoi, puoi specificare uno dei seguenti parametri di ricerca per controllare la quantità di dati restituiti:

  • pageSize: numero massimo di sessioni di debug da elencare. La dimensione predefinita della pagina è 25.
  • pageToken: token di pagina, restituito da una chiamata precedente, che puoi utilizzare per recuperare la pagina successiva.

L'esempio seguente mostra come visualizzare le sessioni di debug per la revisione 1 del proxy API helloworld nell'ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Dove $TOKEN è impostato sul tuo token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente che puoi utilizzare, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

La risposta include un oggetto sessions che contiene un elenco delle sessioni di debug attualmente attive, come mostrato nell'esempio seguente:

{
"sessions": [
{
"id": "a423ac73-0902-4cfa-4242-87a353a84d87",
"timestamp_ms": 1566330186000
},
{
"id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
"timestamp_ms": 1566330286000
}
]
}

Nella risposta sono incluse solo le sessioni di debug che contengono almeno una transazione; le sessioni di debug che non contengono transazioni non sono incluse in questo elenco.

Per saperne di più, consulta l'API List Debug sessions.

Visualizza tutte le transazioni di una sessione di debug utilizzando l'API

Per visualizzare un elenco di transazioni per una sessione di debug, invia una richiesta GET alla seguente risorsa:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Dove debugsession è l'ID di una sessione di debug restituito quando visualizzi le sessioni di debug.

L'esempio seguente mostra come visualizzare le transazioni di una sessione di debug per la revisione 1 dell'API helloworld nell'ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Dove $TOKEN è impostato sul tuo token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente che puoi utilizzare, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

La risposta include un array di ID transazione, come mostrato nell'esempio seguente:

[
"myorg-test-ver-5qxdb-64",
"myorg-test-ver-5qxdb-65",
"myorg-test-ver-5qxdb-66",
"myorg-test-ver-5qxdb-67",
"myorg-test-ver-5qxdb-68",
"myorg-test-ver-5qxdb-69",
"myorg-test-ver-5qxdb-70",
"myorg-test-ver-5qxdb-71",
"myorg-test-ver-5qxdb-72"
]

Per saperne di più, consulta API List debug session data.

Visualizzazione dei dati sulle transazioni per una sessione di debug utilizzando l'API

Per visualizzare i dati delle transazioni per una sessione di debug, invia una richiesta GET alla seguente risorsa: 

https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions/{debugsession}/data/{transactionId}

Dove debugsession è l'ID di una sessione di debug restituito quando visualizzi le sessioni di debug e transactionId è l'ID transazione restituito quando visualizzi un elenco di transazioni per una sessione di debug.

I dati della transazione salvati durante una sessione di debug sono formattati in JSON. Puoi caricare questi dati nello strumento di debug offline.

L'esempio seguente mostra come scaricare i dati delle transazioni per una sessione di debug per la revisione 1 dell'API helloworld nell'ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data/myorg-test-ver-5qxdb-64" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Dove $TOKEN è impostato sul tuo token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente che puoi utilizzare, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

La risposta è costituita da un payload JSON che contiene i dati della transazione specificata, come descritto in Struttura dei dati di download.

I dati di debug contengono tutte le informazioni sulla richiesta e sulla risposta per ogni parte del flusso in un formato JSON proprietario. Puoi salvare questi dati e utilizzarli in un secondo momento nello strumento di debug offline.

Se non sono state aggiunte richieste alla sessione prima della sua fine, la risposta sarà simile alla seguente:

[]

Per saperne di più, consulta API Get debug session data.

Selezione delle opzioni di visualizzazione nell'interfaccia utente

Questa sezione descrive come selezionare le opzioni di visualizzazione per filtrare ciò che viene mostrato nella UI.

Per scegliere le opzioni di visualizzazione per la sessione di debug, seleziona o deseleziona le opzioni nel riquadro Opzioni di visualizzazione. Queste opzioni di visualizzazione vengono mantenute per ogni utente durante la sessione di debug.

Fai clic per ingrandire l'immagine elenco delle opzioni di visualizzazione
Opzione Descrizione
Mostra policy disabilitate Mostra le policy disabilitate. Un criterio può essere disattivato con l'API pubblica. Consulta il riferimento alla configurazione del proxy API.
Mostra policy saltate Mostra le policy che sono state saltate. Una policy ignorata si verifica quando la policy non è stata eseguita perché la condizione del passaggio è stata valutata come falsa. Per saperne di più, consulta Condizioni con variabili di flusso.
Mostra tutte le informazioni sul flusso Rappresentano le transizioni all'interno di un segmento di flusso.
Mostra tutte le condizioni del flusso Rappresentano le condizioni valutate per ogni flusso.

Condividi una sessione di debug

Puoi condividere una sessione di debug con altri utenti che hanno accesso alla tua organizzazione e le autorizzazioni necessarie. Per farlo, invia l'URL visualizzato nel browser quando visualizzi la sessione di debug. Il link è valido solo per 24 ore dopo la creazione della sessione di debug.

Download dei dati della sessione di debug in corso…

Puoi scaricare un file di risultati di debug non elaborati per la visualizzazione offline. Il file scaricato mostra i dettagli completi della sessione di debug, inclusi i contenuti di tutte le intestazioni, le variabili e le policy.

I dati della sessione di debug possono essere scaricati o visualizzati nella UI solo per 24 ore. Dopo questo punto, Apigee elimina i dati della sessione.

Per visualizzare i dati della sessione di debug scaricati, utilizza lo strumento di debug offline.

Interfaccia utente di Apigee

Per scaricare la sessione di debug corrente nella console Google Cloud , fai clic su Scarica nella visualizzazione Debug.

API

Per visualizzare gli ID di tutte le transazioni per la sessione di debug corrente utilizzando l'API Apigee, inserisci il seguente comando:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data

dove SESSION_ID è l'ID della sessione di debug che vuoi scaricare.

Consulta Elenca gli ID transazione di una sessione di debug.

Per ottenere i dati di debug per una transazione utilizzando l'API Apigee, inserisci il seguente comando:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data/TRANSACTION_ID

Struttura dei dati di download

La struttura di download dei dati della sessione di debug è diversa per l'interfaccia utente di Apigee e l'API Apigee.

Interfaccia utente di Apigee

Quando scarichi i dati utilizzando la UI di Apigee, la struttura dei dati:

  • Include tutte le transazioni dell'intera sessione
  • Memorizza le transazioni in negozio in un array Messages
  • Include i metadati della sessione (come oggetto DebugSession)

API

Non puoi utilizzare l'API Apigee per visualizzare i dati di un'intera sessione contemporaneamente; puoi utilizzare l'API solo per visualizzare i dati delle singole transazioni, come descritto in Visualizzazione delle sessioni di debug.

Ad esempio:

{
"completed": true,
"point": [
  ...
...
}

Scarica esempi di dati

L'esempio seguente evidenzia un oggetto di metadati DebugSession nei dati scaricati. Questo oggetto è seguito dall'array Messages che contiene le transazioni nella sessione.

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

Se la sessione di debug non includeva richieste, l'array Message è vuoto, come mostrato nell'esempio seguente:

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
"Messages": []
}

Eliminazione dei dati per una sessione di debug

Elimina i dati per una sessione di debug utilizzando l'interfaccia utente o l'API Apigee, come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per eliminare una sessione di debug nella console Google Cloud :

  1. Nella scheda Debug, fai clic sulla riga della sessione che vuoi eliminare.
  2. Nel riquadro Sessione di debug, fai clic su Elimina.

API

Per eliminare tutti i dati della sessione di debug utilizzando l'API, invia una richiesta DELETE alla seguente risorsa: 

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Dove debugsession è l'ID di una sessione di debug restituito quando visualizzi le sessioni di debug.

L'esempio seguente mostra come eliminare i dati della sessione di debug per la revisione 1 dell'API helloworld nell'ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
      -X DELETE \
      -H "Authorization: Bearer $TOKEN"

Dove $TOKEN è impostato sul tuo token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente che puoi utilizzare, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

In caso di esito positivo, il corpo della risposta sarà vuoto.

I dati della sessione di debug vengono conservati solo per 24 ore. Se non lo elimini esplicitamente prima di questa data, Apigee lo eliminerà per te.