Risolvi i problemi relativi all'API Monitoring

Per diagnosticare gli errori API, correggere i rifiuti di importazione delle metriche e risolvere i problemi relativi ai risultati delle query mancanti quando utilizzi l'API Monitoring, puoi utilizzare le tecniche di risoluzione dei problemi e le soluzioni agli errori descritte in questa guida.

L'API Monitoring fa parte delle API Cloud. Per un elenco dei codici di errore condivisi e consigli generali per la gestione, consulta Gestione degli errori.

Errori generali di API e autenticazione

Questa sezione elenca i codici di errore che possono essere restituiti da una serie di metodi dell'API Monitoring.

401 UNAUTHENTICATED

Il codice di errore 401 UNAUTHENTICATED indica credenziali OAuth2 o IAM mancanti, scadute o non valide.

I due messaggi di errore comuni per questo codice di errore sono Request is missing required authentication credential e User is not authorized to access the project (or metric).

  • Causa: intestazione Authorization: Bearer <token> mancante, token OAuth2 o OIDC scaduto o credenziali del account di servizio non valide.
  • Soluzione: aggiorna i token di autenticazione utilizzando le Credenziali predefinite dell'applicazione o gcloud auth print-access-token. Inoltre, verifica che la chiave del account di servizio sia valida.

403 PERMISSION_DENIED per l'accesso al progetto e la fatturazione

Il codice di errore 403 PERMISSION_DENIED indica che non disponi delle autorizzazioni necessarie per eseguire l'azione richiesta.

Esistono diversi messaggi di errore che possono essere associati a questo codice di errore. Due messaggi di errore comuni sono Billing check failed for project [PROJECT_ID] e Billing account disabled:

  • Causa: la fatturazione Cloud è disabilitata o sospesa nel progettoGoogle Cloud . L'importazione di metriche personalizzate richiede un account di fatturazione attivo.
  • Soluzione: collega un account di fatturazione Cloud attivo al progetto nella console Google Cloud .

Se ricevi questo codice di errore durante la scrittura dei dati delle metriche, consulta anche 403 PERMISSION_DENIED durante la scrittura dei dati delle metriche.

404 NOT_FOUND

Il codice di errore 404 NOT_FOUND indica che l'ID progetto di destinazione non esiste o che la regione o la località non è riconosciuta.

Di seguito sono riportati i messaggi di errore comuni per questo codice di errore:

  • Project [PROJECT_ID] not found

    • Causa: il progetto specificato nell'URI della richiesta non esiste o è stato eliminato.
    • Risoluzione: controlla l'ortografia dell'ID progetto e verifica che il progetto sia attivo nella console Google Cloud .

  • Unavailable region or location o Unrecognized region or location

    • Causa: l'etichetta della località o della regione della risorsa monitorata non è valida o non è riconosciuta.
    • Risoluzione:utilizza nomi di zona e regione Google Cloud validi, ad esempio us-central1 o us-central1-a.

  • The requested URL was not found on this server

    • Causa: il percorso della risorsa nell'URL non è corretto.
    • Risoluzione:confronta l'URL con quello 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 capitalizzazione, ad esempio "TimeSeries" anziché "timeSeries".

500 INTERNAL, 503 UNAVAILABLE, 504 DEADLINE_EXCEEDED

Esistono due messaggi di errore comuni per questi codici di errore: Internal error encountered. Please retry after a few seconds e The service is currently unavailable.

  • Causa: errori temporanei dell'infrastruttura di backend, problemi di rete o ribilanciamento della partizione del database interno.
  • Risoluzione:implementa il backoff esponenziale troncato con jitter nei nuovi tentativi, a partire da 1 secondo fino a 32 secondi. Imposta le scadenze del client RPC su 15 secondi o più. Per saperne di più, vedi Riprovare gli errori API.

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 relativi ai filtri, inizia specificando un solo componente di filtro, ad esempio metric.type, e verifica di ottenere risultati. Aggiungi gli altri componenti del filtro uno alla volta per creare la richiesta.

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, vedi 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'ora 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.

Errori durante l'esecuzione di query sui dati delle metriche

Questa sezione fornisce informazioni sugli errori che possono verificarsi durante la lettura dei dati delle metriche utilizzando un metodo come timeSeries.list.

400 INVALID_ARGUMENT durante l'esecuzione di query sui dati delle metriche

