Visão geral das métricas definidas pelo usuário

As métricas definidas pelo usuário não são definidas pelo Google Cloud. Isso inclui as métricas que você pode definir e as definidas por um aplicativo de terceiros. As métricas definidas pelo usuário permitem capturar dados específicos do aplicativo ou do sistema do lado do cliente. As métricas integradas coletadas pelo Cloud Monitoring podem fornecer informações sobre latência de back-end ou uso de disco, mas não podem informar, por exemplo, quantas rotinas em segundo plano seu aplicativo gerou. Também é possível criar métricas com base no conteúdo das entradas de registro. Para informações sobre esses tipos de métricas, consulte Visão geral de métricas com base em registros.

As métricas definidas pelo usuário às vezes são chamadas de métricas personalizadas ou métricas específicas do aplicativo. Elas permitem que você ou um aplicativo de terceiros defina e colete informações que as métricas integradas do Cloud Monitoring não conseguem. Elas são coletadas usando uma API fornecida por uma biblioteca para instrumentar seu código. Em seguida, as métricas são enviadas para um aplicativo de back-end, como o Cloud Monitoring.

É possível criar métricas definidas pelo usuário usando a API Cloud Monitoring diretamente. No entanto, recomendamos que você use o OpenTelemetry. Para informações sobre como criar métricas definidas pelo usuário, consulte os seguintes documentos:

  • Em Coletar métricas e traces do OTLP, descrevemos como usar o Agente de operações e o receptor do protocolo OpenTelemetry (OTLP, na sigla em inglês) do agente para coletar métricas e traces de aplicativos instrumentados usando o OpenTelemetry e em execução no Compute Engine.

  • No Google Cloud Managed Service para Prometheus, descrevemos como coletar métricas do Prometheus usando aplicativos em execução no Google Kubernetes Engine e no Kubernetes.

  • Em Coletar métricas do Prometheus, descrevemos como usar o Agente de operações para coletar métricas do Prometheus de aplicativos em execução no Compute Engine.

  • Criar métricas definidas pelo usuário com a API descreve como criar métricas usando a API Cloud Monitoring e como adicionar dados a elas. Neste documento, mostramos como usar a API Monitoring com exemplos usando as linguagens de programação APIs Explorer, C#, Go, Java, Node.js, PHP, Python e Ruby.

  • O artigo Criar métricas personalizadas no Cloud Run mostra como usar o Coletor do OpenTelemetry como um agente de arquivo secundário nas implantações do Cloud Run.

No que diz respeito ao Cloud Monitoring, é possível usar métricas definidas pelo usuário, como as integradas. É possível criar gráficos, definir alertas, ler e monitorar os alertas. Para informações sobre como ler dados de métricas, consulte os seguintes documentos:

  • Listar tipos de métricas e recursos explica como listar e examinar os tipos de métrica definidos pelo usuário e integrados. Por exemplo, é possível usar as informações nesse documento para listar todos os descritores de métrica definidos pelo usuário no seu projeto.
  • O artigo Recuperar dados de séries temporais explica como recuperar dados de série temporal de métricas usando a API Monitoring. Por exemplo, este documento descreve como usar a API para ver o uso da CPU de instâncias de máquina virtual (VM) no seu projeto do Google Cloud.

O console do Google Cloud fornece uma página dedicada para ajudar você a visualizar o uso de métricas definidas pelo usuário. Para informações sobre o conteúdo desta página, consulte Visualizar diagnósticos e uso de métricas.

Descritores de métricas definidas pelo usuário

Cada tipo de métrica precisa ter um descritor de métrica que defina como os dados são organizados. O descritor de métrica também define os rótulos e o nome da métrica. Por exemplo, as listas de métricas mostram os descritores de todos os tipos de métricas integrados.

