Risolvere i problemi relativi all'API Monitoring

Questa guida spiega alcuni dei problemi che potrebbero sorgere quando utilizzi l'API Monitoring.

L'API Monitoring fa parte del set di API Cloud. Queste API condividono un insieme comune di codici di errore. Per un elenco dei codici di errore definiti dalle API Cloud e suggerimenti generali sulla gestione degli errori, consulta Gestione degli errori.

Utilizzare Explorer API per il debug

Explorer API è un widget integrato nelle pagine di riferimento per i metodi API. Consente di richiamare il metodo compilando i campi e non richiede di scrivere codice.

Se hai problemi con l'invocazione di un metodo, utilizza il widget Explorer API (Prova questa API) nella pagina di riferimento del metodo per eseguire il debug del problema. Per saperne di più, consulta Explorer API.

Errori API generali

Ecco alcuni degli errori e dei messaggi dell'API Monitoring che potresti visualizzare dalle tue chiamate API:

• 404 NOT_FOUND con il messaggio "Impossibile trovare l'URL richiesto su questo server": Una parte dell'URL non è corretta. Confronta l'URL con l'URL del metodo mostrato nella pagina di riferimento del metodo. Questo errore potrebbe significare che è presente un errore ortografico, ad esempio "project" anziché "projects", o un errore di maiuscole, ad esempio "TimeSeries" anziché "timeSeries".

• 401 UNAUTHENTICATED con "L'utente non è autorizzato ad accedere al progetto (o alla metrica)": questo codice di errore in genere indica un problema di autorizzazione, ma può significare che si è verificato un errore nel nome dell'ID progetto o del tipo di metrica. Verifica l'ortografia e l'uso delle maiuscole.

  Se non utilizzi Explorer API, prova a farlo. Quando la chiamata API funziona in Explorer API, probabilmente si verifica un problema di autorizzazione nell'ambiente in cui stai effettuando la chiamata API. Vai alla pagina di gestione delle API per verificare che l'API Monitoring sia abilitata per il tuo progetto.

• 400 INVALID_ARGUMENT con "Il filtro del campo aveva un valore non valido": verifica l'ortografia e la formattazione del filtro di monitoraggio. Per saperne di più, consulta Filtri di monitoraggio.

• 400 INVALID_ARGUMENT con "Request was missing field interval.endTime": Visualizzi questo messaggio quando l'ora di fine non è presente o quando è presente ma non è formattata correttamente. Se utilizzi l'Explorer API, non inserire tra virgolette il valore del campo ora.

  Ecco alcuni esempi di specifiche di tempo valide:

  2024-05-11T01:23:45Z
  2024-05-11T01:23:45.678Z
  2024-05-11T01:23:45.678+05:00
  2024-05-11T01:23:45.678-04:30
  

Risultati mancanti

Quando una chiamata API restituisce il codice di stato 200 e una risposta vuota, considera quanto segue:

• Quando la chiamata utilizza un filtro, è possibile che il filtro non abbia trovato alcuna corrispondenza. La corrispondenza del filtro è sensibile alle maiuscole. Per risolvere i problemi con i filtri, inizia specificando un solo componente del filtro, ad esempio metric.type, e verifica di ottenere risultati. Aggiungi gli altri componenti del filtro uno alla volta per creare la richiesta.

• Quando lavori con una metrica personalizzata, verifica che sia specificato il progetto che definisce la metrica.

Esistono diversi motivi per cui i punti dati potrebbero non essere presenti quando utilizzi il metodo timeSeries.list:

• I dati potrebbero essere scaduti. Per ulteriori informazioni, consulta Conservazione dei dati.

• I dati potrebbero non essere ancora stati propagati a Monitoring. Per maggiori informazioni, consulta la sezione Latenza dei dati delle metriche.

