Attivazione del tracciamento distribuito

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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 tracciamento distribuito consentono di tenere traccia di una richiesta in un sistema software distribuito più applicazioni, servizi e database, nonché intermediari come i proxy. Questi controlli 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 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 dati dall'interno e dall'esterno del tuo ecosistema Apigee da un'unica posizione.

Nei report di tracciamento distribuito puoi visualizzare le seguenti informazioni:

• Tempo di esecuzione di un intero flusso.
• L'ora in cui viene ricevuta la richiesta.
• L'ora in cui la richiesta viene inviata alla destinazione.
• Ora in cui la risposta viene ricevuta dal target.
• Tempo di esecuzione di ogni criterio in un flusso.
• Tempo di esecuzione dei callout di servizio e dei flussi target.
• Ora in cui la risposta viene inviata al client.

Nel report di tracciamento distribuito, puoi visualizzare i dettagli di esecuzione dei flussi come intervalli. 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
• Risposta
  • Proxy
    • Preflow
    • PostFlow
  • Target
    • Preflow
    • PostFlow

Una volta abilitato il tracciamento distribuito, il runtime Apigee traccia un insieme di variabili predefinite per impostazione predefinita. Per ulteriori informazioni, consulta Variabili di traccia predefinite nel report sul monitoraggio. Puoi usare il criterio Trace Capture per estendere il comportamento di runtime predefinito e tracciare ulteriori flussi, criteri o variabili personalizzate. Per ulteriori informazioni, consulta il criterio TraceCapture.

Una chiamata API in entrata ad Apigee potrebbe contenere intestazioni di traccia mentre la chiamata di una traccia esistente. In questo caso, Apigee partecipa alla traccia esistente e propaga le intestazioni alla chiamata API in uscita. Il runtime Apigee comprende Formato intestazione Zipkin B3. Di conseguenza, riconosce le intestazioni x-b3-traceid, x-b3-spanid e x-b3-sampled quando partecipa a una traccia esistente. Tuttavia, se non sono presenti intestazioni di traccia in una chiamata API in arrivo, Apigee aggiungerà le proprie intestazioni di traccia e le propagherà alla chiamata API in uscita. Altri servizi possono accedere alle intestazioni e partecipare al monitoraggio, se necessario.

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 intervallo viene aggiunto dopo l'invio della risposta proxy al client.

Variabili nell'intervallo POST_RESP_SENT

Le seguenti variabili sono visibili nell'intervallo POST_RESP_SENT:

• REQUEST_URL (request.url)
• REQUEST_VERB (request.verb)
• ANSWER_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'elemento POST_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 (nome ambiente)
• FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
• IS_ERROR (is.error)
• MESSAGE_ID (message.id)
• MESSAGE_STATUS_CODE (message.status.code)
• PERCORSO_PROXY_BASE (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 tracciamento 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 saperne di più, consulta Considerazioni sul rendimento.

La frequenza di campionamento massima configurabile è 0.5.

Configura i runtime Apigee per Cloud Trace

Sia il runtime Apigee che il runtime ibrido Apigee supportano il tracciamento distribuito tramite 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'API Cloud Trace. Questa impostazione consente al progetto Google Cloud di ricevere dati di traccia da origini autenticate.

Per verificare che l'Cloud Trace API sia abilitata:

1. Nella console Google Cloud, vai ad API e servizi:

   Vai ad API e servizi

2. Fai clic su Abilita API e servizi.
3. Nella barra di ricerca, inserisci API Trace.
4. 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 ibrido Apigee per Cloud Trace

Per utilizzare Cloud Trace con un runtime ibrido Apigee, l'API Cloud Trace deve essere abilitata. Per verificare che l'interfaccia utente L'API Trace è abilitata, segui i passaggi descritti in Configurare il runtime Apigee per Cloud Trace.

Oltre ad abilitare l'Cloud Trace API, devi aggiungere l'account di servizio iam.gserviceaccount.com per utilizzare Cloud Trace con il runtime ibrido. Per aggiungere il servizio dell'account, insieme ai ruoli e alle chiavi richiesti, segui questi passaggi:

1. Crea un nuovo account di servizio:

   gcloud iam service-accounts create \
       apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
       --project PROJECT_ID

2. Aggiungi un'associazione dei criteri 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

3. 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

   Se non vengono gestite correttamente, le chiavi degli account di servizio comportano un rischio per la sicurezza. Sei responsabile della sicurezza della chiave privata e di altre operazioni descritte dalle best practice per la gestione delle chiavi degli account di servizio. Se non riesci a creare una chiave del service account, la creazione di chiavi del service account potrebbe essere disabilitata per la tua organizzazione. Per ulteriori informazioni, consulta Gestione delle risorse dell'organizzazione sicure per impostazione predefinita.
4. Aggiungi l'account di servizio al file overrides.yaml.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

5. Applica le modifiche al runtime

apigeectl apply -f overrides.yaml --env=ENV_NAME

Nell'ambiente ibrido Apigee, puoi utilizzare Anthos Service Mesh con Cloud Trace. Per ulteriori informazioni sull'abilitazione di Cloud Trace nel mesh di servizi, consulta Accesso alle tracce in Cloud Trace.

Abilita tracciamento 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. Usi questa intestazione durante la chiamata alle 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:

1. Esegui questa chiamata 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 un samplingRate per l'ambiente di runtime, consulta Considerazioni sul rendimento.
   • Il parametro exporter è impostato su CLOUD_TRACE.
   • L'endpoint è impostato sul progetto Google Cloud a cui vuoi che venga inviata la traccia. NOTA: deve corrispondere al servizio creato nel passaggio di configurazione.

   Una risposta corretta è simile alla seguente:

   {
     "exporter": "CLOUD_TRACE",
     "endpoint": "staging",
     "samplingConfig": {
       "sampler": "PROBABILITY",
       "samplingRate": 0.1
     }
   }

Abilita tracciamento 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:

• Il valore samplingRate è impostato su 0,4. Ciò significa che circa il 40% delle chiamate API viene inviato distribuito il tracciamento.
• Il parametro exporter è impostato su JAEGER.
• 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 tracciamento 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
  }
}

In questo esempio, la frequenza di campionamento viene aggiornata a 0.05.

Per aggiornare la configurazione per Jaeger, imposta il campo exporter in la richiesta a JAEGER.

Disabilita la configurazione del tracciamento 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 abiliti il tracciamento distribuito nel runtime Apigee, tutti i proxy API nel runtime vengono utilizzati la stessa configurazione per il tracciamento. Tuttavia, puoi eseguire l'override della configurazione del tracciamento 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 di tracciamento distribuito per 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 problemi specifici di un proxy API senza dover cambiare 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:

1. 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
         }
       }
     ]
   }

2. 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 tracciamento per un proxy API o un gruppo di proxy API, segui questi passaggi:

1. 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 "nome" campo 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
         }
       }
     ]
   }

2. 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

È previsto un impatto sulle prestazioni quando abiliti il tracciamento distribuito per un ambiente di runtime Apigee. 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 sul rendimento. 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 ambienti con requisiti di traffico elevato e bassa latenza, la frequenza di campionamento è 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.