Tracciamento dell'API

OpenAPI   |  gRPC

Dopo aver eseguito il deployment di Extensible Service Proxy (ESP) o Extensible Service Proxy V2 (ESPv2) e del codice di backend dell'API, il proxy intercetta tutte le richieste ed esegue tutti i controlli necessari prima di inoltrare la richiesta al backend dell'API. Quando il backend risponde, il proxy raccoglie e segnala i dati di telemetria. Un dato di telemetria che il proxy acquisisce, viene tracciato utilizzando Cloud Trace.

In questa pagina viene spiegato come:

• Visualizza le tracce nella console Google Cloud.
• Stima il costo per Trace.
• Configura il proxy per disabilitare il campionamento delle tracce.

Visualizzazione delle tracce

Una traccia monitora una richiesta in entrata alla tua API e i vari eventi (come chiamate RPC o sezioni di codice instrumentate), insieme alle tempistiche precise di ogni evento. Questi eventi sono rappresentati come intervalli nella traccia.

Per visualizzare le tracce del progetto, vai alla pagina Cloud Trace nella console Google Cloud:

Vai a Trace

Nella pagina Esplora traccia, puoi visualizzare in dettaglio una singola traccia e vedere gli intervalli creati da ESP in una traccia. Puoi utilizzare il filtro per visualizzare le tracce per una singola API o operazione.

Le tracce e gli intervalli creati per l'API saranno diversi a seconda che l'API utilizzi ESPv2 o ESP. Di seguito è riportato un riepilogo dei formati di traccia per ogni implementazione.

Per ulteriori informazioni sulla pagina Esplora traccia, consulta Trovare ed esplorare tracce.

Intervalli creati da ESPv2

ESPv2 crea tracce nel seguente formato:

ESPv2 crea almeno due intervalli per traccia:

• Un intervallo ingress OPERATION_NAME per l'intera richiesta e risposta.
• Un intervallo router BACKEND egress per il tempo ESPv2 attende che il backend elabori la richiesta e risponda. Questo include l'hop di rete tra ESPv2 e il backend.

A seconda della configurazione della tua API, ESPv2 potrebbe creare intervalli aggiuntivi:

• Se la tua API richiede l'autenticazione, ESPv2 memorizza nella cache la chiave pubblica necessaria per l'autenticazione per 5 minuti. Se la chiave pubblica non è nella cache, ESPv2 recupera e memorizza nella cache la chiave pubblica e crea un intervallo JWT Remote PubKey Fetch.
• Se la tua API richiede una chiave API, ESPv2 memorizza nella cache le informazioni necessarie per convalidare la chiave API. Se le informazioni non sono nella cache, ESPv2 chiama Service Control e crea un intervallo Service Control remote call: Check.

In generale, ESPv2 crea intervalli solo per le chiamate di rete che bloccano la richiesta in entrata. Le richieste che non bloccano la registrazione non verranno analizzate. Qualsiasi elaborazione locale creerà eventi temporali anziché intervalli. Ad esempio:

• L'applicazione della quota richiede chiamate remote, ma le chiamate non si verificano nel percorso di una richiesta API e non avranno intervalli associati nella traccia.
• Le chiavi API vengono memorizzate nella cache da ESPv2 per un breve periodo di tempo. Tutte le richieste che utilizzano la cache avranno un evento temporale associato nella traccia.

Intervalli creati da ESP

Avviso: l'ESP non ha fornito informazioni dettagliate per gli intervalli. Crea anche intervalli extra non significativi. Esegui la migrazione a ESPv2 per visualizzare tracce dettagliate che seguono le best practice di tracciamento.

ESP crea tracce nel seguente formato:

Come minimo, ESP crea 4 intervalli per traccia:

• Un intervallo per l'intera richiesta e risposta.
• Un intervallo CheckServiceControl per la chiamata al metodo Service Control services.check per ottenere la configurazione dell'API.
• Un intervallo QuotaControl per verificare se nell'API è stata configurata una quota.
• Un intervallo Backend che monitora il tempo speso nel codice di backend dell'API.

A seconda della configurazione dell'API, ESP crea intervalli aggiuntivi:

