Como criar métricas de distribuição

Nesta página, explicamos como criar métricas com base em registros do tipo de distribuição usando o console do GCP e a API do Stackdriver Logging.

Visão geral

As métricas de distribuição exigem um filtro para selecionar as entradas de registro relevantes e um extrator de valor para coletar o valor numérico para a distribuição. O extrator de valor é do mesmo tipo que é usado para rótulos definidos pelo usuário.

Uma métrica de distribuição registra a distribuição estatística dos valores extraídos nos intervalos do histograma. Os valores extraídos não são registrados individualmente, mas a distribuição deles nos intervalos configurados é registrada, juntamente com a contagem, a média e a soma do desvio ao quadrado dos valores. É possível usar o layout padrão dos intervalos de histograma em sua distribuição ou ajustar os limites dos intervalos para capturar os valores de forma aproximada.

Como criar uma métrica de distribuição

Console do Logging

Siga estes passos para criar uma métrica com base em registros no Console do GCP:

  1. Clique em Stackdriver Logging > Métricas com base em registros, na lista de navegação no lado esquerdo do Console do GCP ou clique no seguinte botão:

    Acessar o Visualizador de registros

  2. Use o menu suspenso na parte superior da página para selecionar um projeto.

  3. Clique em Criar métrica na parte superior da página. O Editor de métricas é exibido no lado direito da página, e os registros são mostrados no painel do visualizador, no lado esquerdo:

    Criar métrica de distribuição

  4. No painel do visualizador, crie um filtro para mostrar apenas as entradas de registro que você quer contar na métrica.

    O filtro básico está disponível nos menus suspensos acima das entradas de registro. Como alternativa, acesse a interface avançada do filtro clicando no menu suspenso no lado direito da barra de pesquisa e selecionando Converter para filtro avançado.

    Para saber mais informações, consulte Interfaces do usuário.

  5. No painel Editor de métricas, defina os seguintes campos:

    • Nome: escolha um nome que seja exclusivo entre as métricas com base em registros no projeto. Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para saber detalhes.
    • Descrição: descreva a métrica.
    • Rótulos: (opcional) adicione rótulos clicando em Adicionar item para cada rótulo. Para saber detalhes sobre como definir rótulos, consulte Rótulos de métricas com base em registros.
    • Unidades: (opcional) para métricas de distribuição, também é possível inserir unidades, como s, ms etc. Para saber mais informações, consulte o campo unit do MetricDescriptor.
    • Tipo: distribuição.
    • Nome do campo: digite o campo da entrada de registro que contém o valor da distribuição. Conforme você digita, aparecem opções. Exemplo:

      jsonPayload.latency
      
    • Expressão de extração: (opcional) se Nome do campo sempre contiver um valor numérico conversível no tipo double, deixe esse campo vazio. Caso contrário, especifique uma expressão regular que extraia o valor de distribuição numérico do valor do campo. O menu Criar pode ser usado para criar e verificar interativamente a expressão regular.

      Exemplo. Suponha que o campo de entrada de registro de latency contenha um número seguido por ms para milissegundos. O seguinte regexp escolhe o número sem o sufixo da unidade:

      ([0-9.]+)ms
      

      Os parênteses, conhecidos como um grupo de captura regexp, identificam a parte da correspondência de texto que será extraída. Para saber mais informações sobre expressões regulares, consulte Sintaxe RE2.

    • Mais (intervalos do histograma): (opcional) clique em Mais para abrir uma seção do formulário onde você especifica layouts de intervalo personalizados. Se você não especificar layouts de intervalo, um layout padrão será fornecido. Para saber mais informações, consulte Intervalos do histograma nesta página.

  6. Clique em Criar métrica.

Logging API

Para criar uma métrica de distribuição, use o método projects.metrics.create da Stackdriver Logging API. Teste o método no [APIs Explorer] [apis-explorer-create]. Prepare os argumentos do método da seguinte maneira:

  1. Defina o campo pai como o projeto em que a métrica será criada:

    projects/[PROJECT_ID]
    
  2. Defina o corpo da solicitação como um objeto LogMetric. Veja a seguir um exemplo do objeto para uma métrica de distribuição:

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",
    
      labelExtractors: {
        "my-label-1":
          "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
        "my-label-2":
          "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
      },
      bucketOptions: { [SEE_BELOW] },
    
      metricDescriptor: {
          metricKind: DELTA,
          valueType: DISTRIBUTION,
          unit: "ms",
    
          labels: [
            {
              key: "my-label-1",
              valueType: STRING,
              description: "Description of string my-label-1.",
            },
            {
              key: "my-label-2",
              valueType: INT64,
              description: "Description of integer my-label-2.",
            }
          ]
      },
    }
    