Il codice di errore 400 INVALID_ARGUMENT indica un errore di convalida lato client. Il messaggio di errore associato al codice di errore fornisce informazioni più dettagliate ed è specifico per il metodo API.

Ad esempio, quando esegui query sui dati delle metriche, potresti ricevere i seguenti messaggi:

  • Field filter had an invalid value o Field filter had an invalid value of "[FILTER]": [EXPLANATION]

    • Causa:indica un problema con il filtro di monitoraggio.
    • Soluzione:per risolvere il problema, verifica l'ortografia e la formattazione del filtro. Per saperne di più, consulta Filtri di monitoraggio.

  • Request was missing field interval.endTime o Field interval.endTime had an invalid value

    • Causa: indica che nella richiesta manca l'ora di fine o che il valore è formattato in modo errato.

    • Risoluzione:verifica il formato del campo endTime. I seguenti sono formati validi:

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

Errori durante la scrittura dei dati delle metriche

Questa sezione fornisce informazioni sugli errori che possono verificarsi quando utilizzi il metodo timeSeries.create per scrivere i dati delle metriche, tra cui:

  • Un riepilogo dei codici di errore.
  • Un elenco di messaggi di errore associati a ogni codice di errore. Queste voci includono sia una causa sia informazioni sulla risoluzione. Gli errori generali dell'API si applicano anche al metodo create.

Se non abiliti gli audit log di accesso ai dati per Monitoring, gli errori con il metodo timeSeries.create potrebbero non essere segnalati. Tuttavia, puoi fare quanto segue:

  • Utilizza Esplora log per interrogare i log attività amministratore, che il sistema crea quando tenta di creare automaticamente udescrittore della metricaca e l'azione non va a buon fine. Per visualizzare queste voci di registro, esegui la seguente query, dopo aver sostituito PROJECT_ID con l'ID del tuo Google Cloud progetto:

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateMetricDescriptor"
severity>=ERROR

  • Utilizza Esplora log per eseguire query sui log lato client.

Se abiliti gli audit log di accesso ai dati per Cloud Monitoring, il sistema scrive una voce di log per ogni accesso ai dati. In particolare, queste voci di log includono dettagli sul numero di punti per cui la scrittura non è riuscita e sulla causa dell'errore:

  • Per informazioni sull'attivazione degli audit log di accesso ai dati, consulta Configurare gli audit log di accesso ai dati.

  • Per visualizzare queste voci di log, utilizza Esplora log ed esegui la seguente query dopo aver sostituito PROJECT_ID con l'ID del tuo progettoGoogle Cloud :

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateTimeSeries"
severity>=ERROR

Riepilogo dei codici di errore di timeSeries.create

Codice HTTP Codice di stato gRPC Cause principali
400 INVALID_ARGUMENT Errore di convalida del payload: dimensione del batch, dimensioni etichetta o chiave, ordinamento timestamp, mancata corrispondenza di schema o tipo, struttura dell'istogramma di distribuzione.
400 FAILED_PRECONDITION Frequenza di campionamento superata, tipo di metrica non supportato o arrivo in ritardo al di fuori della finestra di conservazione.
401 UNAUTHENTICATED Credenziali OAuth2 o IAM mancanti, scadute o non valide.
403 PERMISSION_DENIED Ruolo IAM roles/monitoring.metricWriter mancante, fatturazione Cloud disattivata o tentativo non autorizzato di scrivere nei domini delle metriche di sistema riservati.
404 NOT_FOUND L'ID progetto di destinazione non esiste o la regione/località non è riconosciuta.
429 RESOURCE_EXHAUSTED Limite di cardinalità delle serie temporali attive superato per una risorsa monitorata, limiti descrittore della metrica del progetto raggiunti o limiti del tasso di richieste API superati.
500 INTERNAL Errore del servizio di memoria interna o dello schema.
503 UNAVAILABLE Indisponibilità temporanea del servizio di backend.
504 DEADLINE_EXCEEDED La richiesta è scaduta prima di scrivere i punti dati nei nodi di archiviazione.

400 INVALID_ARGUMENT durante la scrittura dei dati delle metriche

400 INVALID_ARGUMENT indica errori di convalida lato client nella struttura della richiesta, nei metadati delle metriche, nelle definizioni delle etichette, nell'allineamento dei timestamp o nei valori dei punti.

