Tracciamento dell'API

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 i controlli necessari prima di inoltrare la richiesta al backend dell'API. Quando il backend backend risponde, il proxy raccoglie e registra la telemetria. Un dato di telemetria acquisito dal proxy è il tracciamento tramite Cloud Trace.

In questa pagina viene spiegato come:

  • Visualizza le tracce in Google Cloud Console.
  • Stima il costo di Trace.
  • Configura il proxy per disabilitare il campionamento delle tracce.

Visualizzazione delle tracce

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

Per visualizzare le tracce relative al tuo progetto, vai alla pagina Cloud Trace in Google Cloud Console:

Vai a Trace

Nella pagina Elenco di tracce puoi visualizzare i dati in dettaglio per visualizzare una singola traccia e visualizzare le sezioni create da ESP in una traccia. Puoi utilizzare il filtro per visualizzare le tracce di una singola API o di una singola operazione.

Le tracce e gli intervalli creati per l'API variano in base all'utilizzo dell'API ESPv2 o ESP. Di seguito è riportato un riepilogo dei formati di traccia per ciascuna implementazione.

Per ulteriori informazioni sulla pagina Elenco di tracce, consulta la sezione Visualizzare le tracce in Google Cloud Console.

Intervalli creati da ESPv2

ESPv2 crea tracce nel seguente formato:

Esempio di traccia con sezioni per ESPv2

Come minimo, ESPv2 crea 2 intervalli per traccia:

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

A seconda della configurazione dell'API, ESPv2 potrebbe 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 recupera e memorizza la chiave pubblica nella cache e crea uno span 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 sono nella cache, ESPv2 chiama Service Control e crea uno span 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 traccia non verranno tracciate. 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 hanno intervalli associati nelle tracce.
  • 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 alla traccia.

Intervalli creati da ESP

ESP crea tracce nel seguente formato:

Esempio di traccia con sezioni per ESP

Come minimo, ESP crea 4 intervalli per traccia:

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

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

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

Frequenza di campionamento

ESP campiona un numero limitato di richieste alla tua API per ottenere dati di traccia. Per controllare la frequenza di campionamento, ESP gestisce un contatore delle richieste e un timer. La frequenza di campionamento dipende dal numero di richieste al secondo inviate alla tua API. Se non vengono ricevute richieste entro un secondo, ESP non invia una 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.

In breve, 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 una stima del 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 nella pagina Endpoint > Servizi o Cloud Logging. Per ulteriori informazioni, consulta la pagina 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 in Span create da ESP o visualizzare la pagina Elenco di tracce per visualizzare le tracce relative alla tua API.
  4. Stima il numero di secondi di un mese in cui l'API riceve il traffico. Ad esempio, alcune API ricevono richieste solo in determinate ore del giorno, mentre altre API li ricevono sporadicamente.
  5. Moltiplica il numero di secondi nel 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 da ESP per traccia è pari a 4.
  4. Questa API riceve le richieste solo durante l'orario di apertura, dal lunedì al venerdì. Il numero di secondi in un mese in cui l'API riceve il traffico è circa: 3600 x 8 x 20 = 576.000
  5. Il numero di intervalli al mese è di circa 576.000 x 4 = 2.304.000

Una volta appurato il numero approssimativo di intervalli in un mese, consulta la pagina Prezzi di traccia per informazioni dettagliate sui prezzi.

Disabilitazione del campionamento delle tracce

Se vuoi impedire a ESP di campionare le richieste e inviare tracce, puoi impostare un'opzione di avvio ESP e riavviare. Le tracce inviate da ESP 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 la procedura di deployment. Per ulteriori informazioni, consulta 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 l'interfaccia a riga di comando di Google Cloud, esegui il comando seguente:
    gcloud components update
    
  3. Salva il file (o i file) app.yaml.
  4. Esegui il deployment del tuo 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 tuo 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 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 --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 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 container Docker, non esiste una coppia chiave-valore dei metadati dell'istanza 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 nella sezione 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 disattivato il campionamento.

Monitora la propagazione del contesto

Per il tracciamento distribuito, un'intestazione della 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 utilizzato per cercare tutte le tracce e unire gli intervalli per una singola richiesta. Se nella richiesta non è specificato alcun contesto di traccia e l'opzione Traccia è abilitata, viene generato un ID traccia casuale per tutti gli intervalli di traccia.

Nell'esempio seguente, Cloud Trace è caratterizzato da intervalli creati da ESPv2 (1) e da intervalli creati dal backend (2) per una singola richiesta. Questo consente di eseguire il debug dei problemi di latenza nell'intero sistema:

Esempio di propagazione del contesto di traccia per ESPv2

Per ulteriori informazioni, leggi la pagina OpenTelemetry Core Concetti: Propagation del contesto

Intestazioni supportate

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

  • traceparent: l'intestazione di propagazione del contesto W3C standard. Supportati dalla maggior parte dei framework di tracciamento moderni.
  • x-cloud-trace-context: intestazione di propagazione del contesto di traccia di GCP. Supportato da framework di tracciamento più vecchi e librerie di Google, ma specifico per i fornitori.
  • grpc-trace-bin: intestazione di propagazione del contesto utilizzata dai backend gRPC con la libreria di tracciamento OpenCensus.

Se stai creando una nuova applicazione, ti consigliamo di utilizzare la propagazione del contesto di traccia traceparent. Per impostazione predefinita, ESPv2 estrae e propaga questa intestazione. Per informazioni dettagliate sulla modifica del comportamento predefinito, consulta la sezione Opzioni di avvio per il tracciamento ESPv2.