• Se l'API richiede l'autenticazione, ESP crea un intervallo CheckAuth in ogni traccia. Per autenticare una richiesta, ESP memorizza nella cache la chiave pubblica necessaria per l'autenticazione per 5 minuti. Se la chiave pubblica non è nella cache, ESP recupera e memorizza nella cache la chiave pubblica e crea un intervallo HttpFetch.
• Se la tua API richiede una chiave API, ESP crea un intervallo CheckServiceControlCache in ogni traccia. ESP memorizza nella cache le informazioni necessarie per convalidare la chiave API. Se le informazioni non sono nella cache, ESP chiama Service Control e crea un intervallo Call ServiceControl server.
• Se hai impostato una quota per la tua API, ESP crea un intervallo QuotaServiceControlCache in ogni traccia. ESP memorizza nella cache le informazioni necessarie per controllare la quota. Se le informazioni non sono nella cache, ESP chiama Service Control e crea un intervallo Call ServiceControl server.

Frequenza di campionamento delle Trace

ESP campiona un numero ridotto di richieste all'API per ottenere dati di traccia. Per controllare la frequenza di campionamento, ESP gestisce un contatore di richieste e un timer. Il numero di richieste al secondo alla tua API determina la frequenza di campionamento. Se non ci sono richieste entro un secondo, ESP non invia alcuna traccia.

Se il numero di richieste in un secondo è:

• Minore o uguale a 999, ESP invia 1 traccia.
• Tra il 1000 e il 1999, ESP invia 2 tracce.
• Tra il 2000 e il 2999, ESP invia 3 tracce.
• e così via.

Per riassumere, puoi stimare la frequenza di campionamento con la funzione ceiling: ceiling(requests per second/1000)

Stima del costo di Trace

Per stimare il costo di Trace, devi stimare il numero di intervalli che ESP invia a Trace in un mese.

Per stimare il numero di intervalli per mese:

1. Stimare il numero di richieste al secondo per la tua API. Per ottenere questa stima, puoi utilizzare il grafico Richieste nella pagina Endpoint > Servizi o Cloud Logging. Per ulteriori informazioni, consulta Monitoraggio dell'API.
2. Calcola il numero di tracce che ESP invia a Trace al secondo: ceiling(requests per second/1000)
3. Stimare il numero di intervalli in una traccia. Per ottenere questa stima, puoi utilizzare le informazioni contenute negli intervalli creati da ESP o visualizzare la pagina Elenco di tracce per visualizzare le tracce per l'API.
4. Stima il numero di secondi in un mese in cui l'API riceve traffico. Ad esempio, alcune API ricevono richieste solo in determinate ore del giorno, mentre altre API ricevono richieste sporadicamente.
5. Moltiplica il numero di secondi del mese per il numero di intervalli.

Ad esempio:

1. Supponiamo che il numero massimo di richieste al secondo per un'API sia 5.
2. La frequenza di campionamento delle tracce è massima (5/1000) = 1
3. L'API non ha una quota configurata, non richiede una chiave API e non richiede l'autenticazione. Pertanto, il numero di intervalli creati da ESP per traccia è 4.
4. Questa API riceve richieste solo durante l'orario lavorativo, dal lunedì al venerdì. Il numero di secondi in un mese in cui l'API riceve traffico è pari a circa: 3600 X 8 X 20 = 576.000
5. Il numero di intervalli al mese è pari a circa 576.000 x 4 = 2.304.000

Dopo aver stabilito il numero approssimativo di intervalli in un mese, consulta la pagina Prezzi di Trace per informazioni dettagliate sui prezzi.

Disabilitazione del campionamento delle tracce

Se vuoi impedire a ESP di campionare le richieste e di inviare le tracce, puoi impostare un'opzione di avvio ESP e riavviare ESP. Le tracce che ESP invia a Cloud Trace sono indipendenti dai grafici visualizzati nella pagina Endpoint > Servizi. I grafici continuano a essere disponibili se disabiliti il campionamento delle tracce.

La sezione seguente presuppone che tu abbia già eseguito il deployment dell'API e dell'ESP o che tu abbia familiarità con il processo di deployment. Per ulteriori informazioni, consulta la pagina relativa al deployment del backend dell'API.

App Engine

Per disabilitare il campionamento delle tracce ESP nell'ambiente flessibile di App Engine:

1. Modifica il file app.yaml. Nella sezione endpoints_api_service, aggiungi l'opzione trace_sampling e imposta il valore su false. Ad esempio:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false
   

   Se la tua applicazione è basata su microservizi, devi includere trace_sampling: false in ogni file app.yaml.

