Attivazione del tracciamento distribuito

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina illustra i passaggi necessari per configurare il tracciamento distribuito per il runtime Apigee. Se non hai mai utilizzato sistemi di tracciamento distribuito e vuoi saperne di più, consulta Informazioni sul tracciamento distribuito.

Introduzione

I sistemi di tracciamento distribuito consentono di tenere traccia di una richiesta in un sistema software distribuito tra più applicazioni, servizi e database, nonché intermediari come i proxy. Questi sistemi di tracciamento generano report che mostrano il tempo impiegato da una richiesta in ogni passaggio. Il tracciamento dei report può anche fornire una visualizzazione granulare dei vari servizi chiamati durante una richiesta, consentendo una comprensione più approfondita di cosa succede in ogni passaggio nel tuo 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 a server di tracciamento distribuiti 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 abilitata il tracciamento, il runtime può inviare dati di traccia a server di tracciamento distribuiti e partecipare a una traccia esistente. Di conseguenza, puoi visualizzare i dati all'interno e all'esterno del tuo ecosistema Apigee da un'unica posizione.

Puoi visualizzare le seguenti informazioni nei report di tracciamento distribuito:

  • 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 viene ricevuta la risposta dal target.
  • Tempo di esecuzione di ogni criterio in un flusso.
  • Tempo di esecuzione dei callout di servizio e dei flussi di destinazione.
  • L'ora in cui la risposta viene inviata al client.

Nel report di tracciamento distribuito, puoi visualizzare i dettagli dell'esecuzione dei flussi come intervalli. Un intervallo è il tempo impiegato da un flusso in una traccia. Il tempo impiegato per eseguire un flusso viene visualizzato come un aggregato del tempo necessario per eseguire ciascun criterio nel flusso. Puoi visualizzare ciascuno dei seguenti flussi come intervalli individuali:

  • Richiesta
    • Proxy
      • Pre-flusso
      • PostFlow
    • Scegli come target
      • Pre-flusso
      • PostFlow
  • Risposta
    • Proxy
      • Pre-flusso
      • PostFlow
    • Scegli come target
      • Pre-flusso
      • PostFlow

Dopo aver abilitato il tracciamento distribuito, il runtime Apigee traccia un insieme di variabili predefinite per impostazione predefinita. Per maggiori informazioni, consulta Variabili di traccia predefinite nel report di tracciamento. Puoi utilizzare il criterio Trace Capture per estendere il comportamento di runtime predefinito e tracciare variabili personalizzate, criteri o flussi aggiuntivi. 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 nei seguenti intervalli:

  • POST_RESP_SENT: questo intervallo viene aggiunto dopo aver ricevuto una risposta dal server di destinazione.
  • POST_CLIENT_RESP_SENT: questo intervallo viene aggiunto dopo che la risposta proxy viene inviata 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.verbo)
  • 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 (nome.target)
  • TARGET_PORT (porta.destinazione)
  • 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)
  • PROXY_BASE_PATH (proxy.basepath)
  • PROXY_CLIENT_IP (proxy.client.ip)
  • PROXY_NAME (nome.proxy)
  • PROXY_PATH_LAMBDA (proxy.pathsuffix)
  • PROXY_URL (proxy.url)

Sistemi di tracciamento distribuiti supportati

Il runtime Apigee supporta i seguenti sistemi di tracciamento distribuiti:

  • Cloud Trace
  • Jaeger

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

Poiché il tracciamento di tutte le chiamate API nel runtime di Apigee influirebbe sulle prestazioni, Apigee ti consente di configurare una frequenza di campionamento probabile. Utilizzando la frequenza di campionamento, puoi specificare il numero di chiamate API inviate per il tracciamento distribuito. Ad esempio, se specifichi la frequenza di campionamento come 0.4, significa che il 40% delle chiamate API viene inviato per il tracciamento. Per ulteriori informazioni, consulta la sezione Considerazioni sul rendimento.

Configura i runtime Apigee per Cloud Trace

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

Configura il runtime Apigee per Cloud Trace

Per utilizzare Cloud Trace con un runtime Apigee, l'Cloud Trace API deve essere abilitata nel progetto Google Cloud. Questa impostazione consente al progetto Google Cloud di ricevere dati di traccia da origini autenticate.

Per confermare 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 API abilitata, questa API è già abilitata e non devi fare nulla. Altrimenti, fai clic su Abilita.

Configura il runtime ibrido Apigee per Cloud Trace

L'API Cloud Trace deve essere abilitata per utilizzare Cloud Trace con un runtime ibrido Apigee. Per confermare che l'API Cloud Trace sia 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 l'account di servizio, oltre ai ruoli e alle chiavi richiesti, esegui 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 di 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. Puoi utilizzare questa intestazione quando chiami le API Apigee. Per maggiori informazioni, consulta la pagina di riferimento per il comando print-access-token.
  • ENV_NAME è il nome di un ambiente della tua organizzazione.
  • PROJECT_ID è l'ID del tuo progetto Google Cloud.

Abilita il 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 di samplingRate è impostato su 0,1. Ciò significa che circa il 10% delle chiamate API viene inviato al tracciamento distribuito. Per saperne di più sull'impostazione di un samplingRate per l'ambiente di runtime, consulta Considerazioni sulle prestazioni.
    • Il parametro exporter è impostato su CLOUD_TRACE.
    • L'endpoint è impostato sul progetto Google Cloud a cui vuoi inviare la traccia. NOTA: deve corrispondere all'account di servizio che è stato eseguito 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 abilitare 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 di samplingRate è impostato su 0,4. Ciò significa che circa il 40% delle chiamate API viene inviato al tracciamento distribuito.
  • Il parametro exporter è impostato su JAEGER.
  • L'endpoint è impostato sulla posizione in cui Jaeger è installato e configurato.

Quando esegui il comando, puoi visualizzare 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 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 visualizzare una risposta simile alla seguente:

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

Aggiorna la configurazione di 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 visualizzare 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 di 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 visualizzare 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 utilizzano la stessa configurazione per il tracciamento. Tuttavia, puoi eseguire l'override della configurazione di tracciamento distribuito per un proxy API o per un gruppo di proxy API. In questo modo puoi avere un controllo più granulare sulla configurazione di tracciamento.

L'esempio seguente esegue l'override della configurazione di tracciamento 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 problemi specifici di un proxy API senza dover modificare la configurazione di tutti i proxy API.

Aggiorna override delle impostazioni di traccia

Per aggiornare l'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 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 "nome" per inviare una richiesta POST alla configurazione di override per il 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 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 eliminare il proxy, utilizza il valore del campo "nome" per inviare una richiesta DELETE alla configurazione di override per il 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 abiliti il tracciamento 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 di CPU e una maggiore latenza. L'entità dell'impatto dipende in parte dalla complessità del proxy API (ad esempio, il numero di criteri) e dalla frequenza di campionamento probabilistica (impostata come samplingRate). Più alta è la frequenza di campionamento, maggiore è l'impatto sulle prestazioni. Anche se l'impatto sulle prestazioni dipende da una serie di fattori, puoi aspettarti un calo delle prestazioni del 10-20% quando utilizzi il tracciamento distribuito.

Per gli ambienti con requisiti di traffico elevato e bassa latenza, la frequenza di campionamento probabilistica consigliata è inferiore o uguale al 10%. Se vuoi utilizzare il tracciamento distribuito per la risoluzione dei problemi, valuta la possibilità di aumentare il campionamento probabiliistico (samplingRate) solo per proxy API specifici.