Attivazione del tracciamento distribuito

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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

Introduzione

I sistemi di tracciamento distribuito consentono di monitorare una richiesta in un sistema software distribuito su 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. I report di tracciamento possono anche fornire una visualizzazione granulare dei vari servizi chiamati durante una richiesta, consentendo una comprensione più approfondita di ciò che accade 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 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 attivato il tracciamento, il runtime può inviare i dati di tracciamento ai server di tracciamento distribuito 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.

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.
  • Ora in cui la richiesta viene inviata alla destinazione.
  • Ora in cui la risposta viene ricevuta dalla destinazione.
  • Tempo di esecuzione di ogni policy in un flusso.
  • Tempo di esecuzione dei callout di servizio e dei flussi di destinazione.
  • Ora in cui la risposta viene inviata al cliente.

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 impiegato per eseguire un flusso viene visualizzato come aggregazione del tempo necessario per eseguire ogni policy nel flusso. Puoi visualizzare ciascuno dei seguenti flussi come intervalli individuali:

  • Richiesta
    • Proxy
      • Preflow
      • PostFlow
    • Target
      • Preflow
      • PostFlow
  • Risposta
    • Proxy
      • Preflow
      • PostFlow
    • Target
      • Preflow
      • PostFlow

Una volta attivato il tracciamento distribuito, il runtime Apigee traccerà un insieme di variabili predefinite per impostazione predefinita. Per ulteriori informazioni, vedi Variabili di traccia predefinite nel report di tracciamento. Puoi utilizzare il criterio TraceCapture per estendere il comportamento di runtime predefinito e tracciare ulteriori variabili di flusso, criteri o personalizzate. Per ulteriori informazioni, consulta le norme relative a 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 del 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.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'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 (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 tracciamento distribuito supportati

Il runtime Apigee supporta i seguenti sistemi di tracciamento distribuito:

  • Cloud Trace
  • Jaeger

Puoi configurare il runtime Apigee per inviare i 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 probabilistico. Utilizzando la frequenza di campionamento, puoi specificare il numero di chiamate API inviate per la tracciabilità distribuita. Ad esempio, se specifichi la frequenza di campionamento come 0.4, significa che il 40% delle chiamate API viene inviato per la tracciabilità. Per ulteriori informazioni, vedi Considerazioni sul rendimento.

Configura i runtime Apigee per Cloud Trace

Sia il runtime Apigee che il runtime Apigee Hybrid supportano la traccia distribuita utilizzando Cloud Trace. Se utilizzi Jaeger, puoi saltare questa sezione e passare ad Attivazione della tracciabilità distribuita per Jaeger.

Configura il runtime Apigee per Cloud Trace

Per utilizzare Cloud Trace con un runtime Apigee, il tuo progetto Google Cloud deve avere l'Cloud Trace API abilitata. 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:

  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 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 Configura il runtime Apigee per Cloud Trace.

Oltre ad attivare l'Cloud Trace API, devi aggiungere il account di servizio iam.gserviceaccount.com per utilizzare Cloud Trace con il runtime ibrido. Per aggiungere il service 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 della policy IAM al 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 il 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 utilizzando Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Attivare il tracciamento distribuito

Prima di attivare la tracciabilità distribuita 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 di autenticazione con un token di connessione. Utilizzi 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 la traccia distribuita 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 a distributed tracing. Per saperne di più sull'impostazione di un samplingRate per l'ambiente di runtime, vedi Considerazioni sul rendimento.
    • Il parametro exporter è impostato su CLOUD_TRACE.
    • L'endpoint è impostato sul progetto Google Cloud a cui vuoi inviare la traccia. NOTA: questo valore deve corrispondere al service account che è stato creato nel passaggio di configurazione.

    Una risposta corretta è simile alla seguente:

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

Attivare il tracciamento distribuito per Jaeger

L'esempio seguente mostra come abilitare la tracciabilità distribuita 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 a Distributed Tracing.
  • 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
  }
}

Visualizzare la configurazione di tracciamento distribuito

Per visualizzare la configurazione di tracciamento distribuito 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 del tracciamento distribuito

Il seguente comando mostra come aggiornare la configurazione della tracciabilità distribuita 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.

Disattiva la configurazione del tracciamento distribuito

L'esempio seguente mostra come disattivare la traccia distribuita configurata 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
  }
}

Eseguire l'override delle impostazioni di traccia per i proxy API

Quando abiliti il tracciamento distribuito in Apigee Runtime, tutti i proxy API nel runtime utilizzano la stessa configurazione per il tracciamento. Tuttavia, puoi ignorare la configurazione del tracciamento distribuito per un proxy API o un gruppo di proxy API. In questo modo avrai un controllo più granulare sulla configurazione della tracciatura.

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 ignorare la configurazione per risolvere i problemi specifici di un proxy API senza dover modificare la configurazione di tutti i proxy API.

Aggiornare gli 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 "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 di traccia

Per eliminare 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 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 abiliti la tracciabilità distribuita per un ambiente di runtime Apigee, è previsto un impatto sulle prestazioni. L'impatto può comportare un aumento dell'utilizzo della memoria, dei requisiti della CPU e della latenza. L'entità dell'impatto dipenderà in parte dalla complessità del proxy API (ad esempio, il numero di policy) e dalla frequenza di campionamento probabilistico (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 aspettarti un calo delle prestazioni del 10-20% quando utilizzi la tracciabilità distribuita.

Per gli ambienti con requisiti di traffico elevato e bassa latenza, il tasso di campionamento probabilistico consigliato è inferiore o uguale al 10%. Se vuoi utilizzare la tracciabilità distribuita per la risoluzione dei problemi, valuta la possibilità di aumentare il campionamento probabilistico (samplingRate) solo per proxy API specifici.