2. Se non hai aggiornato Google Cloud CLI di recente, esegui questo comando:

   gcloud components update
   

3. Salva i file app.yaml.
4. Esegui il deployment del codice di backend e dell'ESP in App Engine:

   gcloud app deploy
   

Per riattivare il campionamento delle tracce:

1. Rimuovi l'opzione trace_sampling da app.yaml.
2. Esegui il deployment del codice di backend e dell'ESP in App Engine:

   gcloud app deploy
   

Compute Engine

Per disabilitare il campionamento delle tracce ESP in Compute Engine con Docker:

1. Connettiti all'istanza VM:

   gcloud compute ssh [INSTANCE_NAME]

2. Nei flag ESP per il comando docker run, aggiungi l'opzione --disable_cloud_trace_auto_sampling:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. Esegui il comando docker run per riavviare ESP.

Per riattivare il campionamento delle tracce:

1. Rimuovi l'--disable_cloud_trace_auto_sampling.
2. Esegui il comando docker run per riavviare ESP.

GKE

Per disabilitare il campionamento delle tracce ESP in GKE:

1. Apri il file manifest di deployment, chiamato deployment.yaml, e aggiungi quanto segue alla sezione containers:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. Avvia il servizio Kubernetes utilizzando il comando kubectl create:

   kubectl create -f deployment.yaml

Per riattivare il campionamento delle tracce:

1. Rimuovi l'opzione --disable_cloud_trace_auto_sampling.
2. Avvia il servizio Kubernetes:

   kubectl create -f deployment.yaml

Se esegui ESP su un'istanza VM di Compute Engine senza un container Docker, non esiste una coppia chiave-valore di metadati di istanze VM equivalente per l'opzione --disable_cloud_trace_auto_sampling. Se vuoi disabilitare il campionamento delle tracce, devi eseguire ESP in un container.

Un client può forzare il tracciamento di una richiesta aggiungendo l'intestazione X-Cloud-Trace-Context alla richiesta, come descritto in Forzare il tracciamento di una richiesta. Se una richiesta contiene l'intestazione X-Cloud-Trace-Context, ESP invia i dati di traccia a Trace anche se hai disabilitato il campionamento delle tracce.

Propagazione del contesto delle tracce

Per il tracciamento distribuito, l'intestazione di una richiesta può contenere un contesto di traccia che specifica un ID traccia. L'ID traccia viene utilizzato quando ESPv2 crea nuovi intervalli di traccia e li invia a Cloud Trace. L'ID traccia viene usato per cercare tutte le tracce e gli intervalli di join per una singola richiesta. Se nella richiesta non viene specificato alcun contesto della traccia e la traccia è abilitata, viene generato un ID traccia casuale per tutti gli intervalli di traccia.

Nell'esempio seguente, Cloud Trace correla gli intervalli creati da ESPv2 (1) con gli intervalli creati dal backend (2) per una singola richiesta. Ciò consente di eseguire il debug dei problemi di latenza nell'intero sistema:

Per ulteriori dettagli, leggi la sezione Concetti principali di OpenTelemetry: Propagazione del contesto

Nota: il tracciamento distribuito richiede che i tuoi client e/o i tuoi backend supportino il tracciamento. Questo non rientra nell'ambito di questa documentazione. Ti consigliamo di utilizzare OpenTelemetry.

Intestazioni supportate

ESPv2 supporta le seguenti intestazioni di propagazione del contesto di traccia:

• traceparent: l'intestazione di propagazione del contesto per la traccia W3C standard. Supportato dalla maggior parte dei framework di tracciamento più moderni.
• x-cloud-trace-context: intestazione di propagazione del contesto della traccia di Google Cloud. Supportati da framework di tracciamento meno recenti e dalle librerie di Google, ma specifici del fornitore.
• grpc-trace-bin: Trace di propagazione del contesto delle tracce utilizzata dai backend gRPC con la libreria di tracciamento OpenCensus.

Se stai creando una nuova applicazione, ti consigliamo di utilizzare la propagazione del contesto della traccia traceparent. ESPv2 estrarrà e propagherà questa intestazione per impostazione predefinita. Per maggiori dettagli sulla modifica del comportamento predefinito, consulta Opzioni di tracciamento di ESPv2 per l'avvio.

Nota: a differenza di ESPv2, la propagazione del contesto della traccia in ESP deve essere abilitata manualmente tramite le opzioni di avvio. ESP non supporta l'intestazione traceparent.