• L'intervallo non è valido:

  • Verifica che l'ora di fine sia corretta.
  • Verifica che l'ora di inizio sia corretta e precedente all'ora di fine. Quando l'ora di inizio è mancante o non valida, l'API imposta l'ora di inizio sull'ora di fine. Per le metriche GAUGE, questo intervallo di tempo corrisponde solo ai punti i cui orari di inizio e fine corrispondono esattamente all'orario di fine dell'intervallo. Per le metriche CUMULATIVE o DELTA, che misurano gli intervalli di tempo, non vengono abbinati punti. Per saperne di più, consulta Intervalli di tempo.

Ritentativo degli errori API

Due dei codici di errore delle API Cloud indicano circostanze in cui potrebbe essere utile riprovare a inviare la richiesta:

• 503 UNAVAILABLE: i tentativi sono utili quando il problema è una condizione di breve durata o transitoria.
• 429 RESOURCE_EXHAUSTED: i tentativi sono utili, dopo un ritardo, per i job in background a esecuzione prolungata con quota basata sul tempo, ad esempio n chiamate per t secondi. I tentativi non sono utili quando il problema è una condizione di breve durata o transitoria oppure quando hai esaurito una quota basata sul volume. Per condizioni temporanee, valuta la possibilità di tollerare l'errore. Per i problemi relativi alla quota, valuta la possibilità di ridurre l'utilizzo della quota o di richiedere un aumento della quota.

Quando scrivi codice che potrebbe riprovare le richieste, assicurati prima che la richiesta sia sicura da riprovare.

È sicuro riprovare a inviare la richiesta?

Se la richiesta è idempotente, è sicuro riprovare. Un'azione idempotente è un'azione in cui qualsiasi modifica dello stato non dipende dallo stato attuale. Ad esempio:

• La lettura di x è idempotente; il valore non viene modificato.
• L'impostazione di x su 10 è idempotente. Ciò potrebbe modificare lo stato se il valore non è già 10, ma non importa quale sia il valore attuale. Inoltre, non importa quante volte tenti di impostare il valore.
• L'incremento di x non è idempotente; il nuovo valore dipende dal valore corrente.

Esegui nuovi tentativi con backoff esponenziale

Quando implementi il codice per riprovare le richieste, non devi inviare rapidamente nuove richieste a tempo indeterminato. Se un sistema è sovraccarico, questo approccio contribuisce al problema.

Utilizza invece un approccio di backoff esponenziale troncato. Quando le richieste non vanno a buon fine a causa di sovraccarichi temporanei anziché di una vera indisponibilità, la soluzione è ridurre il carico. Un backoff esponenziale troncato segue questo pattern generale:

• Stabilisci per quanto tempo vuoi attendere durante i tentativi o quanti tentativi vuoi fare. Quando questo limite viene superato, considera il servizio non disponibile e gestisci la condizione in modo appropriato per la tua applicazione. Questo è ciò che rende il backoff troncato: a un certo punto smetti di riprovare.

• Riprova la richiesta con pause sempre più lunghe per ridurre la frequenza dei tentativi. Riprova finché la richiesta non va a buon fine o non viene raggiunto il limite stabilito.

  L'intervallo viene in genere aumentato di una funzione della potenza del conteggio dei tentativi, il che lo rende un backoff esponenziale.

Esistono molti modi per implementare un backoff esponenziale. Di seguito è riportato un esempio che aggiunge un ritardo di backoff crescente a un ritardo minimo di 1000 ms. Il ritardo di backoff iniziale è di 2 ms e aumenta a 2^retry_count ms a ogni tentativo.

La tabella seguente mostra gli intervalli di nuovi tentativi utilizzando i valori iniziali:

• Ritardo minimo = 1 s = 1000 ms
• Backoff iniziale = 2 ms

Conteggio tentativi	Ritardo aggiuntivo (ms)	Riprova dopo (ms)
0	2^0 = 1	1001
1	2^1 = 2	1002
2	2^2 = 4	1004
3	2^3 = 8	1008
4	2^4 = 16	1016
…	…	…
n	2^n	1000 + 2^n

Puoi troncare il ciclo di nuovi tentativi interrompendolo dopo n tentativi o quando il tempo trascorso supera un valore ragionevole per la tua applicazione.

Per ulteriori informazioni, consulta l'articolo di Wikipedia Algoritmo di backoff esponenziale.