Configurar métricas de contador

Neste documento, explicamos como criar uma métrica com base em registros do tipo contador usando o console do Google Cloud, a API Logging e a Google Cloud CLI.

As métricas de contador contam o número de entradas de registro que correspondem a determinado filtro. Por exemplo, é possível criar uma métrica com base em registros que conta o número de entradas de registro que contêm uma mensagem de erro específica. As métricas com base em registros podem ser aplicadas a um único projeto do Google Cloud ou a um bucket de registros.

Para uma visão geral das métricas com base em registros, consulte Visão geral das métricas com base em registros.

Antes de começar

  1. Para usar métricas com base em registros, é preciso ter um projeto do Google Cloud com faturamento ativado:

    1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
    2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

      Acessar o seletor de projetos

    3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

    4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

      Acessar o seletor de projetos

    5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  2. Verifique se o papel do Identity and Access Management inclui as permissões necessárias para criar e visualizar métricas com base em registros e para criar políticas de alertas. Para mais detalhes, consulte Permissões para métricas com base em registros.

Criar uma métrica com base em registros do tipo contador

A métrica conta as entradas de registro identificadas por um filtro fornecido. Você pode usar expressões regulares no filtro, e recomendamos incluir um tipo de recurso. O comprimento de um filtro não pode exceder 20.000 caracteres.

Não coloque informações sensíveis no filtro. Os filtros são tratados como dados de serviço.

Console

Siga estas etapas para criar uma métrica de contador no console do Google Cloud no seu projeto do Google Cloud:

  1. No painel de navegação do console do Google Cloud, selecione Logging e, em seguida, Métricas com base em registros:

    Acessar Métricas com base em registros

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

  3. Defina o Tipo de métrica: selecione Contador.

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

    • Nome da métrica de registro: escolha um nome que seja exclusivo entre as 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: deixe em branco ou insira o dígito 1.
  5. Defina o filtro de métricas na seção Seleção de filtro.

    1. Use Selecionar escopo do registro para escolher se o filtro vai segmentar todos os registros do projeto do Google Cloud ou somente os registros em um bucket 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. Para verificar 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 Como criar um rótulo.

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

gcloud

É possível criar uma métrica com base em registros sem rótulos personalizados usando o seguinte comando:

gcloud logging metrics create METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  [--bucket-name="BUCKET_NAME"]

Por exemplo, o comando a seguir cria uma métrica com base em registros no escopo do projeto chamada error_count.

gcloud logging metrics create error_count \
     --description "Errors in syslog." \
     --log-filter "resource.type=gce_instance AND log_id(\"syslog\") AND severity>=ERROR"

Para criar uma métrica com base em registros com escopo de bucket, forneça a sinalização --bucket_name:

gcloud logging metrics create error_count \
    --description "Errors in syslog." \
    --log-filter "resource.type=gce_instance AND log_id(\"syslog\") AND severity>=ERROR" \
    --bucket-name projects/my-project/locations/global/buckets/my-test-bucket

Para instruções sobre como criar rótulos, consulte Como criar um rótulo.

API

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

  1. Defina o campo parent do projeto ou bucket em que a métrica será criada:

    • Para uma métrica com base em registros no escopo do 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. Veja a seguir um exemplo de objeto para uma métrica de contador:

    {
      name:        "my-metric"
      description: "This is my metric."
      filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
      metricDescriptor: {
          labels: [
            {
              key: "my-label",
              valueType: STRING,
              description: "This is my label.",
            }
          ]
      },
      labelExtractors: {
        "my-label":
          "REGEXP_EXTRACT(jsonPayload.someField, \"before ([0-9]+) after\")",
        ...
      },
    }
    

Observações:

  • Escolha um nome de métrica 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 detalhes.

  • Para métricas de contador, os campos valueExtractor e bucketOptions do LogMetric não têm finalidade e são omitidos.

  • Se sua métrica não tiver rótulos, será possível omitir os campos metricDescriptor e labelExtractors. Se a métrica tiver rótulos, consulte rótulos de métricas com base em registros para ver uma introdução aos rótulos e detalhes sobre como criá-los na API.

Para ver mais detalhes, consulte o tipo LogMetric.

Latência de novas métricas

A nova métrica aparece imediatamente na lista de métricas da Análise de registros e nos menus relevantes do Monitoring. Os dados geralmente ficam disponíveis em menos de um minuto.

Inspecionar métricas com base em registros

Para listar as métricas com base em registros definidas pelo usuário no seu projeto do Google Cloud ou para inspecionar uma métrica específica no projeto do Google Cloud, faça o seguinte:

Console

  1. No painel de navegação do console do Google Cloud, selecione Logging e, em seguida, Métricas com base em registros:

    Acessar Métricas com base em registros

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

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

gcloud

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

gcloud logging metrics list

Para exibir uma métrica com base em registros definida pelo usuário no projeto do Google Cloud, use o seguinte 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 de 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 da 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 da 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
    

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 os parâmetros do método com este tipo de métrica e identificador:

logging.googleapis.com/user/METRIC_ID

Atualizar métricas com base em registros

É possível editar uma métrica com base em registros definida pelo usuário para alterar a descrição, o filtro 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. Se você estiver usando uma métrica com escopo de bucket, também poderá atualizar o bucket da métrica.

Não é possível alterar os nomes ou tipos de métricas com base em registros definidas pelo usuário ou os rótulos delas, nem excluir rótulos atuais em uma métrica com base em registros.

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

Console

  1. No painel de navegação do console do Google Cloud, selecione Logging e, em seguida, Métricas com base em registros:

    Acessar Métricas com base em registros

  2. Clique em Editar métrica no Menu 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

Use o Google Cloud CLI para alterar a descrição, a consulta e o bucket de uma métrica de contador. 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, todos os dados de métricas coletados antes da alteração não refletirão mais a configuração atual. Os dados de métricas coletados do bucket anterior não são removidos.

Para atualizar métricas de distribuição ou outros campos de métricas de contagem, exceto METRIC_NAME, crie um arquivo que contenha a especificação revisada do seu LogMetric no formato JSON ou YAML. Em seguida, atualize a 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 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.

Excluir métricas com base em registros

Para excluir uma métrica com base em registros definida pelo usuário, faça o seguinte:

Console

  1. No painel de navegação do console do Google Cloud, selecione Logging e, em seguida, Métricas com base em registros:

    Acessar Métricas com base em registros

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

    Outra opção é clicar em Excluir métrica no menu 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

For more details, use the following command:

gcloud logging metrics delete --help

API

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

Além disso, na página Métrica com base em registros do console do Google Cloud, o painel Métricas definidas pelo usuário da interface de métricas com base em registros fornece mais recursos para ajudar no gerenciamento das métricas definidas pelo usuário no seu projeto do Google Cloud. Consulte o painel de métricas definidas pelo usuário para ver mais detalhes.