Questa pagina è stata tradotta dall'API Cloud Translation.

Monitoraggio dell'utilizzo delle API

Questa pagina descrive come utilizzare le metriche API per monitorare e comprendere l'utilizzo delle API Google e Google Cloud.

Le API Google producono metriche dettagliate sull'utilizzo che possono aiutarti a:

Monitora e comprendi il tuo utilizzo delle API di Google.
Monitora le prestazioni delle tue applicazioni e delle API Google.
Scopri i problemi tra le tue applicazioni e le API Google.

Può accelerare notevolmente i tempi di risoluzione quando risolvi i problemi o hai bisogno di assistenza tecnica da Google.

Le metriche prodotte dalle API di Google sono gli indicatori standard utilizzati dai professionisti della Site Reliability di Google per valutare l'integrità di un servizio. Queste metriche coprono conteggi delle richieste, tassi di errore, latenze totali, latenze del backend, dimensioni delle richieste e dimensioni delle risposte. Per le definizioni delle metriche dell'API, consulta la documentazione di Cloud Monitoring.

Puoi visualizzare le metriche delle API in due posizioni: Dashboard delle API e Cloud Monitoring. Le metriche visualizzate sono specifiche per il progetto e non riflettono lo stato complessivo del servizio.

Utilizzo della dashboard dell'API

Il modo più semplice per visualizzare le metriche dell'API è utilizzare la dashboard API della console Google Cloud. Puoi visualizzare una panoramica di tutto l'utilizzo delle API o puoi visualizzare in dettaglio l'utilizzo di un'API specifica.

Per visualizzare una panoramica dell'utilizzo delle API:

Visita la sezione API e servizi della console Cloud. Per impostazione predefinita viene visualizzata la dashboard principale dell'API. In questa pagina puoi visualizzare tutte le API attualmente abilitate per il tuo progetto, nonché i grafici di panoramica per le seguenti metriche:
- Traffico: il numero di richieste al secondo effettuate dal progetto o relative al progetto alle API abilitate
- Errori: la percentuale di richieste alle API abilitate che hanno generato errori
- Latenza mediana: la latenza mediana per le richieste alle API abilitate, se disponibile.

Per visualizzare i dettagli di utilizzo di un'API specifica:

Seleziona l'API che vuoi visualizzare nell'elenco principale delle API della dashboard. La pagina Panoramica dell'API mostra un grafico del traffico più dettagliato con una suddivisione in base al codice di risposta.
Per informazioni sull'utilizzo ancora più dettagliate, seleziona Visualizza metriche. Per impostazione predefinita, vengono visualizzati i seguenti grafici predefiniti, anche se sono disponibili altri:
- Traffico per codice di risposta
- Errori per metodo API
- Latenza complessiva al 50°, 95° e 99° percentile
- Latenza per metodo API (mediana)
Se vuoi aggiungere altri grafici, puoi selezionare altri grafici predefiniti dal menu a discesa Seleziona grafici.

Utilizzo di Cloud Monitoring

Se utilizzi Cloud Monitoring, puoi approfondire i dati delle metriche disponibili utilizzando Metrics Explorer per ottenere informazioni più dettagliate sull'utilizzo dell'API. Cloud Monitoring supporta un'ampia gamma di metriche, che possono essere combinate con filtri e aggregazioni per ottenere punti di vista nuovi e significativi sul rendimento delle applicazioni. Ad esempio, puoi combinare una metrica di conteggio delle richieste con un filtro sulla classe del codice di risposta HTTP per creare una dashboard che mostri i tassi di errore nel tempo oppure puoi esaminare la latenza del 95° percentile delle richieste all'API Cloud Pub/Sub.

Metriche disponibili

La tabella seguente elenca le metriche serviceruntime disponibili. Le metriche relative all'utilizzo dell'API sono quelle che includono consumed_api come risorsa monitorata.

Le stringhe "tipo metrica" in questa tabella devono essere precedute dal prefisso serviceruntime.googleapis.com/. Questo prefisso è stato omesso dalle voci della tabella. Quando esegui una query su un'etichetta, utilizza il prefisso metric.labels., ad esempio metric.labels.LABEL="VALUE".

