Esta página foi traduzida pela API Cloud Translation.

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

Neste documento, explicamos percentis e o modelo de histograma de dados de métrica com um tipo de valor Distribution. A métrica de distribuição define intervalos de valores, chamados de buckets, e registra a contagem de valores medidos que se enquadra em cada bucket. As métricas de distribuição não informam os valores de medidas individuais, mas relatam um histograma das contagens em buckets. Esse tipo de valor é usado pelos serviços quando há muitas medições individuais para serem coletadas, mas informações estatísticas, como médias ou percentis, sobre essas medições são valiosas.

Ao definir uma métrica com valor de distribuição em um mapa de calor, é possível usar uma opção na barra de ferramentas do gráfico para sobrepor os 50º, 95º e 99º percentis. Para exibir uma métrica com valor de distribuição em um gráfico de linhas, configure o gráfico para converter o valor de distribuição em um valor numérico. Essa conversão pode ser realizada usando um alinhador que seleciona um percentil.

A próxima seção desta página usa um exemplo sintético para mostrar como os percentis são determinados. O exemplo mostra que os valores de percentil dependem do número e da largura de buckets, da distribuição das medições e da contagem total de amostras. Os valores de percentis não dependem dos valores reais medidos porque não estão disponíveis no histograma.

Exemplo com dados sintéticos

Considere um modelo de bucket Exponential com uma escala de 1, 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 maior que o bucket finito com índice n.

Os exemplos a seguir mostram que a largura do bucket determina o 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 do percentil são diferentes, mas mostram apenas o 50º, o 95º e o 99º percentil 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 percentil
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 a 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 bucket para determinar o bucket que contém o 50º percentil. Neste exemplo, o bucket 8 contém o 50º percentil.
Calcule a estimativa usando a seguinte regra:
```
pth percentage = 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 valores de menor limites superiores 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 para p_low e p_up dependem de como o as contagens são distribuídas entre os diferentes buckets.

Por exemplo, o 50º percentil é calculado como:

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

Para calcular o percentil 95, substitua 50 por 95 na expressão anterior. Para este exemplo em que há exatamente uma amostra, o 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 percentil
0		1	4	0 a 40
1	1	2	2	40 a 60
2	2	4	1	60 a 70
3	4	8	1	70 a 80
4	8	16	1	80 a 90
5	16	32	0	0
6	32	64	0	0
7	64	128	0	0
8	128	256	1	90 a 100
9	256	512	0	0
10	512	1024	0	0
11	1024		0	0

Você pode usar o procedimento descrito anteriormente para computar os dias 50, 95 e 99%. Por exemplo, o 50o percentil, que está no número do bucket 1, é calculado da seguinte forma:

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

Da mesma forma, o percentil 95 é 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	Máximo de erros
50º	1	1.5	0,5
95º	8	192	74
99º	8	243.2	115,2

Neste e no exemplo anterior, o percentil 95 está no bucket número 8. No entanto, o cálculo do percentil é diferente. A diferença é devido à 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ções de APIs, 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.
Clique em Enter.

Veja a seguir a resposta list da API referente a 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, com o ponto médio de cada bucket, são mostrados na tabela a seguir:

no 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 50º, 95º e 99º percentis. 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 dos 50º, 95º e 99º percentis da métrica, use o método projects.timeSeries/list da API 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 segundos

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, 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 bucket de amostra, o 50o percentil será o ponto médio do Google Cloud. 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 informações sobre como visualizar métricas com valor de distribuição, consulte Sobre métricas com valor de distribuição