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 registra la telemetria. Uno dei dati di telemetria acquisiti dal proxy è il monitoraggio, utilizzando Cloud Trace.

Questa pagina spiega come:

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

Visualizzazione delle tracce

Una traccia monitora una richiesta in arrivo alla tua API e i vari eventi (ad esempio chiamate RPC o sezioni di codice sottoposte a ispezione), nonché i relativi tempi esatti. Questi eventi sono rappresentati come span nella traccia.

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

Vai a Trace

Nella pagina Esploratore di traccia, puoi visualizzare in dettaglio una singola traccia e vedere gli intervalli creati dall'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 sulla pagina Esplora tracce, consulta Trovare ed esplorare le tracce.

Span creati da ESPv2

ESPv2 crea le tracce nel seguente formato:

Come minimo, ESPv2 crea due intervalli per traccia:

• Un intervallo ingress OPERATION_NAME per l'intera richiesta e risposta.
• Un intervallo router BACKEND egress per il tempo necessario a ESPv2 per elaborare la richiesta e rispondere. Sono inclusi l'hop di rete tra ESPv2 e il backend.

A seconda della configurazione dell'API, ESPv2 potrebbe creare ulteriori intervalli:

• 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 la recupera e la memorizza nella cache e crea uno spazio JWT Remote PubKey Fetch.
• Se la tua API richiede una chiave API, ESPv2 memorizza nella cache le informazioni di cui ha bisogno per convalidare la chiave API. Se le informazioni non sono nella cache, ESPv2 chiama Service Control e crea uno span Service Control remote call: Check.

In generale, ESPv2 crea span solo per le chiamate di rete che bloccano la richiesta in arrivo. Le richieste non bloccanti non verranno tracciate. Qualsiasi elaborazione locale creerà eventi di tempo anziché intervalli. Ad esempio:

• L'applicazione della quota richiede chiamate remote, ma queste 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. A tutte le richieste che utilizzano la cache sarà associato un evento di tempo nella traccia.

Span creati da ESP

Avviso: ESP non fornisce informazioni dettagliate per gli intervalli. Inoltre, crea elementi aggiuntivi non significativi. Esegui la migrazione a ESPv2 per visualizzare tracce dettagliate che seguono le best practice per il monitoraggio.

ESP crea le tracce nel seguente formato:

L'ESP crea almeno quattro intervalli per traccia:

• Un intervallo per l'intera richiesta e risposta.
• Uno span CheckServiceControl per la chiamata al metodo services.check di Controllo servizio per ottenere la configurazione dell'API.
• Uno spazio QuotaControl per verificare se è stata configurata una quota nella tua API.
• Uno span 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 uno span 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 la tua API richiede una chiave API, ESP crea un CheckServiceControlCache span in ogni traccia. L'ESP memorizza nella cache le informazioni di cui ha bisogno per convalidare la chiave API. Se le informazioni non sono nella cache, l'ESP chiama Service Control e crea uno span Call ServiceControl server.
• Se hai impostato una quota per la tua API, ESP crea un QuotaServiceControlCache intervallo in ogni traccia. L'ESP memorizza nella cache le informazioni di cui ha bisogno per controllare la quota. Se le informazioni non sono nella cache, ESP chiama Service Control e crea un Call ServiceControl server span.

Frequenza di campionamento della traccia

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

Se il numero di richieste in un secondo è:

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

In sintesi, 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 inviati dall'ESP a Trace in un mese.

Per stimare il numero di span al mese:

1. Stimare il numero di richieste al secondo alla tua API. Per ottenere questa stima, puoi utilizzare il grafico Richieste nella pagina Endpoint > Servizi o Cloud Logging. Per ulteriori informazioni, consulta la sezione Monitoraggio dell'API.
2. Calcola il numero di tracce inviate dall'ESP a Trace al secondo: ceiling(requests per second/1000)
3. Stima il numero di intervalli in una traccia. Per ottenere questa stima, puoi utilizzare le informazioni riportate in Spazi creati dall'ESP o visualizzare la pagina Elenco Trace per vedere le tracce per la tua 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 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 della traccia è il massimo (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 lavoro, 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

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

Disattivare il campionamento delle tracce

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

La sezione seguente presuppone che tu abbia già eseguito il deployment dell'API e dell'ESP o che tu abbia dimestichezza con la procedura di deployment. Per maggiori informazioni, consulta la sezione Eseguire il deployment del backend dell'API.

App Engine

Per disattivare 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 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 di recente non hai aggiornato Google Cloud CLI, esegui il seguente comando:

   gcloud components update

3. Salva il file (o 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 disattivare 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 l'ESP.

Per riattivare il campionamento delle tracce:

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

GKE

Per disattivare il campionamento delle tracce ESP in GKE:

1. Apri il file manifest di 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 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 contenitore Docker, non esiste una coppia chiave-valore dei metadati dell'istanza VM equivalente per l'opzione --disable_cloud_trace_auto_sampling. Se vuoi disattivare il campionamento delle tracce, devi eseguire ESP in un contenitore.

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

Propagazione del contesto traccia

Per il monitoraggio distribuito, un'intestazione della richiesta può contenere un contesto 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 utilizzato per cercare tutte le tracce e unire gli span per una singola richiesta. Se nella richiesta non viene 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 puoi eseguire il debug dei problemi di latenza nell'intero sistema:

Per maggiori dettagli, leggi Concetti fondamentali di OpenTelemetry: propagazione del contesto.

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

Intestazioni supportate

ESPv2 supporta le seguenti intestazioni di propagazione del contesto traccia:

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

Se stai creando una nuova applicazione, ti consigliamo di utilizzare la traceparentpropagazione del contesto della traccia. ESPv2 estrae e propaga questa intestazione per impostazione predefinita. Per maggiori dettagli sulla modifica del comportamento predefinito, consulta Opzioni di avvio del monitoraggio ESPv2.

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