Observações para métricas de distribuição:

  • Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para saber detalhes.

  • metricDescriptor: um objeto MetricDescriptor. metricKind precisa ser DELTA. valueType precisa ser DISTRIBUTION.

Intervalos do histograma

As métricas de distribuição incluem um histograma que conta o número de valores que caem em intervalos especificados. Tenha até 200 intervalos em uma métrica de distribuição.

Cada intervalo tem dois valores limite, L e H, que definem os valores mais baixos e mais altos cobertos pelo intervalo. A largura do intervalo é H - L. Uma vez que não pode haver lacunas entre os intervalos, o limite inferior de um intervalo é o mesmo que o limite superior do intervalo anterior e assim por diante. Para que os limites não caiam em mais de um intervalo, o intervalo inclui o limite inferior. O limite superior pertence ao próximo intervalo.

Todos os layouts do intervalo podem ser especificados com a listagem, em ordem crescente, dos valores de limite entre intervalos individuais. O primeiro é o intervalo de subfluxo, que conta valores inferiores ao primeiro limite. O último é o intervalo de sobrefluxo, que conta valores maiores ou iguais ao último limite. Os outros intervalos contam valores maiores ou iguais ao limite inferior e valores menores que o limite superior. Se houver n valores de limite, então haverá n+1 intervalos. Excluindo os intervalos de subfluxo e sobrefluxo, há n-1 intervalos finitos.

Há três maneiras diferentes de especificar os limites entre os intervalos de histograma para métricas de distribuição: Você especifica uma fórmula para os valores de limite ou lista os valores de limite:

  • Linear(deslocamento, largura, i): todo intervalo tem a mesma largura. Os limites são deslocamento + largura * i, para i=0,1,2,...,N. Para saber mais informações sobre intervalos lineares, consulte a referência da API.

  • Exponencial(escala, fator_de_crescimento, i): as larguras de intervalo aumentam para valores maiores. Os limites são escala * fator_de_crescimento^i, para i=0,1,2,...,N. Para saber mais informações sobre intervalos exponenciais, consulte a referência da API.

  • Explícito: você lista todos os limites dos intervalos na matriz de limites. O intervalo i tem esses limites:

    Limite máximo: limites[i] para (0 <= i < N-1)
    Limite mínimo: limites[i - 1] para (1 <= i < N)

    Para saber mais informações sobre intervalos explícitos, consulte a referência da API.

Na seção a seguir, explicamos como especificar os intervalos do histograma.

Console do Logging

Depois de criar uma métrica de distribuição, clique em Mais no formulário Editor de métricas para abrir o submenu Intervalos do histograma. Veja abaixo o subformulário do layout para o intervalo Linear:

Intervalos do histograma

Intervalos lineares: preencha o formulário do intervalo do histograma da seguinte maneira.

  • Tipo: linear
  • Valor inicial (a): o limite mínimo do primeiro intervalo finito. Esse valor é chamado de deslocamento na API.
  • Número de intervalos (N): o número de intervalos finitos. O valor precisa ser maior que ou igual a 0.
  • Largura do intervalo (b): a diferença entre os limites máximo e mínimo em cada intervalo finito. O valor precisa ser maior que 0.

Por exemplo, se o valor inicial for 5, o número de intervalos for 4 e o tamanho do intervalo for 15, então as faixas do intervalo serão as seguintes:

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Intervalos explícitos: preencha o formulário de intervalo do histograma da seguinte maneira:

  • Tipo: explícito
  • Limites (b): uma lista separada por vírgulas dos valores de limite dos intervalos finitos. Isso também determina o número de intervalos e os tamanhos deles.

Por exemplo, se a lista de limites for:

0, 1, 2, 5, 10, 20

então há cinco intervalos finitos com as seguintes faixas:

[-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF]

Intervalos exponenciais: preencha o formulário de intervalo do histograma da seguinte maneira:

  • Tipo: exponencial
  • Número de intervalos (N): o número total de intervalos finitos. O valor precisa ser maior que 0.

  • Escala linear (a): a escala linear dos intervalos. O valor precisa ser maior que 0.

  • Fator de crescimento exponencial (b): o fator de crescimento exponencial dos intervalos. O valor precisa ser maior que 1.

Por exemplo, se N=4, a=3 e b=2, as faixas do intervalo serão as seguintes:

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Para saber mais sobre os intervalos, consulte BucketOptions na Stackdriver Monitoring API.

Logging API

O layout de intervalo opcional é especificado pelo campo bucketOptions do objeto LogMetric fornecido para projects.metrics.create. Para o objeto LogMetric completo, consulte Como criar uma métrica de distribuição, nesta página. As adições para layouts de intervalo são mostradas abaixo:

Intervalos lineares:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

