Configurar métricas de distribuição

Esta página explica como criar métricas com base em registros do tipo de distribuição usando o console do Google Cloud, a API Logging e a Google Cloud CLI. Para uma visão geral das métricas com base em registros, acesse Visão geral das métricas com base em registros.

Visão geral

As métricas de distribuição exigem um filtro para selecionar as entradas de registro relevantes e um extrator de valor para coletar o valor numérico para a distribuição. O extrator de valor é do mesmo tipo que é usado para rótulos definidos pelo usuário.

Uma métrica de distribuição registra a distribuição estatística dos valores extraídos nos buckets do histograma. Os valores extraídos não são registrados individualmente, mas a distribuição deles nos buckets configurados é registrada, juntamente com a contagem, a média e a soma do desvio ao quadrado dos valores. É possível usar o layout padrão dos buckets de histograma em sua distribuição ou ajustar os limites dos buckets para capturar os valores de forma aproximada.

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

Antes de começar

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

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

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

      Go to project selector

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

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

      Go to project selector

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

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

Criar uma métrica de distribuição

A métrica conta as entradas de registro identificadas por um filtro que você fornece. É possível usar expressões regulares no filtro, e 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 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 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: (opcional) para métricas de distribuição, é possível inserir unidades, como s e ms. Para mais informações, consulte o campo unit do MetricDescriptor.

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

    1. Use o menu Selecionar projeto ou bucket de registro para selecionar se a métrica contabiliza as entradas de registro no seu projeto do 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. 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 tiver um valor numérico que pode ser convertido para o tipo double, deixe 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 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 conferir 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 Criar um rótulo.

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

gcloud

Para criar uma métrica baseada em registro do tipo de distribuição, crie um arquivo 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 arquivo:

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

Para saber como descrever os buckets do histograma de uma distribuição, consulte Buckets do histograma.

API

Para criar uma métrica de distribuição, 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 registro 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. Confira a seguir um exemplo de 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.

buckets do histograma

As métricas de distribuição incluem um histograma que conta o número de valores que caem em buckets especificados. Tenha até 200 buckets em uma métrica de distribuição.

Cada bucket tem dois valores limite, L e H, que definem os valores mais baixos e mais altos cobertos pelo bucket. A largura do bucket é H - L. Como não pode haver lacunas entre os buckets, o limite inferior de um bucket é o mesmo que o limite superior do bucket anterior e assim por diante. Para que os limites não caiam em mais de um bucket, o bucket inclui o limite inferior. O limite superior pertence ao próximo bucket.

Todos os layouts do bucket podem ser especificados com a listagem, em ordem crescente, dos valores de limite entre buckets individuais. O primeiro é o bucket de subfluxo, que conta valores inferiores ao primeiro limite. O último é o bucket de sobrefluxo, que conta valores maiores ou iguais ao último limite. Os outros buckets contam valores maiores ou iguais ao limite inferior e valores menores que o limite superior. Se houver n valores de limite, então haverá n+1 buckets. Excluindo os buckets de subfluxo e sobrefluxo, há n-1 buckets finitos.

Há três maneiras diferentes de especificar os limites entre os buckets de histograma para métricas de distribuição: Você especifica uma fórmula para os valores de limite ou lista os valores de limite:

  • Linear(deslocamento, largura, i): todo bucket tem a mesma largura. Os limites são deslocamento + largura * i, para i=0,1,2,...,N. Para mais informações sobre buckets lineares, consulte a referência da API.

  • Exponencial(escala, fator_de_crescimento, i): as larguras de bucket aumentam para valores maiores. Os limites são scale * growth_factori, para i=0,1,2,...,N. Para mais informações sobre buckets exponenciais, consulte a referência da API.

  • Explícito: você lista todos os limites dos buckets na matriz de limites. O bucket i tem esses limites:

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

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

Na seção a seguir, explicamos como especificar os buckets do histograma.

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 do histograma

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 precisa 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, as faixas do bucket serão as 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 no 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 mostradas abaixo:

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)

Latência da nova métrica

Sua nova métrica aparece imediatamente na lista de métricas e nos menus relevantes do Monitoring. No entanto, pode demorar até um minuto para que a métrica comece a coletar dados para as entradas de registros correspondentes.

Inspecionar métricas de distribuição

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

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

  3. Para conferir os dados em uma métrica com base em registros, clique no Menu 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 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 seu 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 da 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 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 de distribuição

É 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 no escopo do 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 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 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 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 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 qualquer um ou 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 de métrica coletados antes da mudança não vão mais refletir a configuração atual. Os dados de métrica coletados para o bucket anterior não são removidos.

Para atualizar as métricas de distribuição ou outros campos de métrica de contador, excluindo o METRIC_NAME, crie um arquivo que contenha a especificação revisada do 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 maneira:

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

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

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.

    Como alternativa, clique em Excluir métrica no 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 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 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 oferece mais recursos para ajudar você a gerenciar as métricas definidas pelo usuário no seu projeto do Google Cloud. Consulte Métricas definidas pelo usuário para mais detalhes.