Tipo di metrica ^{Fase di lancio} (livelli della gerarchia delle risorse) Nome visualizzato
Tipo, Tipo, Unità Risorse monitorate	Descrizione Etichette
`api/request_count` ^GA *(project)* Conteggio richieste
`DELTA`, `INT64`, `1` api consumed_api produced_api	Il numero di richieste completate. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi. `protocol`: Il protocollo della richiesta, ad esempio "http", "grpc". `response_code`: il codice di risposta HTTP per le richieste HTTP o il codice equivalente HTTP per le richieste gRPC. Consulta la mappatura del codice in https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto. `response_code_class`: La classe del codice di risposta per le richieste HTTP o la classe equivalente HTTP per le richieste gRPC, ad esempio "2xx", "4xx". `grpc_status_code`: il codice di risposta gRPC numerico per le richieste gRPC o il codice equivalente gRPC per le richieste HTTP. Consulta la mappatura del codice in https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto.
`api/request_latencies` ^GA *(project)* Latenze delle richieste
`DELTA`, `DISTRIBUTION`, `s` api consumed_api produced_api	Distribuzione delle latenze in secondi per le richieste non in streaming. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi.
`api/request_latencies_backend` ^GA *(project)* Latenze del backend delle richieste
`DELTA`, `DISTRIBUTION`, `s` api produced_api	Distribuzione delle latenze del backend in secondi per le richieste non in streaming. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi.
`api/request_latencies_overhead` ^GA *(project)* Latenze dell'overhead della richiesta
`DELTA`, `DISTRIBUTION`, `s` api produced_api	Distribuzione delle latenze delle richieste in secondi per le richieste non in streaming, escluso il backend. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi.
`api/request_sizes` ^GA *(project)* Dimensioni delle richieste
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	Distribuzione delle dimensioni delle richieste in byte registrate al termine della richiesta. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi.
`api/response_sizes` ^GA *(project)* Dimensioni di risposta
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	Distribuzione delle dimensioni delle risposte in byte registrate al termine della richiesta. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 1800 secondi.
`quota/allocation/usage` ^GA *(project, folder, organization)* Utilizzo della quota di allocazione
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	La quota di allocazione totale utilizzata. I valori registrati superiori a 1/min vengono ignorati. Se non vengono ricevute modifiche nell'utilizzo della quota, l'ultimo valore viene ripetuto almeno ogni 24 ore. Campionamento eseguito ogni 60 secondi. `quota_metric`: il nome della metrica della quota o del gruppo di quota.
`quota/concurrent/exceeded` ^ALPHA *(project, folder, organization)* Quota simultanea superata
`DELTA`, `INT64`, `1` consumer_quota	Il numero di tentativi di superamento della quota simultanea. Campionamento eseguito ogni 86.400 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 180 secondi. `limit_name`: il nome del limite di quota, ad esempio "Richieste al giorno" o "Indirizzi IP in uso". `quota_metric`: il nome della metrica della quota o del gruppo di quota. `time_window`: La dimensione della finestra per i limiti di operazioni simultanee.
`quota/concurrent/limit` ^ALPHA *(project, folder, organization)* Limite di quota simultanea
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	Il limite di richieste simultanee per la quota. Campionamento eseguito ogni 86.400 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 180 secondi. `limit_name`: il nome del limite di quota, ad esempio "Richieste al giorno" o "Indirizzi IP in uso". `quota_metric`: il nome della metrica della quota o del gruppo di quota. `time_window`: La dimensione della finestra per i limiti di operazioni simultanee.
`quota/concurrent/usage` ^ALPHA *(project, folder, organization)* Utilizzo della quota contemporanea
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	L'utilizzo simultaneo della quota. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 180 secondi. `limit_name`: il nome del limite di quota, ad esempio "Richieste al giorno" o "Indirizzi IP in uso". `quota_metric`: il nome della metrica della quota o del gruppo di quota. `time_window`: La dimensione della finestra per i limiti di operazioni simultanee.
`quota/exceeded` ^GA *(project, folder, organization)* Errore di quota superata
`GAUGE`, `BOOL`, `1` consumer_quota	L'errore si è verificato quando è stato superato il limite di quota. Campionamento eseguito ogni 60 secondi. `limit_name`: il nome del limite di quota, ad esempio "Richieste al giorno" o "Indirizzi IP in uso". `quota_metric`: il nome della metrica della quota o del gruppo di quota.
`quota/limit` ^GA *(project, folder, organization)* Limite di quota
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	Il limite per la quota. Campionamento eseguito ogni 86.400 secondi. `limit_name`: il nome del limite di quota, ad esempio "Richieste al giorno" o "Indirizzi IP in uso". `quota_metric`: il nome della metrica della quota o del gruppo di quota.
`quota/rate/net_usage` ^GA *(project, folder, organization)* Valuta l'utilizzo della quota
`DELTA`, `INT64`, `1` consumer_quota producer_quota	La quota di tariffa totale utilizzata. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 240 secondi. `method`: Il nome del metodo dell'API, ad esempio "disks.list". `quota_metric`: il nome della metrica della quota o del gruppo di quota.
`reserved/metric1` ^EARLY_ACCESS *(project)* Deprecato
`DELTA`, `INT64`, `1` deprecated_resource	Ritirato. Campionamento eseguito ogni 60 secondi. Dopo il campionamento, i dati non sono visibili per un massimo di 180 secondi. `quota_name`: Deprecato. `credential_id`: Deprecato. `quota_location`: Deprecato.

Tabella generata il 19-11-2024 alle ore 19:24:05 UTC.

