Tracciamento dell'API

OpenAPI   | gRPC

Dopo aver eseguito il deployment Extensible Service Proxy (ESP) oppure Extensible Service Proxy V2 (ESPv2) e lo spazio dei nomi di rete di backend, il proxy intercetta tutte le richieste ed esegue i controlli necessari prima di inoltrare la richiesta al backend dell'API. Quando di risposta, il proxy raccoglie e segnala i dati di telemetria. Un pezzo di dati di telemetria tracciati dal proxy mediante l'uso Cloud Trace.

In questa pagina viene spiegato come:

• Visualizza le tracce nella console Google Cloud.
• Stima i costi per Trace.
• Configura il proxy per disabilitare il campionamento della traccia.

Visualizzazione delle tracce

Una traccia monitora una richiesta in entrata all'API e i vari eventi (come chiamate RPC o sezioni di codice strumentate), insieme orari di ogni evento. Questi eventi sono rappresentati come intervalli nella traccia.

Per visualizzare le tracce per il tuo progetto, vai alla pagina di Cloud Trace nella console Google Cloud:

Vai a Trace

Nella pagina Esplora tracce puoi visualizzare in dettaglio una singola traccia e controllare 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 la tua API variano a seconda che l'API utilizzi ESPv2 o ESP. Di seguito è riportato un riepilogo dei formati di traccia per ogni implementazione.

Per ulteriori informazioni nella pagina Explorer Trace, vedi Trovare ed esplorare le tracce.

Intervalli creati da ESPv2

ESPv2 crea le 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 in cui ESPv2 aspetta che il backend elabori la richiesta e risponda. Sono inclusi l'hop di rete tra ESPv2 e il backend.

A seconda della configurazione dell'API, ESPv2 può creare intervalli aggiuntivi:

• Se l'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 la recupera e la memorizza nella cache e crea uno spazio JWT Remote PubKey Fetch.
• Se l'API richiede una chiave API, ESPv2 memorizza nella cache le informazioni necessarie per convalidare la chiave API. Se le informazioni non è nella cache, ESPv2 chiama Service Control e crea un intervallo Service Control remote call: Check.

In generale, ESPv2 crea span solo per le chiamate di rete che bloccano la richiesta in entrata. Le richieste che non comportano il blocco non verranno tracciate. Qualsiasi locale l'elaborazione creerà eventi temporali anziché sulle sezioni. Ad esempio:

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

Intervalli creati da ESP

Avviso: ESP non fornisce informazioni dettagliate per gli intervalli. it crea anche intervalli extra non significativi. Non dimenticare di apporre eseguire la migrazione a ESPv2 per visualizzare e 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 la risposta.
• Uno spazio CheckServiceControl per la chiamata al metodo services.check di Controllo servizio per ottenere la configurazione dell'API.
• Un intervallo QuotaControl per verificare se è presente quota configurate nell'API.
• Un intervallo Backend che monitora il tempo trascorso nel codice di backend dell'API.

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

• Se l'API richiede l'autenticazione, ESP crea un 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, l'ESP la recupera e la memorizza nella cache e crea uno spazio HttpFetch.
• Se l'API richiede una chiave API, ESP crea una CheckServiceControlCache intervallo in ogni traccia. Cache ESP le informazioni necessarie per convalidare la chiave API. Se le informazioni non si trova nella cache, ESP chiama Service Control e crea un intervallo Call ServiceControl server.
• Se hai impostato una quota per l'API, ESP crea una QuotaServiceControlCache intervallo in ogni traccia. Cache ESP 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 della traccia

ESP campiona un numero ridotto di richieste alla tua API per recuperare la traccia e i dati di Google Cloud. Per controllare la frequenza di campionamento, ESP gestisce un contatore delle richieste e un timer. Il numero di richieste al secondo per la tua API determina la frequenza di campionamento. Se non ricevi 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.

Riassumendo, puoi stimare la frequenza di campionamento con Funzione ceiling: ceiling(requests per second/1000)

Stima del costo di Trace

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

Per stimare il numero di intervalli al mese:

1. Stima il numero di richieste al secondo alla tua API. Per ottenere questa stima, puoi utilizzare il grafico Richieste negli Endpoint > Pagina Servizi o Cloud Logging. Consulta Monitoraggio dell'API per ulteriori informazioni.
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 in Span create da ESP oppure visualizza la pagina Elenco tracce per vedere le tracce per l'API.
4. Stima il numero di secondi in un mese in cui la tua API riceve traffico. Ad esempio, alcune API ricevono richieste solo in determinati momenti della giornata, mentre altre ricevono richieste sporadicamente.
5. Moltiplica il numero di secondi di un 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 della traccia è 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 dall'ESP per traccia è 4.
4. Questa API riceve richieste solo durante l'orario di apertura, dal lunedì al venerdì. Il numero di secondi in un mese in cui l'API riceve traffico è approssimativamente: 3600 X 8 X 20 = 576.000
5. Il numero di intervalli al mese è di circa 576.000 x 4 = 2.304.000

Quando conosci il numero approssimativo di intervalli in un mese, fai riferimento alla Prezzi di Trace per informazioni dettagliate sui prezzi.

Disattivare il campionamento delle tracce

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

La sezione seguente presuppone che tu abbia già eseguito il deployment dell'API e o hai familiarità con il processo di deployment. Per ulteriori informazioni le informazioni, vedi Deployment del backend dell'API.

App Engine

Per disabilitare il campionamento della traccia 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 relativo 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 di 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 di ESP in App Engine:

   gcloud app deploy

Compute Engine

Per disabilitare il campionamento della traccia ESP in Compute Engine con Docker:

1. Connettiti alla tua 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 --disable_cloud_trace_auto_sampling.
2. Esegui il comando docker run per riavviare ESP.

GKE

Per disabilitare il campionamento della traccia ESP in GKE:

1. Apri il file manifest del deployment, denominato 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 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 esistono metadati equivalenti delle istanze VM coppia chiave-valore per l'opzione --disable_cloud_trace_auto_sampling. Se Se vuoi disabilitare il campionamento della traccia, devi eseguire ESP in un container.

Un client può forzare il tracciamento di una richiesta aggiungendo X-Cloud-Trace-Context l'intestazione alla richiesta, come descritto 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 l'hai disabilitata campionamento.

Propagazione del contesto traccia

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

Nell'esempio seguente, Cloud Trace correla gli span creati da ESPv2 (1) con gli span creati dal backend (2) per una singola richiesta. In questo modo è possibile eseguire il debug della latenza dei problemi nell'intero sistema:

Per maggiori dettagli, leggi i concetti principali di OpenTelemetry: propagazione del contesto

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

Intestazioni supportate

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

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

Se stai creando una nuova applicazione, ti consigliamo di utilizzare la traccia traceparent la propagazione del contesto. ESPv2 estrarrà e propaga questa intestazione per impostazione predefinita. Consulta le opzioni di avvio di tracciamento ESPv2 per informazioni dettagliate sulla modifica del comportamento predefinito.

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