Configure métricas de contador

Este documento explica como criar uma métrica baseada em registos do tipo contador através da consola, da API Logging e da CLI Google Cloud. Google Cloud

As métricas de contador contabilizam o número de entradas de registo que correspondem a um determinado filtro. Por exemplo, pode criar uma métrica baseada em registos que conte o número de entradas de registo que contêm uma mensagem de erro específica. As métricas baseadas em registos podem ser aplicadas num único Google Cloud projeto ou num contentor de registos.

Para uma vista geral das métricas baseadas em registos, consulte o artigo Vista geral das métricas baseadas em registos.

Antes de começar

1. Para usar métricas baseadas em registos, tem de ter um Google Cloud projeto com a faturação ativada:

   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.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   1. Certifique-se de que a sua função de gestão de identidade e acesso inclui as autorizações necessárias para criar e ver métricas baseadas em registos, bem como para criar políticas de alerta. Para ver detalhes, consulte o artigo Autorizações para métricas baseadas em registos.

   Crie uma métrica baseada em registos do tipo contador

   A métrica contabiliza as entradas de registo identificadas por um filtro que fornece. Pode usar expressões regulares no filtro e recomendamos que inclua um tipo de recurso. O comprimento de um filtro não pode exceder 20 000 carateres.

   Não inclua informações confidenciais no filtro. Os filtros são tratados como dados de serviço.

   Nota: consulte a secção de Resolução de problemas seguinte se estiver a criar métricas baseadas em registos nos registos de auditoria.

   Consola

   Siga estes passos para criar uma métrica de contador na Google Cloud consola no seu Google Cloud projeto:

   1. Na Google Cloud consola, aceda à página Métricas baseadas em registos:

      Aceda a Métricas baseadas em registos

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

   2. Clique em Criar métrica. É apresentado o painel Criar métrica de registos.

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

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

      • Nome da métrica de registo: escolha um nome exclusivo entre as métricas baseadas em registos no seu Google Cloud projeto. Aplicam-se algumas restrições de nomenclatura. Consulte a secção Resolução de problemas para ver detalhes.
      • Descrição: introduza uma descrição para a métrica.
      • Unidades: deixe este campo em branco ou insira o dígito 1.

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

      1. Use o menu Selecionar projeto ou contentor de registos para escolher se a métrica conta as entradas de registo no seu Google Cloud projeto ou apenas essas entradas de registo num contentor de registos específico.

      2. Crie um filtro que recolha apenas as entradas do registo que quer contar na sua métrica através da linguagem de consulta de registo. Também pode usar expressões regulares para criar os filtros da sua métrica.

      3. Para ver que entradas de registo correspondem ao seu filtro, clique em Pré-visualizar registos.

   6. (Opcional) Adicione uma etiqueta na secção Etiquetas. Para obter instruções sobre como criar etiquetas, consulte o artigo Criar uma etiqueta.

   7. Clique em Criar métrica para criar a métrica.

   gcloud

   Pode criar uma métrica baseada em registos sem etiquetas personalizadas através do seguinte comando:

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

   Nota: escolha um nome de métrica que seja único entre as métricas baseadas em registos no seu Google Cloud projeto. Aplicam-se algumas restrições de nomenclatura. Consulte o artigo Resolva problemas de métricas baseadas em registos para ver detalhes.

   Por exemplo, o comando seguinte cria uma métrica baseada em registos com âmbito do projeto denominada 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"
   

   Em alternativa, para criar uma métrica baseada em registos com âmbito de contentor, 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 obter instruções sobre como criar etiquetas, consulte o artigo Configure etiquetas em métricas baseadas em registos.

   API

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

   1. Defina o campo parent para o projeto ou o contentor no qual a métrica vai ser criada:

      • Para uma métrica baseada em registos ao nível do projeto, especifique o projeto:

      projects/PROJECT_ID
      

      • Para uma métrica baseada em registos com âmbito de contentor, especifique o contentor:

      projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
      

   2. Defina o corpo do pedido como um objeto LogMetric. Segue-se um objeto de exemplo 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\")",
          ...
        },
      }
      

   Notas:

   • Escolha um nome de métrica que seja único entre as métricas baseadas em registos no seu projeto. Aplicam-se algumas restrições de nomenclatura. Consulte a secção Resolução de problemas para ver detalhes.

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

   • Se a sua métrica não tiver etiquetas, pode omitir os campos metricDescriptor e labelExtractors. Se a sua métrica tiver etiquetas, consulte as etiquetas de métricas baseadas em registos para uma introdução às etiquetas e detalhes sobre a respetiva criação na API.

   Para mais detalhes, consulte o tipo LogMetric.

   Latência das novas métricas

   A nova métrica aparece imediatamente na lista de métricas do Explorador de registos e nos menus de monitorização relevantes. Normalmente, os dados estão disponíveis em menos de um minuto.

   Inspecione métricas baseadas em registos

   Para listar as métricas baseadas em registos definidas pelo utilizador no seu Google Cloud projeto ou para inspecionar uma métrica específica no seu Google Cloud projeto, faça o seguinte:

   Consola

   1. Na Google Cloud consola, aceda à página Métricas baseadas em registos:

      Aceda a Métricas baseadas em registos

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

   2. No painel Métricas definidas pelo utilizador, são apresentadas as métricas baseadas em registos definidas pelo utilizador no projeto Google Cloud atual:

   3. Para ver os dados numa métrica baseada em registos, clique no Menu na linha da métrica e selecione Ver no Explorador de métricas.

   gcloud

   Para apresentar uma lista das métricas baseadas em registos definidas pelo utilizador no seu Google Cloud projeto, use o seguinte comando:

   gcloud logging metrics list
   

   Para apresentar uma métrica baseada em registos definida pelo utilizador no seu Google Cloud projeto, use o seguinte comando:

   gcloud logging metrics describe METRIC_NAME
   

   Para obter ajuda, use o seguinte comando:

   gcloud logging metrics --help
   

   Não pode ler os dados com intervalos temporais de uma métrica a partir da CLI do Google Cloud.

   API

   Métricas de listas

   Para listar as métricas baseadas em registos definidas pelo utilizador num Google Cloud projeto, use o método da API projects.metrics.list. Preencha os parâmetros do método da seguinte forma:

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

   Obtenha definições de métricas

   Para obter uma única métrica baseada em registos definida pelo utilizador, use o método da API projects.metrics.get. Preencha os parâmetros do método da seguinte forma:

   • 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éries cronológicas numa métrica baseada em registos, use o projects.timeseries.list na API Cloud Monitoring. Para ver detalhes sobre os dados de intervalos temporais, consulte o artigo Ler intervalos temporais.

   Para ler uma única métrica baseada em registos definida pelo utilizador, preencha os parâmetros do método com este tipo e identificador de métrica:

   logging.googleapis.com/user/METRIC_ID
   

   Atualize métricas baseadas em registos

   Pode editar uma métrica baseada em registos definida pelo utilizador para alterar a respetiva descrição, filtro e os nomes dos campos referenciados na métrica. Pode adicionar novas etiquetas à métrica e alterar as expressões regulares usadas para extrair valores para a métrica e as respetivas etiquetas. Se estiver a usar uma métrica com âmbito de grupo, também pode atualizar o grupo da métrica.

   Não pode alterar os nomes nem os tipos de métricas baseadas em registos definidas pelo utilizador, nem as respetivas etiquetas. Além disso, não pode eliminar etiquetas existentes numa métrica baseada em registos.

   Para editar uma métrica baseada em registos, faça o seguinte:

   Consola

   1. Na Google Cloud consola, aceda à página Métricas baseadas em registos:

      Aceda a Métricas baseadas em registos

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

   2. Clique em Editar métrica no Menu para a métrica baseada em registos que quer modificar.

   3. Altere os itens permitidos na métrica.

   4. Clique em Atualizar métrica.

   gcloud

   Use a CLI do Google Cloud para alterar a descrição, a consulta de filtro e o intervalo de uma métrica de contador. 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 alterar o grupo associado a uma métrica ao nível do grupo, os dados das métricas recolhidos antes da alteração deixam de refletir a configuração atual. Os dados de métricas recolhidos para o intervalo anterior não são removidos.

   Nota: o valor METRIC_NAME tem de corresponder a uma métrica baseada em registos existente no seu projeto ou o comando de atualização cria uma nova métrica.

   Google Cloud

   Para atualizar as métricas de distribuição ou outros campos de métricas de contador, excluindo o METRIC_NAME, crie um ficheiro que contenha a especificação revista 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 ficheiro JSON ou YAML:

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

   Para mais detalhes, use o seguinte comando:

   gcloud logging metrics update --help
   

   API

   Para editar uma métrica baseada em registos, 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
     

     Por exemplo:

     projects/my-gcp-project/metrics/my-error-metric
     

   • No corpo do pedido, inclua um objeto LogMetric que seja exatamente igual à métrica existente, exceto pelas alterações e adições que quer fazer.

   Elimine métricas baseadas em registos

   Para eliminar uma métrica baseada em registos definida pelo utilizador, faça o seguinte:

   Consola

   1. Na Google Cloud consola, aceda à página Métricas baseadas em registos:

      Aceda a Métricas baseadas em registos

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

   2. Selecione a métrica que quer eliminar e clique em Eliminar.

      Em alternativa, clique em Eliminar métrica no menu da métrica baseada em registos que quer eliminar.

   gcloud

   Use o seguinte comando para eliminar uma métrica baseada em registos definida pelo utilizador no Google Cloud projeto atual:

   gcloud logging metrics delete METRIC_NAME
   

   Para mais detalhes, use o seguinte comando:

   gcloud logging metrics delete --help
   

   API

   Para eliminar uma métrica baseada em registos definida pelo utilizador, use o método projects.metrics.delete na API.

   Além disso, na página Métrica baseada em registos da Google Cloud consola, o painel Métricas definidas pelo utilizador da interface de métricas baseadas em registos oferece mais funcionalidades para ajudar a gerir as métricas definidas pelo utilizador no seuGoogle Cloud projeto. Consulte a secção Métricas definidas pelo utilizador para ver mais detalhes.