Neste documento, descrevemos como criar métricas definidas pelo usuário e gravar esses dados de métricas usando a API Cloud Monitoring. As métricas definidas pelo usuário usam os mesmos elementos que as métricas integradas do Cloud Monitoring:
- Um conjunto de pontos de dados
- Informações sobre tipo de métrica, que dizem o que os pontos de dados representam
- Informações de recursos monitorados, que mostram onde os pontos de dados se originaram.
As métricas definidas pelo usuário, às vezes chamadas de métricas personalizadas, podem ser usadas da mesma forma que as métricas integradas. Ou seja, é possível criar gráficos e alertas para esses dados de métricas.
As métricas com base em registros são uma classe de métricas definidas pelo usuário, mas não podem ser criadas usando a API Cloud Monitoring. As métricas com base em registros derivam dados de métricas das entradas de registro, mas a API Monitoring não oferece uma maneira de especificar como extrair dados de métricas das entradas de registro. Em vez disso, use o Cloud Logging para criar métricas com base em registros. Quando você cria uma métrica com base em registros, o Logging cria as estruturas descritas neste documento e envia os dados de métrica para o Cloud Monitoring. Para informações sobre como criar métricas com base em registros, consulte os seguintes documentos:
Para instrumentar seu aplicativo, recomendamos que você use uma estrutura de instrumentação neutra de fornecedores e que seja de código aberto, como o OpenTelemetry, em vez de APIs específicas do fornecedor e do produto. ou bibliotecas de cliente. Para mais informações sobre como instrumentar seu aplicativo, consulte Instrumentação e observabilidade.
Antes de começar
Para saber mais sobre as estruturas que sustentam todas as métricas, consulte Métricas, série temporal e recursos.
Para usar o Cloud Monitoring, você precisa ter um projeto do Google Cloud com faturamento ativado. Google Cloud Quando necessário, faça o seguinte:
- 
    
    
      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 theresourcemanager.projects.createpermission. Learn how to grant roles.
 
- 
  
    Verify that billing is enabled for your Google Cloud project. 
- Verifique se a API Monitoring está ativada. Para ver detalhes, leia Como ativar a API Monitoring.
- Para aplicativos executados fora do Google Cloud, o projeto Google Cloud precisa autenticar o aplicativo usando o Application Default Credentials (ADC) local. Para mais informações, consulte Configurar o ADC para um ambiente local ou outro provedor de nuvem.
Criar um tipo de métrica definida pelo usuário
Para criar uma métrica definida pelo usuário, defina um objeto MetricDescriptor que especifique várias informações sobre a métrica ou grave dados de métricas. Quando você grava dados de métricas, o Monitoring cria o descritor de métrica com base na estrutura dos dados fornecidos.
Para informações sobre como criar um descritor de métrica, consulte
Descritores de métrica para métricas definidas pelo usuário.
Criação automática de descritores de métrica
Se você gravar dados de métricas quando ainda não houver um descritor de métrica para essa métrica definida pelo usuário, um descritor de métrica será criado automaticamente. No entanto, talvez ele não seja exatamente o que você quer. A criação automática de descritores de métrica inclui algumas suposições e padrões.
O Cloud Monitoring cria um novo MetricDescriptor quando o objeto TimeSeries incluído em uma chamada para timeSeries.create faz referência a um objeto Metric que especifica um nome do tipo de métrica inexistente.
O Cloud Monitoring usa as seguintes regras para preencher o
MetricDescriptor:
- type: o tipo é copiado do campo- typeno objeto- Metric.
- name: o nome é criado a partir do ID do projeto na chamada do método e do valor de- typeno objeto- Metric.
- labels: os rótulos que aparecem no objeto- Metric. Cada descritor de rótulo no novo descritor de métrica tem os campos abaixo:- key: a chave do rótulo no objeto- Metric.
- valueType:- STRING
- description: não definido
 
