Configurar métricas de contador

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

As métricas de contagem contam o número de entradas de registro que correspondem a um 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 em um único Google Cloud projeto ou em 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 baseadas em registros, é preciso ter um Google Cloud projeto com faturamento ativado:

   Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

   Make sure that billing is enabled for your Google Cloud project.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

   Make sure that billing is enabled for your Google Cloud project.

   1. Verifique se seu 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 por você. É possível usar expressões regulares no filtro. Recomendamos que você inclua 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 consoleGoogle Cloud no seu projeto Google Cloud :

   1. No console 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 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 Google Cloud . Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para 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 o menu Selecionar projeto ou bucket de registros para escolher se a métrica conta as entradas de registro no seu projeto Google Cloud ou apenas as entradas 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. Para ver quais entradas de registro correspondem ao 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 comando a seguir:

   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 com 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 no escopo do bucket, forneça a flag --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 Configurar rótulos em métricas com base em registros.

   API

   Para criar uma métrica de contador, use o método projects.metrics.create da API Logging. Se você usar o painel do APIs Explorer na página de referência, prepare os argumentos da seguinte maneira:

   1. Defina o campo parent como o 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 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 de 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, que é uma introdução aos rótulos com detalhes sobre como criá-los na API.

   Para mais detalhes, consulte o tipo LogMetric.

   Latência de novas métricas

   Sua nova métrica aparece na lista de métricas do Explorador de registros e nos menus relevantes do Monitoring imediatamente. 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 Google Cloud ou inspecionar uma métrica específica no projeto Google Cloud , faça o seguinte:

   Console

   1. No console 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, são exibidas as métricas com base em registros definidas pelo usuário no Google Cloud projeto atual:

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

   gcloud

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

   gcloud logging metrics list
   

   Para mostrar uma métrica com base em registros definida pelo usuário no seu projeto 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 da Google Cloud CLI.

   API

   Listar métricas

   Para listar as métricas com base em registros definidas pelo usuário em um Google Cloud projeto, 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 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 de série temporal em uma métrica com base em registros, use projects.timeseries.list na API Cloud Monitoring. Para 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 mudar 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 mudar os nomes ou tipos de métricas com base em registros definidas pelo usuário ou os rótulos correspondentes. Além disso, não é possível excluir rótulos existentes em uma métrica com base em registros.

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

   Console

   1. No console 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 no more_vert 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 a Google Cloud CLI para mudar a descrição, a consulta de filtro e o bucket de uma métrica de contador. É possível atualizar todos os campos de uma vez.

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

   Se você mudar o bucket associado a uma métrica no escopo do bucket, os dados coletados antes da mudança não vão mais refletir a configuração atual. Os dados de métricas coletados para o bucket anterior não são removidos.

   Para atualizar métricas de distribuição ou outros campos de métricas de contador, 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 seu 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 console 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.

      Como alternativa, clique em Excluir métrica no more_vert menu da métrica com base em registros que você quer excluir.

   gcloud

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

   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 projects.metrics.delete na API.

   Além disso, na página Métrica com base em registros do console Google Cloud , o painel Métricas definidas pelo usuário da interface de métricas com base em registros oferece mais recursos para ajudar você a gerenciar as métricas definidas pelo usuário no projetoGoogle Cloud . Consulte Métricas definidas pelo usuário para mais detalhes.