O Cloud Monitoring pode criar o descritor de métrica para você usando os dados de métrica gravados. Também é possível criar explicitamente o descritor e gravar os dados de métrica. Em ambos os casos, é preciso decidir como você quer organizar os dados das métricas.

Exemplo de design

Suponha que você tenha um programa executado em uma única máquina e que ele chame os programas auxiliares A e B. Você quer contar com que frequência os programas A e B são chamados. Você também quer saber quando o programa A é chamado mais de 10 vezes por minuto e quando o programa B é chamado mais de 5 vezes por minuto. Por fim, suponha que você tenha um único projeto do Google Cloud e planeja gravar os dados no recurso monitorado global.

Neste exemplo, descrevemos alguns designs diferentes que podem ser usados para as métricas definidas pelo usuário:

  • Você usa duas métricas: Metric-type-A conta as chamadas para o programa A, e Metric-type-B conta as chamadas para o programa B. Nesse caso, Metric-type-A contém uma série temporal e Metric-type-B contém uma série temporal.

    É possível criar uma única política de alertas com duas condições ou duas condições, cada uma com uma condição usando esse modo de dados. Uma política de alertas é compatível com várias condições, mas tem uma única configuração para os canais de notificação.

    Esse modelo pode ser apropriado quando você não tem interesse em semelhanças nos dados entre as atividades que estão sendo monitoradas. Neste exemplo, as atividades são a taxa de chamadas para programas A e B.

  • Você usa uma única métrica e um rótulo para armazenar um identificador do programa. Por exemplo, o rótulo pode armazenar o valor A ou B. O Monitoring cria uma série temporal para cada combinação exclusiva de rótulos. Portanto, há uma série temporal com o valor de rótulo A e outra série temporal com B.

    Assim como no modelo anterior, você pode criar uma única política de alertas ou duas políticas de alertas. No entanto, as condições da política de alertas são mais complicadas. Uma condição que gera um incidente quando a taxa de chamadas do programa A excede um limite precisa usar um filtro que inclua apenas pontos de dados com valor de rótulo A.

    Uma vantagem desse modelo é que é simples calcular proporções. Por exemplo, você pode determinar quanto do total é devido a chamadas para A.

  • Use uma única métrica para contar o número de chamadas, mas não use um rótulo para registrar qual programa foi chamado. Nesse modelo, há uma única série temporal que combina os dados dos dois programas. No entanto, não é possível criar uma política de alertas que atenda aos seus objetivos porque os dados de dois programas não podem ser separados.

Os dois primeiros designs permitem que você atenda aos seus requisitos de análise de dados. No entanto, o último design não.

Para mais informações, consulte Criar uma métrica definida pelo usuário.

Nomes de métricas definidas pelo usuário

Ao criar uma métrica definida pelo usuário, você define um identificador de string que representa o tipo de métrica. Essa string precisa ser única entre as métricas definidas pelo usuário no projeto do Google Cloud e usar um prefixo que marque a métrica como definida pelo usuário. Para o Monitoring, os prefixos permitidos são custom.googleapis.com/, workload.googleapis.com/, external.googleapis.com/user e external.googleapis.com/prometheus. O prefixo é seguido por um nome que descreve o que você está coletando. Para detalhes sobre a maneira recomendada de nomear uma métrica, consulte Convenções de nomenclatura de métrica. Veja abaixo alguns exemplos dos dois tipos de identificadores de tipos de métricas:

    custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization

No exemplo anterior, o prefixo custom.googleapis.com indica que as duas métricas são definidas pelo usuário. Ambos os exemplos são para métricas que medem a utilização da CPU. No entanto, usam modelos organizacionais diferentes. Quando você antecipar que terá um grande número de métricas definidas pelo usuário, recomendamos usar uma estrutura de nomenclatura hierárquica como a do segundo exemplo.

Todos os tipos de métricas têm identificadores globalmente exclusivos chamados nomes de recursos. A estrutura do nome de recurso de um tipo de métrica é:

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