Violazioni della struttura delle richieste e del batch

Di seguito sono elencati i messaggi di errore relativi a violazioni della struttura e del batch:

  • Request was missing field timeSeries

    • Causa:l'array time_series nella richiesta era vuoto.
    • Risoluzione:includi almeno un oggetto TimeSeries in ogni richiesta.

  • The maximum number of TimeSeries objects per Create request is 200

    • Causa: la richiesta contiene più di 200 oggetti TimeSeries.
    • Risoluzione: esegui scritture batch su non più di 200 serie temporali per richiesta.

  • Field points had an invalid value: Only one point can be written per TimeSeries per request

    • Causa: un singolo oggetto TimeSeries contiene più di una voce nel campo points.
    • Risoluzione:fornisci esattamente un Point per oggetto TimeSeries per richiesta. Per scrivere più punti dati nel tempo per la stessa metrica, inviali in richieste separate.

  • Duplicate TimeSeries encountered. Only one point can be written per TimeSeries per request

    • Causa: due o più oggetti TimeSeries nella stessa richiesta condividono tipi di metriche, etichette delle metriche ed etichette risorsa monitorata identici.
    • Soluzione: deduplica le serie temporali nei batch lato client in modo che ogni serie temporale univoca venga visualizzata al massimo una volta per richiesta.

  • user defined metrics are not supported on the metric domain "[DOMAIN]"

    • Causa: le metriche definite dall'utente non sono supportate nel dominio specificato.
    • Risoluzione: nessuna.

Etichette e vincoli di denominazione

Di seguito sono elencati i messaggi di errore relativi alle etichette e ai vincoli di denominazione:

  • Field metric.labels had an invalid value of "[KEY]": Label value exceeds the maximum string size of 1024 characters

    • Causa: il valore di un'etichetta di metrica o risorsa supera i 1024 caratteri.
    • Risoluzione: configura l'agente di raccolta o l'applicazione in modo da troncare i valori delle etichette a un massimo di 1024 caratteri. Evita di archiviare testo di grandi dimensioni nelle etichette delle metriche. Scrivi questi dettagli in Cloud Logging.

  • Field metric.labels had an invalid value of "[KEY]": Label key contains invalid characters

    • Causa: una chiave di etichetta contiene caratteri al di fuori del pattern consentito. Le chiavi possono contenere caratteri alfanumerici e trattini bassi, devono avere una lunghezza massima di 100 caratteri e devono iniziare con una lettera.
    • Soluzione:rinomina le chiavi di etichetta in modo che utilizzino solo caratteri validi.

  • The metric type must be a URL-formatted string with a domain and non-empty path

    • Causa: metric.type è formattato in modo errato o manca un prefisso di dominio.
    • Risoluzione:formatta i tipi di metrica personalizzata come custom.googleapis.com/<category>/<name> o workload.googleapis.com/<name>.

  • Field metric.labels had an invalid value: The metric [METRIC_NAME] has more than [LIMIT] labels

    • Causa: il numero di etichette in un descrittore della metrica personalizzata supera 30 o, per le metriche Prometheus, supera 200.
    • Soluzione:rimuovi le etichette non necessarie per rimanere entro il limite del descrittore.

  • unrecognized metric label "[LABEL_KEY]"

    • Causa: il descrittore della metrica esiste già, ma la richiesta fornisce una chiave di etichetta non definita nel descrittore.
    • Risoluzione: assicurati che le chiavi delle etichette corrispondano a MetricDescriptor esistenti o crea un nuovo descrittore della metrica se è necessaria la modifica dello schema.

Mancata corrispondenza tra identificatori di progetto e risorsa

Di seguito sono elencati i messaggi di errore relativi alle mancate corrispondenze tra identificatori di progetti e risorse:

  • Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the project number or ID in the request name ([PROJECT]) o Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the resource container ID in the request name [PROJECT]

    • Causa: l'etichetta project_id o resource_container specificata in resource.labels non corrisponde all'ID progetto o al numero nel nome della richiesta.
    • Risoluzione: imposta l'etichetta project_id della risorsa in modo che corrisponda al progetto di richiesta oppure ometti l'etichetta project_id da resource.labels in modo che venga impostata come predefinita sul progetto di richiesta.

  • unrecognized resource type "[RESOURCE_TYPE]" o missing resource type

    • Causa:resource.type non è riconosciuto da Cloud Monitoring o viene omesso per una metrica non personalizzata.
    • Risoluzione:utilizza un tipo di risorsa monitorata valido, ad esempio gce_instance, k8s_container, generic_task o global.

