Attivazione del tracciamento distribuito

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Questa pagina mostra i passaggi necessari per configurare il tracciamento distribuito per il runtime Apigee. Se è la prima volta che utilizzi sistemi di tracciamento distribuito e desideri maggiori informazioni, consulta Informazioni sul tracciamento 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. Il tracciamento dei report può anche fornire una visione granulare dei vari servizi chiamati durante una richiesta, consentendo una comprensione più approfondita di ciò avviene in ogni passaggio del sistema software.

Lo strumento di tracciamento 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 Apigee in un report di tracciamento distribuito, devi abilitare esplicitamente il tracciamento distribuito nel runtime Apigee. Una volta abilitato il tracciamento, il runtime può inviare dati di traccia ai server di tracciamento distribuiti 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.
  • L'ora in cui la risposta viene ricevuta dal target.
  • Tempo di esecuzione di ciascun 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. Viene visualizzato il tempo necessario per eseguire un flusso come un aggregato del tempo necessario per eseguire ciascun criterio nel flusso. Puoi visualizzare ciascuno i seguenti flussi come intervalli individuali:

  • Richiesta
    • Proxy
      • Pre-flusso
      • PostFlow
    • Destinazione
      • Pre-flusso
      • PostFlow
  • Risposta
    • Proxy
      • Pre-flusso
      • PostFlow
    • Destinazione
      • Pre-flusso
      • PostFlow

Una volta abilitato il tracciamento distribuito, il runtime Apigee traccia un insieme di variabili predefinite per impostazione predefinita. Per ulteriori informazioni, vedi Variabili di traccia predefinite nel report di tracciamento. 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.

Variabili di traccia predefinite nel report di tracciamento

Una volta attivato il tracciamento distribuito, puoi visualizzare il seguente insieme di variabili predefinite nel report di tracciamento. Le variabili sono visibili nelle seguenti sezioni:

  • POST_RESP_SENT::questo intervallo viene aggiunto dopo che il server di destinazione riceve una risposta.
  • 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)
  • IP TARGET (target.ip)
  • TARGET_NAME (nome.target)
  • 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'intervallo 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 (nome.proxy)
  • PROXY_PATH_SUFFIX (proxy.pathsuffix)
  • PROXY_URL (proxy.url)

Sistemi di tracciamento distribuiti supportati

Il runtime Apigee supporta i seguenti sistemi di tracciamento distribuito:

  • Cloud Trace
  • Jaeger

Puoi configurare il runtime Apigee per inviare dati di traccia a Cloud Trace o Sistema Jaeger.

Poiché il tracciamento di tutte le chiamate API nel runtime di Apigee potrebbe influire sulle prestazioni, Apigee ti consente di configurare una frequenza di campionamento probabilistica. Utilizzando la frequenza di campionamento, puoi specificare il numero di chiamate API che vengono inviate per il tracciamento distribuito. Ad esempio, se se specifichi la frequenza di campionamento come 0.4, significa che il 40% delle chiamate API viene inviate per il tracciamento. Per saperne di più, consulta Considerazioni sulle prestazioni.

Configura i runtime Apigee per Cloud Trace

Sia il runtime Apigee che il runtime ibrido Apigee supportano il tracciamento distribuito tramite Cloud Trace. Se utilizzando Jaeger, puoi saltare questa sezione e passare ad Attivare il tracciamento distribuito per Jaeger.

Configura il runtime Apigee per Cloud Trace

Per utilizzare Cloud Trace con un runtime Apigee, il progetto Google Cloud deve disporre Cloud Trace API abilitata. 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 è visualizzato API abilitata, l'API è già abilitata e non devi fare nulla. In caso contrario, fai clic su Attiva.

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
  4. Aggiungi l'account di servizio al file overrides.yaml.
    5. envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json
  5. Applica le modifiche al runtime
    6. apigeectl apply -f overrides.yaml --env=ENV_NAME
.

Abilita tracciamento distribuito

Prima di abilitare il tracciamento 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 connessione. Usi questa intestazione durante la chiamata alle API Apigee. Per ulteriori informazioni, consulta la pagina di riferimento per print-access-token.
  • ENV_NAME è il nome di un ambiente nella tua organizzazione.
  • PROJECT_ID è l'ID del tuo progetto Google Cloud.

Abilita tracciamento distribuito per Cloud Trace

L'esempio seguente mostra come abilitare il tracciamento 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:

    • Il valore samplingRate è impostato su 0,1. Ciò significa che circa il 10% delle chiamate API viene inviato distribuito il tracciamento. Per saperne di più sull'impostazione di un valore samplingRate per l'ambiente di runtime, consulta la sezione Considerazioni sulle prestazioni.
    • 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 tracciamento 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 sul luogo 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 di tracciamento distribuito

Per visualizzare la configurazione di tracciamento distribuita esistente nel runtime, accedi al tuo runtime ed esegui questo 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 di tracciamento 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.

Disabilita la configurazione del tracciamento distribuito

L'esempio seguente mostra come disabilitare il tracciamento 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
  }
}

Esegui l'override delle 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. Ciò ti offre un controllo più granulare configurazione di tracciamento.

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 override delle impostazioni di traccia

Per aggiornare 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 override esistenti della configurazione di tracciamento: 
    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 aggiornare il proxy, utilizza il valore del parametro "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}}'

Elimina override delle impostazioni della 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 override esistenti della configurazione di tracciamento: 
    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 parametro "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. Impatto può comportare un aumento dell'utilizzo della memoria, un aumento dei requisiti di CPU e una maggiore latenza. La portata dell'impatto dipenderà in parte dalla complessità del proxy API (ad esempio, il numero di criteri) e frequenza di campionamento probabilistica (impostata come samplingRate). Più alta è la frequenza di campionamento, maggiore è l'impatto sulle prestazioni. Sebbene l'impatto sulle prestazioni dipenda da una serie di fattori, ci si può aspettare un calo del 10-20% delle prestazioni quando usando il tracciamento distribuito.

Per ambienti con requisiti di traffico elevato e bassa latenza, la frequenza di campionamento è inferiore o uguale al 10%. Se vuoi usare il tracciamento distribuito per risolvere i problemi, Valuta la possibilità di aumentare il campionamento probabilistico (samplingRate) solo per proxy API specifici.