em que METRIC_TYPE é o identificador de string do tipo de métrica. Se os exemplos de métricas anteriores forem criados no projeto my-project-id, os nomes dos recursos para essas métricas serão os seguintes:

    projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

Nome ou tipo? No descritor de métrica, o campo name armazena o nome do recurso do tipo de métrica e o campo type armazena a string METRIC_TYPE.

Tipos de recursos monitorados para métricas definidas pelo usuário

Ao gravar dados em uma série temporal, você precisa indicar qual é a origem dos dados. Para especificar a origem dos dados, escolha um tipo de recurso monitorado que represente a origem dos dados e, em seguida, use-o para descrever a origem específica. O recurso monitorado não faz parte do tipo de métrica. Em vez disso, a série temporal em que os dados são gravados inclui uma referência ao tipo de métrica e ao recurso monitorado. O tipo de métrica descreve os dados, enquanto o recurso monitorado descreve a origem dos dados.

Considere o recurso monitorado antes de criar o descritor de métrica. O tipo de recurso monitorado que você usa afeta os rótulos que você precisa incluir no descritor de métrica. Por exemplo, o recurso de VM do Compute Engine contém rótulos para o ID do projeto, o ID da instância e a zona da instância. Portanto, se você planeja gravar sua métrica em um recurso de VM do Compute Engine, os rótulos de recurso incluem o ID da instância para que você não precise de um rótulo para o ID da instância no descritor de métrica.

Cada ponto de dados da sua métrica precisa estar associado a um objeto de recurso monitorado. Os pontos de diferentes objetos de recursos monitorados são mantidos em diferentes séries temporais.

Use um dos seguintes tipos de recursos monitorados com métricas definidas pelo usuário:

É uma prática comum usar os objetos de recursos monitorados que representam os recursos físicos em que o código do aplicativo está sendo executado. Essa abordagem tem várias vantagens:

  • Você consegue melhor desempenho em comparação com o uso de um único tipo de recurso.
  • Você evita dados fora de ordem causados pela gravação de vários processos na mesma série temporal.
  • É possível agrupar os dados de métricas definidos pelo usuário com outros dados de métricas dos mesmos recursos.

global e recursos genéricos

Os tipos de recurso generic_task e generic_node são úteis em situações em que nenhum outro tipo mais específico é apropriado. O tipo generic_task é útil para definir recursos semelhantes a tarefas, como aplicativos. O tipo generic_node é útil para definir recursos semelhantes a nós, como máquinas virtuais. Os dois tipos generic_* têm vários rótulos comuns que podem ser usados para definir objetos de recursos exclusivos, facilitando o uso deles em filtros de métricas para agregações e reduções.

Por outro lado, o tipo de recurso global só tem os rótulos project_id e location. Quando você tem muitas fontes de métricas em um projeto, usar o mesmo objeto de recurso global pode causar colisões e substituições dos dados das métricas.

Métodos de API compatíveis com métricas definidas pelo usuário

A tabela a seguir mostra quais métodos da API Monitoring são compatíveis com métricas definidas pelo usuário e quais métodos aceitam métricas integradas:

Método da API Monitoring Use com
métricas definidas pelo usuário		 Usar com
métricas integradas
monitoredResourceDescriptors.get sim sim
monitoredResourceDescriptors.list sim sim
metricDescriptors.get sim sim
metricDescriptors.list sim sim
timeSeries.list sim sim
timeSeries.create sim
metricDescriptors.create sim
metricDescriptors.delete sim

Limites e latências

Para saber os limites relacionados às métricas definidas pelo usuário e à retenção de dados, consulte Cotas e limites.

Para manter os dados de métricas além do período de armazenamento, copie manualmente os dados para outro local, como o Cloud Storage ou o BigQuery.

Para informações sobre latências associadas à gravação de dados em métricas definidas pelo usuário, consulte Latência dos dados de métricas.

A seguir