Per visualizzare le metriche dell'API in Metrics Explorer, seleziona API utilizzata come tipo di risorsa e poi una delle metriche serviceruntime. Quindi, utilizza le opzioni di filtro e aggregazione per perfezionare i dati. Dopo aver trovato le informazioni sull'utilizzo dell'API che ti interessano, puoi utilizzare Cloud Monitoring per creare dashboard e avvisi personalizzati che ti aiuteranno a continuare a monitorare e gestire un'applicazione solida. Le istruzioni per questa operazione sono disponibili alle pagine seguenti:

Per ulteriori informazioni, consulta Esplora metriche.

Risoluzione dei problemi relativi alle metriche API

Le metriche API possono essere particolarmente utili se devi contattare Google quando qualcosa va storto e possono anche indicarti che non è necessario contattare l'assistenza. Ad esempio:

Se tutte le chiamate a un servizio falliscono per un singolo ID credenziale, ma non per altri, è probabile che ci sia un problema con quell'account che puoi facilmente risolvere autonomamente senza aprire un ticket.
Stai risolvendo un problema con la tua app e noti una correlazione tra le prestazioni limitate della tua applicazione e un prolungato aumento della latenza del 50° percentile di un servizio Google Cloud critico. Chiamaci e indicaci questi dati per consentirci di iniziare a lavorare al problema il più rapidamente possibile.
Le latenze per un servizio Google Cloud sembrano buone e invariate rispetto a prima, ma le metriche in-app segnalano che la latenza delle chiamate al servizio è eccessivamente alta. Ciò indica che si è verificato un problema nella rete. Contatta il tuo operatore di rete (in alcuni casi, Google) per avviare il processo di debugging.

Best practice

Sebbene le metriche API siano uno strumento estremamente utile, ci sono problemi che devi considerare per assicurarti che forniscano informazioni utili, in particolare quando configuri avvisi in base ai valori delle metriche. Le seguenti best practice ti aiuteranno a ottenere il massimo dai dati delle metriche dell'API.

La latenza causa un problema?

Sebbene alcuni servizi siano piuttosto sensibili alla latenza, per altri sono più importanti la scalabilità e l'affidabilità. Alcune API, ad esempio Cloud Storage o BigQuery, possono avere un paio di secondi di alta latenza senza che i clienti se ne accorgano. Con i dati delle metriche API, puoi scoprire quanto gli utenti hanno bisogno di un determinato servizio.

Cerca le variazioni rispetto alla norma

Prima di decidere di inviare un avviso per un determinato valore della metrica, valuta cosa viene effettivamente considerato un comportamento insolito. L'esame delle metriche dell'API può mostrare che i risultati relativi alla latenza per la maggior parte dei servizi rientrano in una distribuzione normale: un'ampia gobba al centro e valori anomali su entrambi i lati. Le metriche ti aiuteranno a comprendere la distribuzione normale in modo da progettare la tua app in modo che funzioni bene all'interno della curva di distribuzione. Le metriche possono anche aiutarti a correlare le variazioni di distribuzione con i momenti in cui l'app non funziona come previsto, per aiutarti a trovare la causa principale di un problema. Ci aspettiamo che il 99° percentile sia molto diverso dalla mediana, ma non prevediamo cambiamenti significativi in questi percentile nel tempo.

Inoltre, potresti notare che alcuni tipi di richieste richiedono più tempo di altri. Se le dimensioni medie di una foto caricata su Google Foto sono 4 MB, ma di solito carichi file RAW da 20 MB, il tempo medio per caricare 20 foto è probabilmente molto peggiore rispetto alla maggior parte degli utenti, ma rimane un comportamento normale per te.

Tutto ciò significa che non è particolarmente utile inviare un avviso la prima volta che viene rilevata una chiamata RPC o HTTP 5xx di un secondo. Invece, quando esamini un servizio Google come possibile causa di un problema riscontrato nella tua applicazione, confronta i codici di ritorno e i tassi di latenza nel tempo e cerca variazioni sostenute rispetto alla norma che sono correlate ai problemi osservati nella tua applicazione.

Percentuale di traffico

Le metriche API sono più utili quando hai un volume elevato di traffico verso l'API. Se chiami un servizio solo a intermittenza, le metriche dell'API non saranno statisticamente valide e non ti forniranno informazioni significative sul triage.

Ad esempio, se vuoi monitorare la latenza del 99,5° percentile per un servizio e effettui solo 100 chiamate all'ora, la misurazione su un periodo di due ore ti fornirà un solo punto dati per rappresentare il 99,5° percentile, che non ti dirà molto sul comportamento normale dell'API o della tua applicazione. Assicurati che la frequenza del traffico, la percentuale che stai monitorando e la finestra temporale che stai prendendo in considerazione generino molti punti dati di interesse, altrimenti i dati di monitoraggio non ti saranno utili.

API supportate

Tutte le API Google e Google Cloud, nonché le API basate su Cloud Endpoints e API Gateway, supportano le metriche API. Se sei un consumatore di API, puoi visualizzare le metriche relative alle API consumate nella dashboard delle API. Se sei un produttore di API, puoi visualizzare le metriche delle API prodotte nella dashboard di Endpoints.