A amostra anterior cria os seguintes intervalos:

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Intervalos explícitos: os limites são listados individualmente.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

A amostra anterior cria os seguintes intervalos:

[-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF]

Intervalos exponenciais: os limites são scale * growthFactor ^ i para i=0,1,2, ..., numFiniteBuckets

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

A amostra anterior cria os seguintes intervalos:

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Latência da nova métrica

A nova métrica aparecerá imediatamente na lista de métricas do Visualizador de registros e nos menus pertinentes do Stackdriver Monitoring. No entanto, pode demorar até um minuto para que a métrica comece a coletar dados para as entradas de registros correspondentes.

Como inspecionar métricas de distribuição

Para listar as métricas com base em registros no projeto do GCP ou para inspecionar uma métrica específica no projeto, faça o seguinte:

Console do Logging

Para acessar a página Métricas com base em registros, que lista todas as métricas com base em registros no projeto atual, clique no botão a seguir:

Acessar métricas com base em registros

Para visualizar os dados em uma métrica com base em registros, selecione Ver no Metrics Explorer no menu flutuante, no lado direito da listagem da métrica.

API Logging

Como listar métricas

Para listar as métricas com base em registros definidas pelo usuário em um projeto, use o método API projects.metrics.list. Preencha os parâmetros do método da seguinte maneira:

  • parent: o nome do recurso do projeto: projects/[PROJECT_ID].
  • pageSize: o número máximo de resultados.
  • pageToken: recebe a próxima página de resultados. Consulte projects.metrics.list.

Como recuperar definições de métrica

Para recuperar uma única métrica com base em registros definida pelo usuário, use o método API projects.metrics.get. Preencha os parâmetros do método da seguinte maneira:

  • metricName: o nome do recurso da métrica:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

Leitura de dados métricos

Para ler os dados da série temporal em uma métrica com base em registros, use projects.timeseries.list na API Stackdriver Monitoring. Para saber mais detalhes, consulte Como ler séries temporais. Esta é a informação necessária para métricas com base em registros:

  • O tipo de métrica é logging.googleapis.com/user/[METRIC_ID].

SDK do Cloud

Para listar as métricas com base em registros definidas pelo usuário no seu projeto, use o seguinte comando:

gcloud logging metrics list

Para exibir uma métrica com base em registros definida pelo usuário no projeto, use o seguinte comando:

gcloud logging metrics describe [METRIC_NAME]

Para saber mais detalhes, use o seguinte comando:

gcloud logging metrics --help

Não é possível ler dados da série temporal de uma métrica do Cloud SDK.

Como atualizar métricas de distribuição

Atualize uma métrica com base em registros para alterar a descrição, os filtros e os nomes dos campos referenciados na métrica. Adicione novos rótulos à métrica e altere as expressões regulares usadas para extrair valores para a métrica e seus rótulos.

Não é possível alterar os nomes ou tipos de métricas com base em registros ou os rótulos deles e excluir rótulos atuais em uma métrica com base em registros.

Para editar ou atualizar uma métrica com base em registros, siga as instruções abaixo:

Console do Logging

  1. Vá para a página Métricas com base em registros:

    Acessar métricas com base em registros

  2. Clique em Editar métrica no menu no lado direito da métrica com base em registros que você quer editar.

  3. Altere apenas os itens permitidos na métrica.

  4. Clique em Concluído.

Logging API

Para editar ou atualizar uma métrica com base em registros, use o método projects.metrics.update na API. Defina os campos da seguinte maneira:

  • metricName: o nome completo do recurso da métrica:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    Exemplo:

    projects/my-gcp-project/metrics/my-error-metric
    
  • No corpo da solicitação, inclua um objeto LogMetric que seja exatamente igual à métrica atual, exceto pelas alterações e adições que você quer fazer.

SDK do Cloud

Ele permite alterar somente a descrição e o filtro de uma métrica atual.

Para atualizar uma métrica com base em registros, use o comando a seguir. Especifique uma ou ambas as sinalizações:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

Para saber mais detalhes, use o seguinte comando:

gcloud logging metrics update --help

Como excluir métricas de distribuição

Para excluir uma métrica com base em registros, faça o seguinte:

Console do Logging

  1. Vá para a página Métricas com base em registros:

    Acessar métricas com base em registros

  2. Selecione as métricas que você quer excluir e clique em Excluir na parte superior da página.

    Também é possível clicar em Excluir métrica no menu no lado direito da métrica com base em registros que você quer excluir.

API Logging

Use o método projects.metrics.delete na API.

SDK do Cloud

Use o seguinte comando para excluir uma métrica com base em registros definida pelo usuário no projeto atual:

gcloud logging metrics delete [METRIC_NAME]

Para saber mais detalhes, use o seguinte comando:

gcloud logging metrics delete --help

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.