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 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 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 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'elemento 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'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 (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:

  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 confermare 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, 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 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 utilizzando Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

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:

  1. 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 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 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 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 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
  }
}
 In questo esempio, la frequenza di campionamento viene aggiornata a 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:

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