Risolvere i problemi relativi all'API Monitoring

Questa guida illustra alcuni dei problemi che potrebbero verificarsi durante l'utilizzo dell'API Monitoring.

L'API Monitoring è una delle 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

API Explorer è un widget integrato nelle pagine di riferimento per i metodi API. Ti consente di invocare 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 ulteriori informazioni, consulta Explorer API.

Errori generali dell'API

Di seguito sono riportati alcuni degli errori e dei messaggi dell'API Monitoring che potresti visualizzare dalle chiamate API:

  • 404 NOT_FOUND con "Impossibile trovare l'URL richiesto su questo server": Qualche parte dell'URL non è corretta. Confronta l'URL con l'URL del metodo mostrato nella pagina di riferimento del metodo. Questo errore potrebbe indicare un errore ortografico, come "project" anziché "projects", o un errore di utilizzo delle lettere maiuscole, come "TimeSeries" anziché "timeSeries".

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

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

  • 400 INVALID_ARGUMENT con "Il filtro dei campi aveva un valore non valido": verifica l'ortografia e la formattazione del filtro di monitoraggio. Per ulteriori informazioni, consulta Filtri di monitoraggio.

  • 400 INVALID_ARGUMENT con "Nella richiesta mancava il campo interval.endTime": viene visualizzato questo messaggio quando l'ora di fine non è presente o quando è presente, ma non è formattata correttamente. Se utilizzi l'Explorer API, non devi indicare il valore del campo time.

    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, tieni conto di quanto segue:

  • Quando la chiamata utilizza un filtro, il filtro potrebbe non avere trovato alcuna corrispondenza. La corrispondenza del filtro è sensibile alle maiuscole. Per risolvere i problemi relativi ai 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 utilizzi una metrica personalizzata, verifica che sia specificato il progetto che la definisce.

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

  • I dati potrebbero essere obsoleti. Per ulteriori informazioni, vedi Conservazione dei dati.

  • I dati potrebbero non essere ancora stati propagati a Monitoraggio. Per ulteriori informazioni, consulta 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 che sia precedente all'ora di fine. Se l'ora di inizio non è presente o non è corretta, l'API imposta l'ora di inizio sull'ora di fine. Per le metriche GAUGE, questo intervallo di tempo corrisponde solo ai punti le cui ore di inizio e di fine corrispondono esattamente all'ora di fine dell'intervallo. Per le metriche CUMULATIVE o DELTA, che vengono misurate su intervalli di tempo, non viene effettuata alcuna corrispondenza dei punti. Per ulteriori informazioni, consulta Intervalli di tempo.

Errori di ripetizione dell'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 di nuovo sono utili quando il problema è di breve durata o temporaneo.
  • 429 RESOURCE_EXHAUSTED: i tentativi di nuovo sono utili, dopo un ritardo, per i lavori in background di lunga durata con una quota basata sul tempo, ad esempio n chiamate ogni t secondi. I tentativi di nuovo invio non sono utili quando il problema è una condizione transitoria o di breve durata o quando hai esaurito una quota basata sul volume. Per condizioni transitorie, valuta la possibilità di tollerare l'errore. Per problemi correlati alla quota, valuta la possibilità di ridurre l'utilizzo della quota o di richiederne un aumento.

Quando scrivi codice che potrebbe riprovare le richieste, assicurati innanzitutto che sia sicuro riprovare la richiesta.

È sicuro riprovare a inviare la richiesta?

Se la richiesta è idempotente, puoi riprovare in tutta sicurezza. Un'azione idempotente è un'azione in cui qualsiasi variazione di stato non dipende dallo stato corrente. Ad esempio:

  • La lettura di x è idempotente; il valore non cambia.
  • L'impostazione di x su 10 è idempotente; questo potrebbe modificare lo stato, se il valore non è già 10, ma non importa quale sia il valore corrente. Inoltre, non importa quante volte provi a impostare il valore.
  • L'incremento di x non è idempotente; il nuovo valore dipende dal valore corrente.

Riprova con backoff esponenziale

Quando implementi il codice per ripetere le richieste, non vuoi emettere rapidamente nuove richieste a tempo indeterminato. Se un sistema è sovraccaricato, 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é per una mancata disponibilità, la soluzione è ridurre il carico. Un backoff esponenziale troncato segue questo schema generale:

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

  • Riprova a inviare la richiesta con pause sempre più lunghe per ritirare 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 conto dei tentativi, rendendolo 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 2retry_count ms con ogni tentativo.

La tabella seguente mostra gli intervalli tra i diversi tentativi utilizzando i valori iniziali:

  • Ritardo minimo = 1 s = 1000 ms
  • Backoff iniziale = 2 ms
Numero di tentativi Ritardo aggiuntivo (ms) Riprova dopo (ms)
0 20 = 1 1001
1 21 = 2 1002
2 22 = 4 1004
3 23 = 8 1008
4 24 = 16 1016
… … …
n 2n 1000 + 2n

Puoi troncare il ciclo di ripetizione 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 Backoff esponenziale.