Configurar métricas de distribuição

Console

Siga estas etapas para criar uma métrica de contador com base em registros no Console do Google Cloud no seu projeto do Google Cloud:

1. No console do Google Cloud, acesse a página Métricas com base em registros.

   Acessar Métricas com base em registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. Clique em Criar métrica. O painel Criar métrica de registros é exibido.

3. Defina o Tipo de métrica: selecione Distribuição.

4. Defina os seguintes campos na seção Detalhes:

   • Nome da métrica de registro: escolha um nome que seja exclusivo entre métricas com base em registros no projeto do Google Cloud. Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para ver detalhes.
   • Descrição: insira uma descrição para a métrica.
   • Unidades: (opcional) para métricas de distribuição, é possível insira unidades, como s e ms. Para mais informações, consulte a unit do MetricDescriptor.

5. Defina o filtro de métricas na seção Seleção de filtro.

   1. Use o menu Selecionar bucket do projeto ou do registro para determinar se o métrica conta as entradas de registro no seu projeto do Google Cloud ou apenas em um bucket de registros específico.

   2. Crie um filtro que colete apenas as entradas de registros que você quer contar na métrica usando a linguagem de consulta de geração de registros. Também é possível usar expressões regulares para criar os filtros da métrica.

   3. 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:

      protoPayload.latency
      

   4. Expressão regular: (opcional) se o Nome do campo sempre for contiver um valor numérico conversível para o tipo double, você poderá deixe este campo em branco. Caso contrário, especifique uma expressão regular que extraia o valor de distribuição numérico do valor do campo.

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

      ([0-9.]+)
      

      Os parênteses, conhecidos como um grupo de captura regexp, identificam a parte da correspondência de texto que será extraída. Para mais detalhes, consulte Como usar expressões regulares.

   • Avançado (buckets do histograma): (opcional) clicar em Avançado abre uma seção do formulário que pode ser usada para especificar layouts de bucket personalizados. Se você não especificar os layouts do bucket, um layout padrão será fornecido. Para mais informações, consulte buckets do histograma nesta página.
   1. Para saber quais entradas de registro correspondem ao seu filtro, clique em Visualizar registros.

6. (Opcional) Adicione um rótulo na seção Rótulos. Para instruções sobre como criar rótulos, consulte Criar um rótulo.

7. Clique em Criar métrica para criá-la.

gcloud

Para criar uma métrica com base em registros do tipo distribuição, crie um arquivo que contenha uma representação dos seus A definição de LogMetric em nos formatos JSON ou YAML. Depois, use o comando a seguir para ler do arquivo:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

Para informações sobre como descrever os buckets de histograma de uma distribuição, consulte Buckets de histograma.

API

Para criar uma métrica de distribuição, use o método projects.metrics.create da API Logging. É possível testar o método no APIs Explorer. Prepare os argumentos do método da seguinte maneira:

1. Defina o campo pai como o projeto ou bucket em que a métrica está a serem criados:

   • Para uma métrica com base em registros com escopo de projeto, especifique o projeto:

   projects/PROJECT_ID
   

   • Para uma métrica com base em registros com escopo de bucket, especifique o bucket:

   projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
   

