O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Percentis e métricas com valor de distribuição

As métricas com um tipo de valor Distribution no Cloud Monitoring agrupam medições de alto volume em intervalos de valores chamados buckets, em vez de registrar cada ponto de dados individual. Registrar as contagens de buckets como um histograma permite que os serviços resumam grandes conjuntos de medições para que você possa analisar estatísticas como médias e percentis.

Em um gráfico de mapa de calor, é possível sobrepor os percentis 50, 95 e 99 na barra de ferramentas do gráfico. Para exibir uma métrica com valor de distribuição em um gráfico de linhas, use um alinhador que selecione um percentil para converter cada distribuição em um valor numérico.

Os exemplos neste documento mostram como a contagem de buckets, a largura do bucket, a distribuição de medições e o tamanho da amostra determinam os valores de percentil estimados sem armazenar medições individuais.

Exemplo com dados sintéticos

Considere um modelo de bucket Exponential com uma escala de 1, um fator de crescimento de 2 e 10 buckets finitos. Esse histograma contém 12 buckets: os 10 buckets finitos, 1 bucket que especifica apenas um limite superior e 1 que especifica apenas um limite inferior. Neste exemplo, o bucket finito com índice n+1 é duas vezes mais amplo que o bucket finito com índice n.

Os exemplos a seguir mostram que a largura do bucket determina o erro máximo entre o percentil calculado e as medições. Eles também mostram que o número de amostras em um histograma é importante. Por exemplo, se o número de amostras for menor que 20, os 95º e 99º percentis estarão sempre no mesmo bucket.

Caso 1: o número total de amostras é 1

Quando há uma única medição, os três valores de percentil são diferentes, mas mostram apenas os percentis 50, 95 e 99 do mesmo bucket. O erro entre a estimativa e as medições reais não pode ser determinado porque a medição não é conhecida.

Suponha um histograma de medidas como o mostrado na tabela a seguir:

Número do bucket	Limite inferior	Limite superior	Contagem	Intervalo de percentis
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

Para calcular o 50º percentil, faça o seguinte:

Use as contagens de buckets para determinar o bucket que contém o 50º percentil. Neste exemplo, o bucket número 8 contém o 50º percentil.
Calcule a estimativa usando a seguinte regra:
```
pth percentile = bucket_low +
                (bucket_up - bucket_low)*(p - p_low)/(p_up - p_low)
```
Na expressão anterior, p_low e p_up são os limites inferior e superior do intervalo de percentil do bucket. Da mesma forma, bucket_low e bucket_up são os limites inferior e superior do bucket. Os valores de p_low e p_up dependem de como as contagens são distribuídas entre os diferentes buckets.

Por exemplo, o 50º percentil é calculado da seguinte forma:

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

Para calcular o 95º percentil, substitua 50 por 95 na expressão anterior. Neste exemplo, em que há exatamente uma amostra, os percentis são os seguintes:

Percentil	Número do bucket	Valor
50º	8	192
95º	8	249,6
99º	8	254,7

O erro entre a estimativa e as medidas reais pode ser delimitado, mas não pode ser determinado porque a medição não é conhecida.

Caso 2: o número total de amostras é 10

Quando há 10 amostras, o 50º percentil pode estar em um bucket diferente do que os 95º e 99º percentis. No entanto, não há medições suficientes para que os 95º e 99º percentis estejam em buckets diferentes.

Suponha um histograma de medidas como o mostrado na tabela a seguir:

Número do bucket	Limite inferior	Limite superior	Contagem	Intervalo de percentis
0		1	4	0 - 40
1	1	2	2	40 a 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

Use o procedimento descrito anteriormente para calcular os percentis 50, 95 e 99. Por exemplo, o 50º percentil, que está no bucket número 1, é calculado da seguinte maneira:

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

Da mesma forma, o 95º percentil é calculado da seguinte maneira:

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

Usando o processo descrito anteriormente, os percentis podem ser calculados. Cada linha na tabela a seguir lista um percentil, o bucket correspondente e o valor calculado:

Percentil	Número do bucket	Valor	Erro máximo
50º	1	1.5	0,5
95º	8	192	74
99º	8	243,2	115,2

Neste exemplo e no anterior, o 95º percentil está no bucket número 8. No entanto, o cálculo do percentil é diferente. A diferença se deve à forma como as amostras são distribuídas. No primeiro exemplo, todas as amostras estão no mesmo bucket, enquanto no exemplo mais recente, as amostras estão em buckets diferentes.