Timestamp e intervalli

Di seguito sono elencati i messaggi di errore relativi a timestamp e intervalli:

  • Points must be written in order. One or more of the points specified had an older end time than the most recent point

    • Causa: il valore end_time del punto dati è precedente o uguale al timestamp del punto dati più recente inserito in precedenza per quella serie temporale.
    • Soluzione:inserisci i punti rigorosamente in ordine cronologico.

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be equal to the end time ([END]) for the gauge metric '[METRIC]'

    • Causa: è stato inviato un punto della metrica GAUGE in cui start_time non è uguale a end_time.
    • Risoluzione:per le metriche GAUGE, imposta start_time uguale a end_time o ometti start_time.

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be before the end time ([END]) for the non-gauge metric '[METRIC]'

    • Causa: un punto della metrica CUMULATIVE o DELTA ha un valore start_time maggiore o uguale al valore end_time.
    • Risoluzione:assicurati che il valore start_time sia inferiore al valore end_time e rappresenti un intervallo di tempo diverso da zero.

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than 5m into the future.

    • Causa: il timestamp del punto è più di 5 minuti avanti rispetto all'ora attuale del server.
    • Risoluzione:sincronizza l'orologio di sistema con Google Public NTP (time.google.com).

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than approximately 24 hours in the past

    • Causa: il timestamp del punto è precedente all'orizzonte di conservazione in memoria, ovvero 24 ore.
    • Soluzione:scrivi i dati in tempo reale entro 24 ore dalla generazione.

Tipi di valori e distribuzioni

I seguenti elenchi mostrano i messaggi di errore relativi ai tipi e alle distribuzioni di valori:

  • value type for metric must be [EXPECTED], but is [ACTUAL] o metric kind for metric must be [EXPECTED], but is [ACTUAL]

    • Causa: il tipo di valore in entrata (INT64, DOUBLE, STRING, BOOL, DISTRIBUTION) o il tipo di metrica (GAUGE, DELTA, CUMULATIVE) è in conflitto con il MetricDescriptor esistente.
    • Soluzione: assicurati che i tipi di dati corrispondano al descrittore esistente. I tipi di valori e i tipi di metrica non possono essere modificati dopo la creazione.

  • Field points[0].value had an invalid value: The metric value exceeds the maximum string size of 1024 characters

    • Causa: un punto della metrica di tipo valore STRING supera i 1024 caratteri.
    • Risoluzione:tronca i valori delle metriche stringa a un massimo di 1024 caratteri oppure invia i log a Cloud Logging.

  • Field points[0].value had an invalid value: Bucket options must be specified for Distribution metric

    • Causa: un punto DISTRIBUTION non specifica bucket_options.
    • Risoluzione:definisci linear_buckets, exponential_buckets o explicit_buckets per le metriche di distribuzione.

  • Field points[0].value.distributionValue had an invalid value: Distribution value has |bucket_counts| fields that sum to X which does not equal the |count| field value of Y

    • Causa: la somma dei conteggi in bucket_counts non corrisponde al campo count.
    • Risoluzione: assicurati che la somma di tutti i conteggi dei bucket sia uguale al campione count.

  • Field points[0].value had an invalid value: Distribution metric has too many buckets

    • Causa: il numero di bucket dell'istogramma supera 200.
    • Risoluzione:modifica i parametri dei bucket per mantenere il conteggio totale dei bucket pari a 200 o meno.

400 FAILED_PRECONDITION

Di seguito sono elencati i messaggi di errore correlati a questo codice di errore:

  • One or more points were written more frequently than the maximum sampling period configured for the metric

    • Causa: i punti per la stessa serie temporale sono stati inviati più velocemente della velocità massima consentita di un punto ogni 5 secondi.
    • Risoluzione:limita la velocità di importazione in modo che i punti consecutivi per una serie temporale specifica siano distanziati di almeno 5 secondi.

  • ingestion of prometheus delta metrics is not supported in this API

    • Causa: la richiesta ha tentato di scrivere metriche Prometheus DELTA tramite timeSeries.create.
    • Risoluzione:utilizza le metriche di Prometheus GAUGE o CUMULATIVE oppure importale tramite gli endpoint OTLP di Google Cloud Managed Service per Prometheus.

  • One or more points arrived late outside of its aggregation window

    • Causa: i punti sono arrivati dopo la finestra di aggregazione per le metriche aggregate a livello di raccolta.
    • Risoluzione:scarica e riproduci in streaming i punti con latenze del buffer inferiori.

