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 criar um gráfico com 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 percentis 50, 95 e 99. 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. É possível realizar essa conversão usando um aligner 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 percentis dependem do número de buckets, da largura deles, da distribuição das medidas 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, um fator de crescimento de 2 e 10 buckets finitos. Esse histograma contém 12 buckets, os 10 buckets finitos, um que especifica apenas um limite superior e um 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 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 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:

  1. Use as contagens de bucket para determinar o bucket que contém o 50o percentil. Neste exemplo, o bucket número 8 contém o 50o percentil.

  2. 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 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 50o percentil é calculado da seguinte forma:

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

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

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 – 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 50o 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 95o percentil é calculado da seguinte forma:

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 95o 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. 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:

  1. Acesse a página da Web de projects.timeSeries/list.

  2. 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 informações sobre a métrica que armazena as latências de solicitações de API, insira 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.

  3. 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)n

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

Os buckets dessa métrica e o ponto médio de cada um deles 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, é possível prever os valores dos percentis 50o, 95o e 99o para qualquer conjunto de medições. Por exemplo, se houver uma amostra e ela estiver no bucket número 10, o valor do 50o 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

Conforme ilustrado nos dois exemplos com dados sintéticos, os valores dos percentis dependem de como as amostras são distribuídas. Quando todas as amostras estiverem no bucket de amostra, o 50o percentil será 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 informações sobre como visualizar métricas com valor de distribuição, consulte Sobre métricas com valor de distribuição.