Exemplo com dados reais

Esta seção contém um exemplo que ilustra como é possível determinar o modelo de bucket usado por uma métrica específica. Esta seção também ilustra como avaliar o possível erro nos valores de percentis calculados.

Identificar o modelo de bucket

Para determinar os buckets usados para uma métrica em um intervalo de tempo específico, chame o método projects.timeSeries/list da API Cloud Monitoring.

Por exemplo, para identificar o modelo de bucket de uma métrica, faça o seguinte:

Acesse a página da Web de projects.timeSeries/list.
Em APIs Explorer, insira o filtro que especifica a métrica, um horário de início e um horário de término.

Por exemplo, para receber informações sobre a métrica que armazena latências de solicitação de API, digite o seguinte:
```
metric.type="serviceruntime.googleapis.com/api/request_latencies"
resource.type="consumed_api"
```
Neste exemplo, o campo de filtro especifica um tipo de métrica e um tipo de recurso. Para mais informações sobre esses filtros, consulte Filtros do Monitoring.
Pressione Enter.

Veja a seguir a resposta da API list para uma métrica com valor de distribuição disponível em um projeto do 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"
              ]
            }
          }
        },

Na resposta da API, o campo value descreve os dados armazenados na matriz points. Os campos count e mean informam que, para o intervalo de tempo especificado, havia três medidas e o valor médio delas era 25,889. O campo bucketOptions mostra que o modelo exponencial está configurado para ter 66 buckets, uma escala de 1 e um fator de crescimento de 1,4.

Para calcular os limites inferior e superior do bucket com índice n, use as seguintes regras:

Limite inferior (1 ≤ n < N) = escala * (fator de crescimento)^(n-1)
Limite superior (0 ≤ n < N-1) = escala * (fator de crescimento)ⁿ

Nas expressões anteriores, N é o número total de buckets.

Os buckets dessa métrica, junto com o ponto médio de cada um, são mostrados na tabela a seguir:

n-ésimo bucket	Limite inferior	Limite superior	Ponto médio
0		1	Não relevante
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
…

Verificar os cálculos de percentis

Agora que a configuração do bucket é conhecida, para qualquer conjunto de medições, é possível prever os valores dos percentis 50, 95 e 99. Por exemplo, se houver uma amostra e ela estiver no bucket número 10, o valor do 50º percentil será 24,79.

Para recuperar os valores de percentil 50, 95 e 99 da métrica, use o método de API projects.timeSeries/list e inclua um período de alinhamento e um alinhador. Neste exemplo, as configurações a seguir foram selecionadas:

Alinhador: ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95, ou ALIGN_PERCENTILE_99
Período de alinhamento: 60 s

Para a seleção de ALIGN_PERCENTILE_50, cada valor na série temporal é o 50º percentil de um 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
          }
        }
      ]
    },

Para duas das amostras, o 50º percentil está no bucket 10. Para a outra amostra, ele está no bucket 11.

A tabela a seguir mostra os resultados da execução do método projects.timeSeries/list com diferentes alinhadores. A primeira linha corresponde ao caso em que o alinhador não é especificado. Quando você não especifica um alinhador, os valores de modelo do bucket e média são retornados. As três próximas linhas listam os dados retornados quando o alinhador está definido como ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95 e ALIGN_PERCENTILE_99:

Estatística	Amostra @ 15:06	Amostra @ 15:05	Amostra @ 15:04
mean	25,889	33,7435	Indisponível
50º percentil	24,79	34,71	24,79
95º percentil	28,51	39,91	28,51
99º percentil	28,84	40,37	28,84

Como os dois exemplos com dados sintéticos ilustram, os valores dos percentis dependem de como as amostras são distribuídas. Quando todas as amostras estão no mesmo bucket, o 50º percentil é o ponto médio desse bucket. No entanto, quando as amostras estão em buckets diferentes, essa distribuição afeta as estimativas.

Para determinar se o 50º percentil é uma estimativa razoável da média, compare o valor médio ao 50º percentil. O valor médio é retornado com os detalhes do bucket.

A seguir

Para saber como visualizar métricas com valor de distribuição, consulte Sobre métricas com valor de distribuição.

Percentis e métricas com valor de distribuição Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.