403 PERMISSION_DENIED durante la scrittura dei dati delle metriche

Quando scrivi i dati delle metriche, puoi ricevere una risposta 403 PERMISSION_DENIED per motivi correlati all'accesso al progetto e alla fatturazione e per i seguenti motivi:

  • Permission monitoring.timeSeries.create denied on resource (or it may not exist)

    • Causa: Il chiamante non dispone dell'autorizzazione monitoring.timeSeries.create sul progetto di destinazione.
    • Soluzione:concedi il ruolo Monitoring Metric Writer (roles/monitoring.metricWriter) al account di servizio o al principal.

  • Billing check failed for project [PROJECT_ID] o Billing account disabled

    • Causa: la fatturazione Cloud è disabilitata o sospesa nel progettoGoogle Cloud . L'importazione di metriche personalizzate richiede un account di fatturazione attivo.
    • Soluzione: collega un account di fatturazione Cloud attivo al progetto nella console Google Cloud .

  • User does not have permission to write to metric [METRIC]

    • Causa: il chiamante ha tentato di scrivere metriche personalizzate direttamente nei domini riservati al sistema, ad esempio compute.googleapis.com o storage.googleapis.com.
    • Risoluzione: utilizza domini di metrica personalizzata come custom.googleapis.com/ o workload.googleapis.com/.

429 RESOURCE_EXHAUSTED

Di seguito sono elencati i messaggi di errore correlati a questo codice di errore:

  • Monitored resource ([RESOURCE_ID]) has too many time series (custom metrics)

    • Causa: Limite di serie temporali attive superato (cardinalità elevata). Il numero di serie temporali attive per una singola risorsa monitorata ha superato il limite di 200.000 serie attive in un periodo di 24 ore. Per le metriche Prometheus, il limite è di 1.000.000 di serie attive. Ciò si verifica in genere quando gli ID effimeri, come ID contenitore, UUID pod, ID richiesta, ID utente o timestamp, sono inclusi nelle etichette delle metriche sulle risorse in churn.
    • Risoluzione:
      • Rimuovi le etichette effimere o con cardinalità elevata dalle metriche.
      • Se devi monitorare le metriche per singoli task effimeri, utilizza il tipo di risorsa monitorata generic_task anziché i tipi specifici della risorsa, come dataflow_job. Mappa l'identificatore effimero all'etichetta task_id della risorsa generic_task.

  • Your Metric Ingestion quota has been exhausted

    • Causa: il progetto ha superato la quota di frequenza di importazione dell'API.
    • Risoluzione: scrivi serie temporali batch fino a 200 serie per richiesta oppure richiedi un aumento della quota nella pagina Quote della console Google Cloud .

  • Your Metric Descriptors quota has been exhausted

    • Causa: il progetto ha raggiunto il limite massimo di 10.000 descrittori delle metriche personalizzate per progetto. Per le metriche Prometheus, questo limite è di 25.000 per progetto.
    • Soluzione:elimina i descrittori delle metriche non utilizzati utilizzando projects.metricDescriptors.delete o riduci la denominazione dinamica delle metriche.

  • Rate of metric descriptor creation exceeded

    • Causa: il progetto ha tentato di creare nuovi descrittori delle metriche più velocemente di 6000 al minuto per progetto.
    • Risoluzione:evita di creare dinamicamente nuovi tipi di metriche durante l'importazione dei dati; crea in anticipo i descrittori, se possibile.

Ritentare gli 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 lunga esecuzione 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 innanzitutto che la richiesta sia sicura da riprovare.

È sicuro riprovare a inviare la richiesta?

Se la tua richiesta è idempotente, puoi riprovare a inviarla in tutta sicurezza. 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.

Effettua nuovi tentativi con backoff esponenziale

Quando implementi il codice per riprovare le richieste, non devi inviare indefinitamente nuove richieste rapidamente. 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 e propria 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 questa 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 in base a 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 2retry_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 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 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.