Monitoraggio dell'utilizzo delle API

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

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

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

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

Le metriche prodotte dalle API di Google sono gli indicatori standard che i proprietari di siti Google Site Reliability Engineer utilizzano per valutare l'integrità di un servizio. Queste metriche riguardano conteggio delle richieste, percentuali di errore, latenze totali, latenze di backend, dimensioni delle richieste e dimensioni della risposta. Per le definizioni delle metriche API, consulta la documentazione di Cloud Monitoring.

Puoi visualizzare le metriche dell'API in due punti: dashboard delle API e Cloud Monitoring. Le metriche che vedi sono specifiche per il tuo progetto e non riflettono lo stato generale del servizio.

Utilizzo della dashboard delle API

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

Per visualizzare una panoramica sull'utilizzo dell'API:

  1. Visita la sezione API e servizi di Cloud Console. La dashboard principale dell'API è visualizzata per impostazione predefinita. In questa pagina puoi visualizzare tutte le API attualmente abilitate per il progetto, oltre a grafici di panoramica per le seguenti metriche:

    • Traffico: numero di richieste al secondo effettuate dal tuo progetto o relative al tuo progetto per le API abilitate
    • Errori: la percentuale di richieste alle API abilitate che hanno generato errori
    • Latenza mediana: la latenza mediana delle richieste alle API abilitate, se disponibile.

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

  1. Seleziona l'API che vuoi visualizzare nell'elenco principale delle API. La pagina Panoramica dell'API mostra un grafico del traffico più dettagliato con un'analisi per codice di risposta.
  2. Per informazioni ancora più dettagliate sull'utilizzo, seleziona Visualizza metriche. Per impostazione predefinita vengono visualizzati i seguenti grafici predefiniti, anche se sono disponibili altri grafici:

    • Traffico per codice di risposta
    • Errori per metodo API
    • Latenza complessiva al 50°, 95° e 99° percentile
    • Latenza per metodo API (mediana)
  3. 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 esaminare più a fondo i dati disponibili per le metriche mediante Metrics Explorer per ottenere informazioni più approfondite sul tuo utilizzo dell'API. Cloud Monitoring supporta una vasta gamma di metriche, che puoi combinare con filtri e aggregazioni per viste nuove e approfondite sulle tue prestazioni delle applicazioni. Ad esempio, puoi combinare una metrica del conteggio delle richieste con un filtro nella classe Codice di risposta HTTP per creare una dashboard che mostra i tassi di errore nel tempo oppure visualizzare la latenza del 95° percentile delle richieste all'API Cloud Pub/Sub.

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

Per ulteriori informazioni, consulta Metrics Explorer.

Risoluzione dei problemi con le metriche API

Le metriche dell'API possono essere particolarmente utili se hai bisogno di contattare Google in caso di problemi e potrebbero persino indicare che non hai bisogno di contattare l'assistenza. Ad esempio:

  • Se tutte le chiamate a un servizio non vanno a buon fine per un solo ID credenziale, ma non un'altra, è probabile che ci sia qualcosa di sbagliato in quell'account che puoi correggere facilmente senza aprire un ticket.
  • Stai risolvendo un problema con la tua app e noti una correlazione tra le prestazioni ridotte dell'applicazione e un aumento sostenuto della latenza del 50° percentile di un servizio GCP critico. Certamente a chiamarci e indicarci questi dati in modo da poter iniziare a lavorare sul problema nel più breve tempo possibile.
  • Le latenze di un report di servizio di GCP sono buone e invariate rispetto a prima, ma le metriche in-app indicano che la latenza delle chiamate al servizio è anormalmente elevata. Questo indica che si è verificato un problema in rete. Chiama il tuo provider di rete (in alcuni casi, Google) per avviare il processo di debug.

Best practice

Sebbene le metriche dell'API siano uno strumento estremamente utile, è necessario prendere in considerazione alcuni problemi per assicurarsi che forniscano informazioni utili, soprattutto quando si configurano gli avvisi in base ai valori delle metriche. Le seguenti best practice ti aiuteranno a sfruttare al meglio i dati delle metriche delle API.

La latenza è un problema?

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

Cerca le modifiche dalla norma

Prima di decidere di attivare un avviso per un determinato valore della metrica, valuta ciò che viene effettivamente considerato come comportamento insolito. Analizzando le metriche dell'API puoi dimostrare che i risultati di latenza per la maggior parte dei servizi rientrano in una normale distribuzione: una grande gobba al centro e valori anomali su entrambi i lati. Le metriche ti aiuteranno a comprendere la normale distribuzione in modo da poter progettare la tua app in modo che funzioni bene all'interno della curva di distribuzione. Le metriche possono anche aiutarti a correlare le modifiche alla distribuzione con i tempi in cui la tua app non funziona come previsto, per aiutarti a individuare la causa principale di un problema. Ci aspettiamo che il 99° percentile appaia molto diverso dalla mediana; ciò che non prevediamo è cambiamenti significativi in quei percentili nel corso del tempo.

Inoltre, potresti notare che alcuni tipi di richieste richiedono più tempo di altri. Se la dimensione media di una foto caricata in Google Foto è di 4 MB, ma in genere carichi file RAW da 20 MB, è probabile che il tempo medio di caricamento di 20 foto sia notevolmente inferiore a quello della maggior parte degli utenti, ma è comunque comportamento normale.

Ciò significa che non è particolarmente utile avvisare la prima volta che viene rilevata una chiamata RPC o 5xx HTTP di lunga durata. Quando esamini un servizio Google come possibile causa di un problema della tua applicazione, confronta i codici di reso e i tassi di latenza nel tempo, quindi controlla se sono normali modifiche correlate ai problemi osservati nella tua applicazione.

Percentuale di traffico

Le metriche API sono più utili se il tuo volume di traffico verso l'API è elevato. Se chiami un servizio solo a intermittenza, le tue metriche dell'API non saranno statisticamente valide e non forniranno informazioni significative sulla valutazione.

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

API supportate

Tutte le API di Google, di Google Cloud e le API basate su endpoint Cloud e gateway dell'API supportano le metriche dell'API. Se sei un consumer dell'API, puoi visualizzare le metriche API utilizzate nella dashboard delle API. Se sei un produttore di API, puoi visualizzare le metriche dell'API prodotto nella dashboard degli endpoint.