Neste documento, descrevemos como criar métricas definidas pelo usuário dados de métricas usando a API Cloud Monitoring. As métricas definidas pelo usuário usam os mesmos elementos que o Cloud Monitoring integrado usam:
- 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 indicam onde os pontos de dados se originou.
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, crie gráficos e alertas para os dados dessas métricas.
As métricas com base em registros são uma classe de métricas definidas pelo usuário, mas não é possível usando a API Cloud Monitoring. As métricas com base em registros dados de métricas das entradas de registro, mas a API Monitoring não fornece 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. Ao criar uma métrica com base em registros, o Logging cria as estruturas descritas neste documento e envia os dados da métrica ao Cloud Monitoring para você. 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 por trás de 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. Quando necessário, faça o seguinte:
-
No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
- Verifique se a API Monitoring está ativada. Para ver detalhes, leia Como ativar a API Monitoring.
Para aplicativos executados fora do Google Cloud, os O projeto do Google Cloud precisa autenticar seu aplicativo. Normalmente, você configura a autenticação criando uma conta de serviço para o projeto e uma variável de ambiente.
Para aplicativos executados em um instância do Amazon Elastic Compute Cloud (Amazon EC2), criar a conta de serviço para a instância Projeto do conector da AWS.
Para informações sobre como criar uma conta de serviço, consulte Primeiros passos na autenticação.
Criar um tipo de métrica definido pelo usuário
Para criar uma métrica definida pelo usuário, você define uma
Objeto MetricDescriptor
que especifica várias informações sobre a métrica,
ou gravar dados de métricas. Quando você grava dados de métricas,
O Monitoring cria o descritor de métrica para você com base
na estrutura dos dados que você fornece.
Para informações sobre como criar um descritor de métrica, consulte
Descritores de métricas para métricas definidas pelo usuário.
Criação automática de descritores de métrica
Se você gravar dados de métrica quando um descritor de métrica for definida pelo usuário ainda não existir, 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 uma
Metric
que especifica um objeto inexistente
nome do tipo de métrica.
O Cloud Monitoring usa as regras a seguir para preencher
MetricDescriptor
:
type
: o tipo é copiado do objetoMetric
type
.name
: o nome é criado a partir do ID do projeto na chamada do método e do valor detype
no objetoMetric
.labels
: os rótulos que aparecem no objetoMetric
. Cada descritor de rótulo no novo descritor de métrica tem os campos abaixo:key
: a chave do rótulo no objetoMetric
.valueType
:STRING
description
: não definido
metricKind
: o tipo da métrica é definido comoGAUGE
, a menos que você especifique o parâmetrometricKind
do objetoTimeSeries
. Quando você especifica ometricKind
, a nova métrica tem esse tipo. Só é possível especificar tiposGAUGE
eCUMULATIVE
.valueType
: o tipo de valor é retirado do valor digitado doPoint
que está sendo gravado. O tipo de valor precisa serBOOL
.INT64
,DOUBLE
ouDISTRIBUTION
. Quando você especifica um tipo de valor no campovalueType
doTimeSeries
, esse tipo precisa corresponder ao tipo dePoint
.unit
: não definidodescription
:"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 nessa chamada para
create
.
Próxima etapa: consulte Gravar métricas definidas pelo usuário.
Criação manual de descritores de métrica
Para criar um descritor de métrica, faça o seguinte:
Determine a estrutura do descritor de métrica. Para obter ajuda para tornar navegue pelas métricas integradas e analisar os dados de série temporal:
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 é usada no console do Google Cloud.
Escolha um ou mais projetos para definir a métrica definida pelo usuário e gravar os dados de série temporal dele. Quando você precisar da mesma métrica em vários projetos, crie e definições da métrica em cada projeto.
Para gravar métricas definidas pelo usuário a partir de recursos gerenciados por uma conta da AWS, crie o descritor de métrica na o projeto de conector da AWS para essa conta.
Determine o tipo de métrica e de valor e, se quiser, as unidades. Nem todos os tipos de valor e de métrica têm suporte para 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.
determinar os recursos monitorados em relação aos quais os dados da métrica são escrito. Escolha uma das opções a seguir:
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 de contêiner do GKE.global
: Use este recurso quando nenhum outro tipo estiver adequados. Na maioria dos casos de uso,generic_node
ougeneric_task
são melhores do queglobal
.k8s_cluster
: cluster do Kubernetes.k8s_container
: contêiner do Kubernetes.k8s_node
: nó do Kubernetes.k8s_pod
: pod do Kubernetes.
Crie um objeto
MetricDescriptor
e o transmita como um argumento para uma chamada à funçãometricDescriptors.create
.
Geralmente, é um erro chamar
metricDescriptors.create
usando o mesmo tipo
como um descritor de métrica existente. 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ê vai criar uma métrica de medidor.
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. Acesse o 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
MetricDescriptor
como 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
na
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 obter 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 Resolver problemas de chamadas de API se você dificuldade.
Próxima etapa: consulte Gravar 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,
anexa um novo ponto de dados à série temporal existente. Quando o
não existir, esse método a cria e anexa 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
metric
eresource
identificam um objetoTimeSeries
. 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
metricKind
evalueType
. Eles são ignorados ao gravar pontos de dados. Cada objeto
TimeSeries
pode conter apenas um único objetoPoint
:- 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
timeSeries.create
para 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 dados pontos para 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 o APIs Explorer.
para mais informações.
Para gravar um ponto na métrica stores/daily_sales
criada no
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 Resolver problemas de chamadas de API se você dificuldade.
Excluir métricas definidas pelo usuário
Para excluir uma métrica definida pelo usuário, exclua o descritor de métrica. 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 o descritor de métrica, chame o método
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 o 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 Resolver problemas de chamadas de API se você dificuldade.
Modificar uma métrica definida pelo usuário
Para modificar uma métrica definida pelo usuário, você precisa atualizar o
Objeto MetricDescriptor
que define a métrica.
A única modificação aceita é adicionar rótulos.
Para adicionar rótulos a uma métrica atual definida pelo usuário, use o
timeSeries.create
e inclua o novo
os rótulos com os dados da série temporal. Os rótulos são adicionados à métrica
quando os rótulos que você tenta escrever são válidos e o número total
de rótulos é menor que 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 Exclua as métricas definidas pelo usuário para mais informações.
Não é possível renomear uma métrica.