Configure métricas de distribuição

Esta página explica como criar métricas baseadas em registos do tipo de distribuição através da Google Cloud consola, da API Logging e da CLI Google Cloud. Para uma vista geral das métricas baseadas em registos, aceda ao artigo Vista geral das métricas baseadas em registos.

Vista geral

As métricas de distribuição requerem um filtro para selecionar as entradas de registo relevantes e um extrator de valores para obter o valor numérico da distribuição. O extrator de valores é do mesmo tipo que o usado para etiquetas definidas pelo utilizador.

Uma métrica de distribuição regista a distribuição estatística dos valores extraídos em contentores de histogramas. Os valores extraídos não são registados individualmente, mas a respetiva distribuição nos intervalos configurados é registada, juntamente com a contagem, a média e a soma do desvio quadrático dos valores. Pode usar o esquema predefinido dos segmentos do histograma na sua distribuição ou ajustar os limites dos segmentos para captar aproximadamente os valores.

Para mais informações sobre como ver e interpretar as métricas de distribuição, consulte o artigo Métricas de distribuição.

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 de distribuição

   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 baseada em registos 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 Distribuição.

   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: (opcional) para métricas de distribuição, pode, opcionalmente, introduzir unidades, como s e ms. Para mais informações, consulte o campo unit do MetricDescriptor.

   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 selecionar 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. Nome do campo: introduza o campo de entrada do registo que contém o valor da distribuição. São-lhe oferecidas opções à medida que escreve. Por exemplo:

         protoPayload.latency
         

      4. Expressão regular: (opcional) se o Nome do campo contiver sempre um valor numérico convertível no tipo double, pode deixar este campo vazio. Caso contrário, especifique uma expressão regular que extraia o valor de distribuição numérico do valor do campo.

         Exemplo. Suponha que o campo latency de entrada de registo contém um número seguido de ms para milissegundos. A expressão regular seguinte escolhe o número sem o sufixo da unidade:

         ([0-9.]+)
         

         Os parênteses, conhecidos como um grupo de captura de regex, identificam a parte da correspondência de texto que vai ser extraída. Consulte o artigo sobre a utilização de expressões regulares para ver detalhes.

      • Avançadas (intervalos do histograma): (opcional) se clicar em Avançadas, é aberta uma secção do formulário que pode usar para especificar esquemas de intervalos personalizados. Se não especificar os esquemas de contentores, é fornecido um esquema de contentores predefinido. Para mais informações, consulte Intervalos do histograma nesta página.
      1. 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 ver instruções sobre como criar etiquetas, consulte o artigo Crie uma etiqueta.

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

   gcloud

   Para criar uma métrica baseada em registos do tipo de distribuição, crie um ficheiro que contenha uma representação da sua definição de LogMetric no formato JSON ou YAML. Em seguida, use o seguinte comando para ler a configuração do seu ficheiro:

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

   Para ver informações sobre a descrição dos contentores do histograma para uma distribuição, consulte Contentores do histograma.

   API

   Para criar uma métrica de distribuição, 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 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.",
              }
            ]
        },
      }
      

   Notas:

   • Aplicam-se algumas restrições de nomenclatura. Consulte a secção Resolução de problemas para ver detalhes.

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

   Intervalos de histograma

   As métricas de distribuição incluem um histograma que contabiliza o número de valores que se enquadram em intervalos especificados (grupos). Pode ter até 200 intervalos numa métrica de distribuição.

   Cada segmento tem dois valores limite, L e H, que definem os valores mais baixos e mais altos abrangidos pelo segmento. A largura do balde é H - L. Uma vez que não pode haver lacunas entre os intervalos, o limite inferior de um intervalo é igual ao limite superior do intervalo anterior e assim sucessivamente. Para que os limites não se enquadrem em mais do que um grupo, um grupo inclui o seu limite inferior. O limite superior pertence ao grupo seguinte.

   Todos os esquemas de intervalos podem ser especificados através da enumeração, por ordem crescente, dos valores limite entre intervalos individuais. O primeiro grupo é o grupo de overflow inferior, que contabiliza os valores inferiores ao primeiro limite. O último recipiente é o recipiente de overflow, que contabiliza valores superiores ou iguais ao último limite. Os outros intervalos contam valores superiores ou iguais ao respetivo limite inferior e inferiores ao respetivo limite superior. Se existirem n valores limite, existem n+1 grupos. Excluindo os intervalos de valores inferiores e superiores, existem n-1 intervalos finitos.

   Existem três formas diferentes de especificar os limites entre os contentores do histograma para métricas de distribuição. Especifica uma fórmula para os valores limite ou indica os valores limite:

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

   • Exponencial(escala, fator_crescimento, i): as larguras dos intervalos aumentam para valores mais elevados. Os limites são scale * growth_factorⁱ, para i=0,1,2,...,N. Para mais informações sobre os intervalos exponenciais, consulte a referência da API.

   • Explícito: lista todos os limites para os contentores na matriz bounds. O intervalo i tem os seguintes limites:

     Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
     Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)
     

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

   A forma como especifica os intervalos do histograma é explicada na secção seguinte:

   Consola

   O submenu Intervalos do histograma é aberto quando cria uma métrica de distribuição e clica em Mais no formulário Editor de métricas. O subformulário seguinte destina-se ao esquema de agrupamento Linear:

   

   Intervalos lineares: preencha o formulário de intervalos do histograma da seguinte forma.

   • Tipo: Linear
   • Valor inicial (a): o limite inferior do primeiro intervalo finito. Este valor é denominado desvio na API.
   • Número de contentores (N): o número de contentores finitos. O valor tem de ser igual ou superior a 0.
   • Largura do intervalo (b): a diferença entre o limite superior e o limite inferior em cada intervalo finito. O valor tem de ser superior a 0.

   Por exemplo, se o valor de início for 5, o número de contentores for 4 e a largura do contentor for 15, os intervalos dos contentores são os seguintes:

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

   Intervalos explícitos: Preencha o formulário de intervalos do histograma da seguinte forma:

   • Tipo: Explícito
   • Limites (b): uma lista separada por vírgulas dos valores de limite dos intervalos finitos. Isto também determina o número de intervalos e as respetivas larguras.

   Por exemplo, se a lista de limites for:

   0, 1, 2, 5, 10, 20
   

   Existem cinco intervalos finitos com os seguintes intervalos:

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

   Intervalos exponenciais: Preencha o formulário de intervalos do histograma da seguinte forma:

   • Tipo: Exponencial

   • Número de intervalos (N): o número total de intervalos finitos. O valor tem de ser superior a 0.

   • Escala linear (a): a escala linear dos intervalos. O valor tem de ser superior a 0.

   • Fator de crescimento exponencial (b): o fator de crescimento exponencial para os intervalos. O valor tem de ser superior a 1.

   Por exemplo, se N=4, a=3 e b=2, os intervalos dos grupos são os seguintes:

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

   Para mais informações acerca dos contentores, consulte BucketOptions na API Cloud Monitoring.

   API

   O esquema de contentor opcional é especificado pelo campo bucketOptions no objeto LogMetric fornecido a projects.metrics.create. Para ver o objeto LogMetric completo, consulte Crie uma métrica de distribuição nesta página. As adições para esquemas de contentores são as seguintes:

   Contentores lineares:

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

   O exemplo anterior cria os seguintes contentores:

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

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

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

   O exemplo anterior cria os seguintes contentores:

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

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

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

   O exemplo anterior cria os seguintes contentores:

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

   Latência da nova métrica

   A nova métrica é apresentada imediatamente na lista de métricas e nos menus de monitorização relevantes. No entanto, a métrica pode demorar até 1 minuto a começar a recolher dados para as entradas do registo correspondentes.

   Inspecione as métricas de distribuição

   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 as métricas de distribuição

   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 as métricas de distribuição

   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.