Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Questa pagina illustra i passaggi necessari per configurare il monitoraggio distribuito per il runtime Apigee. Se non hai mai utilizzato sistemi di monitoraggio distribuito e vuoi saperne di più, consulta Informazioni sul monitoraggio distribuito.
Introduzione
I sistemi di monitoraggio distribuito ti consentono di monitorare una richiesta in un sistema software distribuito su più applicazioni, servizi e database, nonché su intermediari come i proxy. Questi sistemi di monitoraggio generano report che mostrano il tempo impiegato da una richiesta in ogni passaggio. I report di monitoraggio possono anche fornire una visione granulare dei vari servizi chiamati durante una richiesta, consentendo una comprensione più approfondita di ciò che accade in ogni fase del sistema software.
Lo strumento di traccia in Apigee Edge e lo strumento di debug in Apigee sono utili per la risoluzione dei problemi e il monitoraggio dei proxy API. Tuttavia, questi strumenti non inviano dati ai server di monitoraggio distribuito come Cloud Trace o Jaeger. Per visualizzare i dati di runtime di Apigee in un report sul monitoraggio distribuito, devi attivare esplicitamente il monitoraggio distribuito nel runtime di Apigee. Una volta attivato il monitoraggio, il runtime può inviare i dati delle tracce ai server di monitoraggio distribuito e partecipare a una traccia esistente. Di conseguenza, puoi visualizzare i dati all'interno e all'esterno dell'ecosistema Apigee da un'unica posizione.
Nei report sul monitoraggio distribuito puoi visualizzare le seguenti informazioni:
- Tempo di esecuzione di un intero flusso.
- Ora in cui viene ricevuta la richiesta.
- Ora in cui la richiesta viene inviata al target.
- Ora in cui la risposta viene ricevuta dal target.
- Tempo di esecuzione di ogni criterio in un flusso.
- Tempo di esecuzione dei callout del servizio e dei flussi target.
- Ora in cui la risposta viene inviata al client.
Nel report sul monitoraggio distribuito, puoi visualizzare i dettagli di esecuzione dei flussi come span. Un intervallo si riferisce al tempo impiegato da un flusso in una traccia. Il tempo necessario per eseguire un flusso viene visualizzato come aggregato del tempo necessario per eseguire ogni criterio nel flusso. Puoi visualizzare ciascuno dei seguenti flussi come singoli intervalli:
- Richiedi
- Proxy
- Preflow
- PostFlow
- Target
- Preflow
- PostFlow
- Proxy
- Risposta
- Proxy
- Preflow
- PostFlow
- Target
- Preflow
- PostFlow
- Proxy
Una volta attivato il monitoraggio distribuito, il runtime Apigee traccia per impostazione predefinita un insieme di variabili predefinite. Per ulteriori informazioni, consulta Variabili di traccia predefinite nel report sul monitoraggio. Puoi utilizzare il criterio TraceCapture per estendere il comportamento di runtime predefinito e tracciare variabili aggiuntive per flussi, criteri o personalizzate. Per ulteriori informazioni, consulta le norme relative a TraceCapture.
Variabili di traccia predefinite nel report sul monitoraggio
Una volta attivato il monitoraggio distribuito, puoi visualizzare il seguente insieme di variabili predefinite nel report sul monitoraggio. Le variabili sono visibili nei seguenti intervalli:
- POST_RESP_SENT: questo span viene aggiunto dopo aver ricevuto una risposta dal server di destinazione.
- POST_CLIENT_RESP_SENT: questo span viene aggiunto dopo l'invio della risposta del proxy al client.
Variabili nell'intervallo POST_RESP_SENT
Le seguenti variabili sono visibili nell'elementoPOST_RESP_SENT
:
- REQUEST_URL (request.url)
- REQUEST_VERB (request.verb)
- RESPONSE_STATUS_CODE (response.status.code)
- ROUTE_NAME (route.name)
- ROUTE_TARGET (route.target)
- TARGET_BASE_PATH (target.basepath)
- TARGET_HOST (target.host)
- TARGET_IP (target.ip)
- TARGET_NAME (target.name)
- TARGET_PORT (target.port)
- TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
- TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
- TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
- TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
- TARGET_SSL_ENABLED (target.ssl.enabled)
- TARGET_URL (target.url)
Variabili nell'intervallo POST_CLIENT_RESP_SENT
Le seguenti variabili sono visibili nell'elementoPOST_CLIENT_RESP_SENT
:
- API_PROXY_REVISION (apiproxy.revision)
- APIPROXY_NAME (apiproxy.name)
- CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
- CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
- CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
- CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
- ENVIRONMENT_NAME (environment.name)
- FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
- IS_ERROR (is.error)
- MESSAGE_ID (message.id)
- MESSAGE_STATUS_CODE (message.status.code)
- PROXY_BASE_PATH (proxy.basepath)
- PROXY_CLIENT_IP (proxy.client.ip)
- PROXY_NAME (proxy.name)
- PROXY_PATH_SUFFIX (proxy.pathsuffix)
- PROXY_URL (proxy.url)
Sistemi di monitoraggio distribuito supportati
Il runtime Apigee supporta i seguenti sistemi di monitoraggio distribuito:
- Cloud Trace
- Jaeger
Puoi configurare il runtime Apigee in modo da inviare i dati di traccia a un sistema Cloud Trace o a un sistema Jaeger.
Poiché il monitoraggio di tutte le chiamate API nel runtime di Apigee influirebbe sul rendimento, Apigee ti consente di configurare una frequenza di campionamento probabilistica.
Utilizzando la frequenza di campionamento, puoi specificare il numero di chiamate API inviate per il monitoraggio distribuito. Ad esempio, se
specifichi la frequenza di campionamento come 0.4
, significa che il 40% delle chiamate API viene
inviato per il monitoraggio. Per ulteriori informazioni, consulta Considerazioni sul rendimento.
Configurare gli ambienti di runtime Apigee per Cloud Trace
Sia il runtime Apigee che il runtime Apigee hybrid supportano il monitoraggio distribuito utilizzando Cloud Trace. Se utilizzi Jaeger, puoi saltare questa sezione e andare a Attivare il monitoraggio distribuito per Jaeger.
Configura il runtime Apigee per Cloud Trace
Per utilizzare Cloud Trace con un runtime Apigee, nel progetto Google Cloud deve essere attivata l'Cloud Trace API. Questa impostazione consente al tuo progetto Google Cloud di ricevere dati di traccia da origini autenticate.
Per verificare che l'Cloud Trace API sia abilitata:
- Nella console Google Cloud, vai ad API e servizi:
- Fai clic su Abilita API e servizi.
- Nella barra di ricerca, inserisci API Trace.
- Se viene visualizzato il messaggio API abilitata, significa che l'API è già abilitata e non devi fare altro. In caso contrario, fai clic su Abilita.
Configura il runtime di Apigee hybrid per Cloud Trace
L'API Cloud Trace deve essere abilitata per utilizzare Cloud Trace con un runtime Apigee hybrid. Per verificare che l'API Cloud Trace sia abilitata, segui i passaggi descritti in Configurare il runtime Apigee per Cloud Trace.
Oltre ad attivare l'Cloud Trace API, devi aggiungere l'account di servizio iam.gserviceaccount.com
per utilizzare Cloud Trace con il runtime ibrido. Per aggiungere l'account di servizio, insieme ai ruoli e alle chiavi richiesti, svolgi i seguenti passaggi:
- Crea un nuovo account di servizio:
gcloud iam service-accounts create \ apigee-runtime --display-name "Service Account Apigee hybrid runtime" \ --project PROJECT_ID
- Aggiungi un'associazione del criterio IAM all'account di servizio:
gcloud projects add-iam-policy-binding \ PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \ --role=roles/cloudtrace.agent --project PROJECT_ID
- Crea una chiave dell'account di servizio:
gcloud iam service-accounts keys \ create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
- Aggiungi l'account di servizio al file
overrides.yaml
. - Applica le modifiche al runtime
envs: - name: ENV_NAME serviceAccountPaths: runtime: apigee-runtime.json synchronizer: apigee-sync.json udca: apigee-udca.json
apigeectl apply -f overrides.yaml --env=ENV_NAME
Attivare il monitoraggio distribuito
Prima di attivare il monitoraggio distribuito per Cloud Trace o Jaeger, crea le seguenti variabili di ambiente:
TOKEN
="Authorization: Bearer $(gcloud auth print-access-token)
"
ENV_NAME
=YOUR_ENVIRONMENT_NAME
PROJECT_ID
=YOUR_GOOGLE_CLOUD_PROJECT_ID
Dove:
TOKEN
definisce l'intestazione Authentication con un token di accesso. Utilizza questo intestazione quando chiami le API Apigee. Per ulteriori informazioni, consulta la pagina di riferimento del comando print-access-token.ENV_NAME
è il nome di un ambiente nella tua organizzazione.PROJECT_ID
è l'ID del tuo progetto Google Cloud.
Attivare il monitoraggio distribuito per Cloud Trace
L'esempio seguente mostra come attivare il monitoraggio distribuito per Cloud Trace:
- Esegui questa chiamata all'API Apigee:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \ -X PATCH \ -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'", "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
Il corpo della richiesta di esempio è costituito dai seguenti elementi:
samplingRate
è impostato su 0,1. Ciò significa che circa il 10% delle chiamate API viene inviato al monitoraggio distribuito. Per ulteriori informazioni sull'impostazione di unsamplingRate
per l'ambiente di runtime, consulta Considerazioni sul rendimento.- Il parametro
exporter
è impostato suCLOUD_TRACE
. - L'endpoint è impostato sul progetto Google Cloud in cui vuoi che venga inviata la traccia. NOTA: deve corrispondere all'account di servizio creato nel passaggio di configurazione.
Una risposta corretta è simile alla seguente:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.1 } }
Attivare il monitoraggio distribuito per Jaeger
L'esempio seguente mostra come attivare il monitoraggio distribuito per Jaeger:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \ -X PATCH \ -H "content-type:application/json" -d '{ "samplingConfig": { "samplingRate": 0.4, "sampler": "PROBABILITY"}, "endpoint": "http://DOMAIN:9411/api/v2/spans", "exporter": "JAEGER" }'
In questo esempio:
samplingRate
è impostato su 0,4. Ciò significa che circa il 40% delle chiamate API viene inviato al monitoraggio distribuito.- Il parametro
exporter
è impostato suJAEGER
. - L'endpoint è impostato sulla posizione in cui Jaeger è installato e configurato.
Quando esegui il comando, puoi vedere una risposta simile alla seguente:
{ "exporter": "JAEGER", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.4 } }
Visualizza la configurazione del monitoraggio distribuito
Per visualizzare la configurazione di monitoraggio distribuito esistente nel tuo runtime, accedi al runtime ed esegui il seguente comando:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig
Quando esegui il comando, puoi vedere una risposta simile alla seguente:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.1 } }
Aggiorna la configurazione del monitoraggio distribuito
Il seguente comando mostra come aggiornare la configurazione del monitoraggio distribuito esistente per Cloud Trace:
curl -s \ -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \ -X PATCH -H "content-type:application/json" \ -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"}, "endpoint":"staging", exporter:"CLOUD_TRACE"}'
Quando esegui il comando, puoi vedere una risposta simile alla seguente:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.05 } }
0.05
.
Disattivare la configurazione del monitoraggio distribuito
L'esempio seguente mostra come disattivare il monitoraggio distribuito configurato per Cloud Trace:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \ -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig": {"sampler": "OFF","samplingRate": 0.1}}'
Quando esegui il comando, puoi vedere una risposta simile alla seguente:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "OFF", "samplingRate": 0.1 } }
Sostituire le impostazioni di traccia per i proxy API
Quando attivi il monitoraggio distribuito nel runtime Apigee, tutti i proxy API nel runtime utilizzano la stessa configurazione per il monitoraggio. Tuttavia, puoi ignorare la configurazione del monitoraggio distribuito per un proxy API o un gruppo di proxy API. In questo modo, avrai un maggiore controllo sulla configurazione del monitoraggio.
L'esempio seguente sostituisce la configurazione del monitoraggio distribuito per il proxy API hello-world
:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \ -X POST \ -H "content-type:application/json" \ -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
Puoi eseguire l'override della configurazione per risolvere i problemi specifici di un proxy API senza dover modificare la configurazione di tutti i proxy API.
Aggiorna le sostituzioni delle impostazioni di traccia
Per aggiornare un'override della configurazione di monitoraggio per un proxy API o un gruppo di proxy API, svolgi i seguenti passaggi:
- Utilizza il seguente comando per recuperare eventuali sostituzioni esistenti della configurazione di monitoraggio:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \ -X GET
Questo comando dovrebbe restituire una risposta simile alla seguente, che contiene un campo "name" che identifica il proxy o i proxy regolati dall'override:
{ "traceConfigOverrides": [ { "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1", "apiProxy": "proxy1", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.25 } } ] }
- Per aggiornare il proxy, utilizza il valore del campo "name" per inviare una richiesta POST alla configurazione di override per quel proxy,insieme ai valori dei campi aggiornati. Ad esempio:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \ -X POST \ -H "content-type:application/json" \ -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'
Eliminare le sostituzioni delle impostazioni di traccia
Per eliminare un'override della configurazione di monitoraggio per un proxy API o un gruppo di proxy API, svolgi i seguenti passaggi:
- Utilizza il seguente comando per recuperare eventuali sostituzioni esistenti della configurazione di monitoraggio:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \ -X GET
Questo comando dovrebbe restituire una risposta simile alla seguente, che contiene un campo "name" che identifica il proxy o i proxy regolati dall'override:
{ "traceConfigOverrides": [ { "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1", "apiProxy": "proxy1", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.25 } } ] }
- Per eliminare il proxy, utilizza il valore del campo "name" per inviare una richiesta DELETE alla configurazione di override per quel proxy,insieme ai valori dei campi aggiornati. Ad esempio:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \ -X DELETE \
Considerazioni sulle prestazioni
Quando attivi il monitoraggio distribuito per un ambiente di runtime Apigee, è previsto un impatto sulle prestazioni. L'impatto può comportare un aumento dell'utilizzo della memoria, un aumento dei requisiti della CPU e un aumento della latenza.
L'entità dell'impatto dipenderà in parte dalla complessità del proxy API (ad esempio, il numero di criteri) e dalla frequenza di campionamento probabilistica (impostata come samplingRate
). Maggiore è la frequenza di campionamento, maggiore è l'impatto sulle prestazioni.
Sebbene l'impatto sulle prestazioni dipenda da una serie di fattori, puoi prevedere un calo del 10-20% delle prestazioni quando utilizzi il monitoraggio distribuito.
Per gli ambienti con traffico elevato e requisiti di bassa latenza, la frequenza di campionamento probabilistica consigliata è inferiore o uguale al 10%. Se vuoi utilizzare il monitoraggio distribuito per la risoluzione dei problemi,
valuta la possibilità di aumentare il campionamento probabilistico (samplingRate
) solo per proxy API specifici.