2. Defina o corpo da solicitação como um objeto LogMetric. Seguir é uma amostra objeto para uma métrica de distribuição.

   {
     name:        "my-metric"
     description: "Description of my-metric."
     filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
     valueExtractor: "REGEXP_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:

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

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

Console

Depois de criar uma métrica de distribuição, clique em Mais no formulário Editor de métricas para abrir o submenu buckets do histograma. O subformulário a seguir é para o layout de bucket Linear:

buckets lineares: preencha o formulário do bucket do histograma da seguinte maneira.

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

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

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

buckets explícitos: preencha o formulário de bucket do histograma da seguinte maneira:

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

Por exemplo, se a lista de limites for:

0, 1, 2, 5, 10, 20

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

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

buckets exponenciais: preencha o formulário de bucket do histograma da seguinte maneira:

• Tipo: exponencial

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

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

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

Por exemplo, se N=4, a=3 e b=2, então o bucket variará são os seguintes:

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

Para mais informações sobre os buckets, consulte BucketOptions na API Cloud Monitoring.

API

O layout de bucket opcional é especificado pelo campo bucketOptions em o objeto LogMetric fornecido para projects.metrics.create. Para o objeto LogMetric completo, consulte Criar uma métrica de distribuição nesta página. As adições para layouts de bucket são as mostradas a seguir:

buckets lineares:

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

A amostra anterior cria os seguintes buckets:

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

Buckets 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 buckets:

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

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

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

A amostra anterior cria os seguintes buckets:

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

Console

1. No console do Google Cloud, acesse a página Métricas com base em registros.

   Acessar Métricas com base em registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. No painel Métricas definidas pelo usuário, você encontra métricas com base em registros no projeto atual do Google Cloud:

3. Para exibir os dados em uma métrica com base em registros, clique no more_vert Menu em na linha da métrica e selecione Ver no Metrics Explorer.

gcloud

Para listar as métricas com base em registros definidas pelo usuário no projeto do Google Cloud, use este comando:

gcloud logging metrics list

Para exibir uma métrica com base em registros definida pelo usuário no projeto do Google Cloud, faça o seguinte: use este comando:

gcloud logging metrics describe METRIC_NAME

Para receber ajuda, use o seguinte comando:

gcloud logging metrics --help

Não é possível ler os dados da série temporal de uma métrica na Google Cloud CLI.

API

Listar métricas

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

• parent: o nome do recurso do projeto do Google Cloud: projects/PROJECT_ID
• pageSize: o número máximo de resultados.
• pageToken: recebe a próxima página de resultados. Para informações sobre como usar tokens de página, consulte projects.metrics.list.

Recuperar definições de métricas

Para recuperar uma única métrica com base em registros definida pelo usuário, use o método 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
  

Ler dados de métricas

Para ler os dados da série temporal em uma métrica com base em registros, use projects.timeseries.list na API Cloud Monitoring. Para ver detalhes sobre os dados de série temporal, consulte Como ler séries temporais.

Para ler uma única métrica com base em registros definida pelo usuário, preencha o campo com esse tipo de métrica e identificador:

logging.googleapis.com/user/METRIC_ID

Console

1. No console do Google Cloud, acesse a página Métricas com base em registros.

   Acessar Métricas com base em registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. Clique em Editar métrica na more_vert Cardápio da métrica com base em registros que você quer modificar.

3. Altere os itens permitidos na métrica.

4. Clique em Atualizar métrica.

gcloud

Usar a Google Cloud CLI para alterar a descrição e o filtro de uma métrica de contador e um bucket. Você pode atualizar qualquer um ou todos os campos de uma só vez.

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

Se você alterar o bucket associado a uma métrica com escopo de bucket, os dados de métricas coletados antes da mudança não refletem mais o configuração atual. Os dados de métricas coletados para o bucket anterior não é removido.

Para atualizar métricas de distribuição ou outros campos de métricas de contagem, excluindo o METRIC_NAME, crie um arquivo que contenha a especificação revisada de LogMetric no formato JSON ou YAML. Depois, atualize o métrica chamando o comando update com o campo --config-from-file, substituindo FILENAME pelo nome do arquivo JSON ou YAML:

gcloud logging update METRIC_NAME --config-from-file FILENAME

Para saber mais detalhes, use o seguinte comando:

gcloud logging metrics update --help

API

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

• 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.

Console

1. No console do Google Cloud, acesse a página Métricas com base em registros.

   Acessar Métricas com base em registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. Selecione a métrica que você quer excluir e clique em Excluir.

   Se preferir, clique em Excluir métrica na Cardápio more_vert da métrica com base em registros que você quer excluir.

gcloud

Use o comando a seguir para excluir uma métrica com base em registros definida pelo usuário. no projeto atual do Google Cloud:

gcloud logging metrics delete METRIC_NAME

Para saber mais detalhes, use o seguinte comando:

gcloud logging metrics delete --help

API

Para excluir uma métrica com base em registros definida pelo usuário, use o método método projects.metrics.delete na API.