- metricKind: o tipo de métrica é definido como- GAUGE, a menos que você especifique o parâmetro- metricKinddo objeto- TimeSeries. Quando você especifica o- metricKind, a nova métrica tem esse tipo. É possível especificar apenas os tipos- GAUGEe- CUMULATIVE.
- valueType: o tipo de valor é retirado do valor digitado de- Pointque está sendo escrito. O tipo de valor precisa ser- BOOL,- INT64,- DOUBLEou- DISTRIBUTION. Quando você especifica um tipo de valor no campo- valueTypede- TimeSeries, esse tipo precisa corresponder ao tipo de- Point.
- unit: não definido
- description:- "Auto created custom metric.".
- displayName: não definido
Em uma única chamada timeSeries.create, é possível incluir vários objetos TimeSeries que se referem ao mesmo tipo de métrica inexistente. Nesse caso, os rótulos no novo descritor de métrica consistem na união de todos os rótulos nos objetos Metric em todas as série temporal nesta chamada para create.
Próxima etapa: consulte Escrever métricas definidas pelo usuário.
Criação manual de descritores de métricas
Para criar um descritor de métrica, faça o seguinte:
- Determine a estrutura do descritor de métrica. Para ajudar você a fazer essas escolhas, navegue pelas métricas integradas e analise os dados da série temporal delas: - Escolha um nome de métrica para sua métrica definida pelo usuário. 
- Escolha um nome de exibição e uma descrição para sua métrica. O nome de exibição é usado no console Google Cloud . 
- Escolha os projetos em que sua métrica definida pelo usuário será definida e grave os dados de série temporal. Quando você precisa da mesma métrica em vários projetos, faça definições idênticas dela em cada projeto. 
- Determine o tipo de métrica e de valor e, se quiser, as unidades. Nem todos os tipos de valores e métricas são compatíveis com métricas definidas pelo usuário. Para mais informações sobre esses campos, consulte Tipos de valor e tipos de métricas. 
- Escolha os rótulos da métrica: nomes, tipos de valor e descrições. 
 
- Determine os recursos monitorados em relação aos quais os dados de métricas são gravados. Escolha uma das seguintes opções: - aws_ec2_instance: Instância do Amazon EC2.
- dataflow_job: job do Dataflow.
- gae_instance: instância do App Engine.
- gce_instance: instância do Compute Engine.
- generic_node: nó de computação especificado pelo usuário.
- generic_task: Tarefa definida pelo usuário.
- gke_container: instância do contêiner do GKE.
- global: use este recurso quando nenhum outro tipo for adequado. Na maioria dos casos de uso,- generic_nodeou- generic_tasksão opções melhores do que- global.
- k8s_cluster: cluster do Kubernetes.
- k8s_container: contêiner do Kubernetes.
- k8s_node: nó do Kubernetes.
- k8s_pod: pod do Kubernetes.
 
