Questa pagina è stata tradotta dall'API Cloud Translation.

Percentili e metriche con valori di distribuzione

Questo documento descrive come comprendere i percentile e il modello di istogramma per i dati delle metriche con un tipo di valore Distribution. Una metrica di distribuzione definisce intervalli di valori, chiamati bucket, e registra il conteggio dei valori misurati che rientrano in ogni bucket. Le metriche di distribuzione non riportano i valori delle singole misure, ma un istogramma dei conteggi nei bucket. Questo tipo di valore viene utilizzato dai servizi quando le singole misurazioni sono troppo numerose per essere raccolte, ma le informazioni statistiche, come medie o percentile, su queste misurazioni sono importanti.

Quando rappresenti una metrica con valore di distribuzione in una mappa termica, puoi utilizzare un'opzione nella barra degli strumenti del grafico per sovrapporre i 50°, 95° e 99° percentile. Per visualizzare una metrica con valore di distribuzione in un grafico a linee, devi configurare il grafico in modo che converta il valore della distribuzione in un valore numerico. Puoi eseguire questa conversione utilizzando un allineatore che seleziona una percentile.

La sezione successiva di questa pagina utilizza un esempio sintetico per mostrare come vengono determinate le Percentili. L'esempio mostra che i valori percentile dipendono dal numero di bucket, dalla larghezza dei bucket, dalla distribuzione delle misurazioni e dal conteggio totale dei campioni. I valori percentile non dipendono dai valori misurati effettivi perché questi valori non sono disponibili nell'istogramma.

Esempio con dati sintetici

Prendiamo in considerazione un modello di bucket Exponential con una scala di 1, un fattore di crescita di 2 e 10 bucket finiti. Questo istogramma contiene 12 bucket, i 10 bucket finiti, 1 bucket che specifica solo un limite superiore e 1 che specifica solo un limite inferiore. Per questo esempio, il bucket finale con indice n+1 è due volte più largo del bucket finale con indice n.

Gli esempi seguenti mostrano che la larghezza del bucket determina l'errore massimo tra il percentile calcolato e le misurazioni. Inoltre, mostrano che il numero di campioni in un istogramma è importante. Ad esempio, se il numero di campioni è inferiore a 20, i percentile 95 e 99 si trovano sempre nello stesso bucket.

Caso 1: il numero totale di campioni è 1.

Quando è presente una singola misurazione, i tre valori percentile sono diversi, ma vengono mostrati solo il 50°, il 95° e il 99° percentile dello stesso bucket. L'errore tra la stima e le misurazioni effettive non può essere determinato perché la misurazione non è nota.

Ad esempio, supponiamo che l'istogramma delle misurazioni sia come mostrato nella tabella seguente:

Numero del bucket	Limite inferiore	Limite superiore	Conteggio	Intervallo percentile
0		1	0	0
1	1	2	0	0
2	2	4	0	0
3	4	8	0	0
4	8	16	0	0
5	16	32	0	0
6	32	64	0	0
7	64	128	0	0
8	128	256	1	0 - 100
9	256	512	0	0
10	512	1024	0	0
11	1024		0	0

Per calcolare il 50° percentile:

Utilizza i conteggi dei bucket per determinare il bucket che contiene il 50° percentile. In questo esempio, il bucket numero 8 contiene il 50° percentile.
Calcola la stima utilizzando la seguente regola:
```
pth percentage = bucket_low +
                (bucket_up - bucket_low)*(p - p_low)/(p_up - p_low)
```
Nell'espressione precedente, p_low e p_up sono i limiti inferiore e superiore dell'intervallo percentile per il bucket. Analogamente, bucket_low e bucket_up sono i limiti inferiore e superiore del bucket. I valori di p_low e p_up dipendono da come i conteggi sono distribuiti tra i diversi bucket.

Ad esempio, il 50° percentile viene calcolato come segue:

   50th percentile = 128 + (256-128)*(50-0)/(100-0)
                   = 128 + 128 * 50 / 100
                   = 128 + 64
                   = 192

Per calcolare il 95° percentile, sostituisci 50 con 95 nell'espressione precedente. Per questo esempio in cui è presente esattamente un campione, le percentile sono le seguenti:

Percentile	Numero del bucket	Valore
50°	8	192
95°	8	249,6
99°	8	254,7

L'errore tra la stima e le misurazioni effettive può essere limitato, ma non può essere determinato perché la misurazione non è nota.

Caso 2: il numero totale di campioni è 10.

Quando sono presenti 10 campioni, il 50° percentile potrebbe trovarsi in un bucket diverso rispetto ai percentile 95 e 99. Tuttavia, non sono disponibili misurazioni sufficienti per consentire che i percentili 95 e 99 si trovino in bucket diversi.

Ad esempio, supponiamo che l'istogramma delle misurazioni sia come mostrato nella tabella seguente:

Numero del bucket	Limite inferiore	Limite superiore	Conteggio	Intervallo percentile
0		1	4	0 - 40
1	1	2	2	40 - 60
2	2	4	1	60 - 70
3	4	8	1	70 - 80
4	8	16	1	80 - 90
5	16	32	0	0
6	32	64	0	0
7	64	128	0	0
8	128	256	1	90 - 100
9	256	512	0	0
10	512	1024	0	0
11	1024		0	0

Puoi utilizzare la procedura descritta in precedenza per calcolare i 50°, 95° e 99° percentile. Ad esempio, il 50° percentile, che si trova nel bucket numero 1, viene calcolato come segue:

50th percentile = 1 + (2-1)*(50-40)/(60-40)
                = 1 + (1 * 10 / 20)
                = 1 + 0.5
                = 1.5

Analogamente, il 95° percentile viene calcolato come segue:

95th percentile = 128 + (256-128)*(95-90)/(100-90)
                = 128 + 128 * 5 / 10
                = 128 + 64
                = 192

Utilizzando la procedura descritta in precedenza, è possibile calcolare i percentile. Ogni riga della tabella seguente elenca un percentile, il bucket corrispondente e il valore calcolato:

Percentile	Numero del bucket	Valore	Errore massimo
50°	1	1,5	0,5
95°	8	192	74
99°	8	243,2	115,2

In questo esempio e nell'esempio precedente, il percentile 95 si trova nel bucket numero 8. Tuttavia, il calcolo del percentile è diverso. La differenza è dovuta al modo in cui vengono distribuiti i campioni. Nel primo esempio, tutti gli esempi si trovano nello stesso bucket, mentre nell'esempio più recente, gli esempi si trovano in bucket diversi.

Esempio con dati reali

Questa sezione contiene un esempio che illustra come determinare il modello di bucket utilizzato da una determinata metrica. Questa sezione illustra anche come valutare il potenziale errore nei valori percentile calcolati.

Identifica il modello del bucket

Per determinare i bucket utilizzati per una metrica in un intervallo di tempo specifico, chiama il metodo projects.timeSeries/list dell'API Cloud Monitoring.

Ad esempio, per identificare il modello del bucket per una metrica:

Vai alla pagina web projects.timeSeries/list.
In APIs Explorer, inserisci il filtro che specifica la metrica, un'ora di inizio e un'ora di fine.

Ad esempio, per ottenere informazioni sulla metrica che memorizza le latenze delle richieste API, inserisci quanto segue:
```
metric.type="serviceruntime.googleapis.com/api/request_latencies"
resource.type="consumed_api"
```
In questo esempio, il campo del filtro specifica un tipo di metrica e un tipo di risorsa. Per ulteriori informazioni su questi filtri, consulta Filtri di monitoraggio.
Fai clic su Invio.

Di seguito è riportata la risposta dell'API list per una metrica con valore di distribuzione disponibile in un progetto Google Cloud:

{
  "timeSeries": [
    {
      "metric": {...},
      "resource": {...},
      },
      "metricKind": "DELTA",
      "valueType": "DISTRIBUTION",
      "points": [
        {
          "interval": {
            "startTime": "2020-11-03T15:05:00Z",
            "endTime": "2020-11-03T15:06:00Z"
          },
          "value": {
            "distributionValue": {
              "count": "3",
              "mean": 25.889,
              "bucketOptions": {
                "exponentialBuckets": {
                  "numFiniteBuckets": 66,
                  "growthFactor": 1.4,
                  "scale": 1
                }
              },
              "bucketCounts": [
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "3"
              ]
            }
          }
        },

Nella risposta dell'API, il campo value descrive i dati archiviati nell'array points. I campi count e mean indicano che per l'intervallo di tempo specificato sono state effettuate 3 misurazioni e il loro valore medio è 25,889. Il campo bucketOptions mostra che il modello esponenziale è configurato per avere 66 bucket, una scala di 1 e un fattore di crescita di 1, 4.

Per calcolare i limiti inferiori e superiori per il bucket con indice n, utilizza le seguenti regole:

Limite inferiore (1 ≤ n < N) = scala * (fattore di crescita)^(n-1)
Limite superiore (0 ≤ n < N-1) = scala * (fattore di crescita)ⁿ

Nelle espressioni precedenti, N è il numero totale di bucket.

I bucket per questa metrica, insieme al punto intermedio di ciascun bucket, sono riportati nella tabella seguente:

Bucket n	Limite inferiore	Limite superiore	Punto intermedio
0		1	Non applicabile
1	1	1,40	1,20
2	1,40	1,96	1,68
…
9	14,76	20,66	17,71
10	20,66	28,93	24,79
11	28,93	40,50	34,71
…

Verifica i calcoli dei percentile

Ora che la configurazione del bucket è nota, per qualsiasi insieme di misurazioni puoi prevedere i valori del 50°, 95° e 99° percentile. Ad esempio, se c'è un campione e si trova nel bucket 10, il valore del 50° percentile è 24,79.

Per recuperare i valori del 50°, 95° e 99° percentile della metrica, puoi utilizzare il metodo dell'API projects.timeSeries/list e includere un periodo di allineamento e un allineatore. In questo esempio, sono state selezionate le seguenti impostazioni:

Aligner: ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95 o ALIGN_PERCENTILE_99
Periodo di allineamento: 60 s

Per la selezione ALIGN_PERCENTILE_50, ogni valore della serie temporale è il 50° percentile di un bucket:

{
  "timeSeries": [
    {
      "metric": {...},
      "resource": {...},
      "metricKind": "GAUGE",
      "valueType": "DOUBLE",
      "points": [
        {
          "interval": {
            "startTime": "2020-11-03T15:06:36Z",
            "endTime": "2020-11-03T15:06:36Z"
          },
          "value": {
            "doubleValue": 24.793256140799986
          }
        },
        {
          "interval": {
            "startTime": "2020-11-03T15:05:36Z",
            "endTime": "2020-11-03T15:05:36Z"
          },
          "value": {
            "doubleValue": 34.710558597119977
          }
        },
        {
          "interval": {
            "startTime": "2020-11-03T15:04:36Z",
            "endTime": "2020-11-03T15:04:36Z"
          },
          "value": {
            "doubleValue": 24.793256140799986
          }
        }
      ]
    },

Per due dei campioni, il 50° percentile si trova nel bucket 10, mentre per l'altro campione si trova nel bucket 11.

La tabella seguente mostra i risultati dell'esecuzione del metodo projects.timeSeries/list con diversi allineatori. La prima riga corrisponde al caso in cui l'allineatore non sia specificato. Se non specifichi un allineatore, vengono restituiti il modello del bucket e i valori medi. Le tre righe successive elencano i dati restituiti quando l'allineatore è impostato su ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95 e ALIGN_PERCENTILE_99:

Statistica	Sample @ 15:06	Sample @ 15:05	Sample @ 15:04
medio	25,889	33,7435	Non disponibile.
50° percentile	24,79	34,71	24,79
95° percentile	28,51	39,91	28,51
99° percentile	28,84	40,37	28,84

Come mostrano i due esempi con dati sintetici, i valori delle terne dipendono dalla distribuzione dei campioni. Quando tutti i campioni si trovano nel bucket di esempio, il 50° percentile è il punto medio del bucket. Tuttavia, quando i campioni si trovano in bucket diversi, questa distribuzione influisce sulle stime.

Per determinare se il 50° percentile è una stima ragionevole della media, puoi confrontare il valore medio con il 50° percentile. Il valore medio viene restituito con i dettagli del bucket.

Passaggi successivi

Per informazioni su come visualizzare le metriche con valori di distribuzione, consulta Informazioni sulle metriche con valori di distribuzione.