- Crie um objeto - MetricDescriptore transmita-o como um argumento para uma chamada ao método- metricDescriptors.create.
Geralmente, é um erro chamar metricDescriptors.create usando o mesmo nome de tipo que um descritor de métrica atual. No entanto, se todos os campos do
novo objeto MetricDescriptor corresponderem exatamente aos campos do
descritor existente, não será um erro, mas não terá efeito.
No exemplo a seguir, você cria uma métrica de medição.
Protocolo
Para criar um descritor de métrica, use o método metricDescriptors.create.
É possível executá-lo por meio do widget da APIs Explorer na página de referência do método. Consulte APIs Explorer para mais informações.
Veja a seguir os parâmetros de exemplo para metricDescriptors.create:
- nome (URL): projects/[PROJECT_ID]
- Corpo da solicitação: forneça um objeto - MetricDescriptorcomo o seguinte:- { "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
Insira esses valores nos campos no widget, usando o ID do projeto no lugar de [PROJECT_ID]:
 
 
Clique em Executar para executar o método.
Ao criar uma nova métrica, o campo name em MetricDescriptor é ignorado e pode ser omitido. O método create retorna o novo descritor de métrica com o campo name preenchido, que neste exemplo seria:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Se, por exemplo, você quiser receber o descritor de uma métrica, use esse nome.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
Próxima etapa: consulte Escrever métricas definidas pelo usuário.
Gravar métricas definidas pelo usuário
Só é possível gravar dados em tipos de métricas definidas pelo usuário. Para gravar seus dados, use o método timeSeries.create.
Quando a série temporal existe, esse
método anexa um novo ponto de dados à série temporal existente. Se a
série temporal não existir, esse método a criará e anexará os dados.
Você escreve pontos de dados passando uma lista de objetos TimeSeries para timeSeries.create.
O tamanho máximo da lista é de 200, e cada objeto nela precisa especificar uma série temporal diferente:
- Os valores dos campos metriceresourceidentificam um objetoTimeSeriesespecífico. Esses campos representam o tipo de métrica dos dados e o recurso monitorado a partir do qual os dados foram coletados.
- Omita os campos metricKindevalueType. Eles são ignorados ao gravar pontos de dados.
- Cada objeto - TimeSeriespode conter apenas um único objeto- Point:- O valor do ponto e o intervalo de tempo precisam ser consistentes com a definição do tipo de métrica.  Para informações sobre intervalos de tempo de tipos diferentes de métricas, consulte TimeInterval.
- O intervalo de tempo do ponto precisa ser posterior a qualquer ponto atual na série temporal.
- O tempo de término do intervalo não pode ser maior que 25 horas no passado nem que cinco minutos no futuro.
 
- O valor do ponto e o intervalo de tempo precisam ser consistentes com a definição do tipo de métrica.  Para informações sobre intervalos de tempo de tipos diferentes de métricas, consulte 
- Para gravar mais de um ponto na mesma série temporal, use uma chamada separada para o método - timeSeries.createpara cada ponto. Não grave dados em uma única série temporal mais rapidamente do que um ponto a cada 5 segundos. Quando você adiciona pontos de dados a série temporal diferentes, não há limitação de taxa.
Protocolo
Para gravar dados de métricas, use o método timeSeries.create.
É possível executá-lo por meio do widget da APIs Explorer na página de referência do método. Consulte APIs Explorer para mais informações.
Para gravar um ponto na métrica stores/daily_sales criada na seção Criação manual de descritores de métrica:
- Acesse a página de referência de timeSeries.create.
- Forneça os parâmetros abaixo ao widget das APIs Explorer.
- Clique no botão Executar.
Use os seguintes parâmetros de amostra:
- nome: projects/[PROJECT_ID]
- corpo da solicitação: inclua uma lista de objetos - TimeSeries. A amostra a seguir tem apenas uma série temporal na lista.- { "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
Excluir métricas definidas pelo usuário
Para excluir uma métrica definida pelo usuário, exclua o descritor de métrica dela. Não é possível excluir os dados de séries temporais armazenados no seu projeto do Google Cloud . No entanto, a exclusão do descritor de métrica torna os dados inacessíveis. Os dados vão expirar e serão excluídos de acordo com a política de retenção de dados.
Não é possível excluir o descritor de métrica de uma métrica integrada.
Para excluir seu descritor de métrica, chame o método
metricDescriptors.delete.
Protocolo
Para excluir um descritor de métrica, use o método metricDescriptors.delete.
É possível executá-lo por meio do widget da APIs Explorer na página de referência do método. Consulte APIs Explorer para mais informações.
Para excluir a métrica stores/daily_sales criada em Criação manual de descritores de métrica:
- Acesse a página de referência de metricDescriptors.delete:
- Forneça o nome do descritor de métrica ao widget da APIs Explorer: - nome: - projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
- Clique no botão Executar. 
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
Modificar uma métrica definida pelo usuário
Para modificar uma métrica definida pelo usuário, atualize o objeto MetricDescriptor que a define.
A única modificação aceita é a adição de rótulos.
Para adicionar rótulos a uma métrica definida pelo usuário, use o método timeSeries.create e inclua os novos rótulos com os dados de série temporal. Os rótulos são adicionados ao descritor de métrica quando os rótulos que você tenta gravar são válidos e o número total de rótulos é inferior a 30.
Depois, os dados da série temporal são gravados como se o rótulo estivesse lá desde o início.
Se você quiser fazer mais do que adicionar novos rótulos, exclua e recrie o descritor de métrica. Nesse caso, você perde todos os dados da série temporal coletados anteriormente para o descritor de métrica antigo. Consulte Excluir métricas definidas pelo usuário para mais informações.
Não é possível renomear uma métrica.