Para definir uma métrica personalizada, use o método de API metricDescriptors.create para criar um descritor de métrica personalizado. É possível simplesmente gravar dados de série temporal da métrica e deixar o Monitoring criar automaticamente o descritor. No entanto, é necessário saber quais informações usar em uma definição de métrica. Depois de criar um novo descritor, use a métrica com os métodos de API do descritor e os métodos de API da série temporal. Também é possível utilizar a métrica para gráficos e alertas no Monitoring.
Nomes de métricas personalizadas
Quando criar uma métrica personalizada, atribua um nome de tipo exclusivo entre as métricas personalizadas no projeto do GCP. O nome do tipo precisa começar com custom.googleapis.com/
, seguido por um nome simples ou um nome de caminho.
Com os nomes de caminho, você organiza as métricas personalizadas. No entanto, eles são tratados da mesma maneira que os nomes simples.
Consulte Regras de nomenclatura para ver mais detalhes.
Veja exemplos de dois nomes de tipos:
custom.googleapis.com/cpu_utilization
custom.googleapis.com/instance/cpu/utilization
As métricas personalizadas também têm nomes de recursos, que são exclusivos entre todos os recursos do GCP em todos os projetos. O formato do nome de recurso de uma métrica é:
projects/[PROJECT_ID]/metricDescriptors/[METRIC_TYPE]
Se os exemplos de métrica personalizada anteriores tivessem sido criados no projeto my-project-id
, os respectivos nomes de recursos seriam:
projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization
Nome ou tipo? Na Monitoring API, os campos de nome de tipo de métrica têm geralmente os marcadores type
. Já os campos de nome de recurso têm name
.
No entanto, em conversas e em algumas documentações, o nome do tipo é muitas vezes chamado de "nome da métrica".
Como definir a métrica personalizada
Para criar a métrica personalizada, forneça um objeto MetricDescriptor que especifique várias informações sobre ela. Veja a seguir as informações necessárias:
Escolha um nome de tipo para a métrica personalizada, conforme descrito na seção anterior.
Escolha um projeto em que a métrica personalizada será definida e grave os dados de série temporal dela. As métricas personalizadas da AWS precisam ser criadas no projeto do conector da AWS referente à conta dessa plataforma. O projeto escolhido também precisa ser membro do espaço de trabalho em que a métrica é monitorada. Se você precisa de métricas iguais em vários projetos, faça as mesmas definições para elas em cada projeto.
Escolha um nome de exibição e uma descrição da métrica. O nome de exibição é usado na interface de usuário do Monitoring.
Escolha o tipo de métrica e de valor e, opcionalmente, as unidades. Nem todos os tipos de valores e classes de métrica são compatíveis com as métricas personalizadas. Consulte Tipos de métricas.
Escolha os rótulos da métrica: nomes, tipos de valor e descrições.
Escolha os objetos de recursos monitorados que serão incluídos nos pontos de dados da série temporal da métrica. Pense sobre isso antes de criar o descritor de métrica. O tipo de recurso monitorado que você usa afeta quais rótulos de métrica você precisa. Por exemplo, se um objeto de instância de VM for incluído nos dados, não será necessário um rótulo de métrica para especificar a instância. Para ver mais informações, consulte Como escolher um tipo de recurso monitorado.
Navegar pelas métricas integradas e analisar os dados da série temporal delas ajudará você a fazer essas escolhas.
Como escolher um tipo de recurso monitorado
Cada um dos pontos de dados da métrica precisa incluir um objeto de recurso monitorado. Os pontos de diferentes objetos de recursos monitorados são mantidos em séries temporais distintas.
Você pode usar apenas os seguintes tipos de recursos monitorados nas métricas personalizadas:
aws_ec2_instance
: instância do Amazon EC2.dataflow_job
: job do Dataflow.gce_instance
: instância do Google Compute Engine.gke_container
: instância de contêiner do Kubernetes Engine.generic_node
: nó de computação especificado pelo usuário.generic_task
: tarefa definida pelo usuário.global
: use este recurso quando nenhum outro tipo for adequado. Na maioria dos casos de uso,generic_node
ougeneric_task
são opções melhores do queglobal
;k8s_cluster
: cluster do Kubernetes.k8s_container
: contêiner do Kubernetes.k8s_node
: nó do Kubernetes.k8s_pod
: pod do Kubernetes.
É 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. Isso tem muitas 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 da métrica personalizada e de outras dos mesmos recursos.
Recursos global
em comparação a genéricos
Os tipos de recursos generic_task
e generic_node
são úteis em situações em que não seja adequado o uso de nenhum dos recursos mais específicos.
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 em filtros de métrica para agregações e reduções.
Por outro lado, o tipo de recurso global
tem apenas os rótulos project_id
e location
. Se um projeto tiver muitas fontes de métricas, o uso do mesmo objeto de recurso global
poderá causar colisões e sobregravações dos dados das métricas.
Chamar o método create
Depois de fazer as escolhas, transmita um objeto MetricDescriptor para chamar o método metricDescriptors.create. Como alternativa, consulte Criação automática de descritores de métrica. A alteração de um descritor atual é limitada. Consulte Como modificar descritores de métrica para ver mais informações.
Geralmente, é um erro chamar metricDescriptors.create usando o mesmo nome de tipo de um descritor de métrica personalizada atual. No entanto, se todos os campos do novo objeto MetricDescriptor corresponderem aos do descritor atual, isso não será um erro, mas não terá efeito.
Como criar descritores de métrica
No exemplo a seguir, você cria uma métrica personalizada de medidor: custom.googleapis.com/stores/daily_sales
. A métrica tem um marcador de dimensão única: store_id
.
Protocolo
Para criar um descritor de métrica, use o método metricDescriptors.create. É possível executá-lo por meio do widget da API Explorer na página de referência do método. Consulte a API Explorer para ver mais informações.
Veja a seguir amostras de parâmetros de 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": "daily sales", "type": "custom.googleapis.com/stores/daily_sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
Forneça estes valores nos campos do widget usando o código do projeto no lugar de [PROJECT_ID
]:
Clique em Executar para executar o método.
Quando uma nova métrica personalizada é criada, o campo name
no MetricDescriptor
é ignorado e pode ser omitido. O método create
retorna o novo descritor de métrica com o campo name
preenchido. Neste exemplo, ele é:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Use esse nome se quiser receber o descritor de uma métrica, por exemplo.
C#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Como solucionar problemas de chamadas da API se tiver dificuldade.
Próxima etapa: veja Como gravar dados de métrica.
Como excluir métricas
Para excluir uma métrica personalizada, 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 API Explorer na página de referência do método. Consulte a API Explorer para ver mais informações.
É possível excluir somente os tipos de métricas personalizadas.
Para excluir a métrica personalizada stores/daily_sales
criada em Como criar 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 API Explorer:
nome:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
Clique em Executar.
C#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Como solucionar problemas de chamadas da API se tiver dificuldade.
Não é possível excluir os dados de série temporal da métrica personalizada. No entanto, eles expiram e são excluídos de acordo com a política de retenção de dados.
Como gravar dados de métricas
É possível gravar dados apenas para tipos de métricas personalizadas. Use o método timeSeries.create para gravar os pontos de dados. O método anexa um novo ponto de dados a uma série temporal existente, criando-a se necessário.
Para gravar pontos de dados, transmita 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:
- Cada série temporal é identificada pelos campos de
metric
eresource
do objeto TimeSeries. - Omita os campos
metricKind
evalueType
. Eles são ignorados ao gravar pontos de dados. Cada objeto TimeSeries precisa 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 saber mais sobre intervalos de tempo de tipos diferentes de métricas, consulte Tipos de métricas.
- 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 superior a 24 horas no passado nem maior que cinco minutos no futuro.
Se você quiser gravar mais de um ponto na mesma série temporal, use uma chamada separada para o método timeSeries.create de cada ponto. Não faça as chamadas mais rápido do que uma vez por minuto. Se você estiver adicionando pontos de dados a séries temporais diferentes, não haverá limitação de taxa.
Protocolo
Para gravar dados de métrica, use o método timeSeries.create. É possível executá-lo por meio do widget da API Explorer na página de referência do método. Consulte a API Explorer para ver mais informações.
Para gravar um ponto na métrica personalizada stores/daily_sales
criada em Como criar descritores de métrica, siga as seguintes instruções:
- Acesse a página de referência de timeSeries.create.
- Forneça os parâmetros abaixo ao widget da API Explorer.
- Clique em 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#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Como solucionar problemas de chamadas da API se tiver dificuldade.
Criação automática de descritores de métrica
Se você gravar dados de métrica em um tipo de métrica personalizada que ainda não existe, um novo tipo de descritor de métrica personalizada será criado automaticamente para você. 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.
Especificamente, durante uma chamada para timeSeries.create, se um objeto TimeSeries incluir um objeto Metric que determine um nome do tipo de métrica inexistente, o Stackdriver Monitoring criará um novo MetricDescriptor com os seguintes campos:
type
: o tipo é copiado do campotype
do objeto Metric.name
: o nome é criado a partir do código do projeto na chamada do método e do valor detype
no objetoMetric
;labels
: os rótulos são os que aparecem no objetoMetric
. Cada descritor de rótulo no novo descritor de métrica tem os seguintes campos:key
: a chave do rótulo no objetoMetric
valueType
:STRING
description
: não definido
metricKind
: o tipo de métrica padrão éGAUGE
. No entanto, se o parâmetrometricKind
do objeto TimeSeries for especificado, a nova métrica terá esse tipo. É possível especificar somente os tiposGAUGE
eCUMULATIVE
;valueType
: o tipo de valor é extraído do valor inserido de Point que está sendo gravado e precisa serBOOL
,INT64
,DOUBLE
ouDISTRIBUTION
. Se você especificar um tipo de valor no campovalueType
do TimeSeries, ele precisará corresponder ao tipo em Point.unit
: não definido;description
:"Auto created custom metric."
.displayName
: não definido.
Em uma única chamada de timeSeries.create, é possível incluir vários objetos TimeSeries que se refiram ao mesmo tipo de métrica personalizada inexistente. Nesse caso, os campos do novo tipo são definidos da mesma maneira. No entanto, os rótulos no novo descritor de métrica consistem na união de todos os rótulos nos objetos Metric de todas as séries temporais dessa chamada para create
.
Como modificar descritores de métrica
Também é possível usar a chamada de timeSeries.create para adicionar novos rótulos a métricas personalizadas. Para adicioná-los ao descritor de métrica personalizada, inclua os rótulos com os dados da série temporal.
O rótulo é adicionado se ele for válido e não ultrapassar o limite máximo de 10 rótulos no descritor de métrica. Depois, os dados da série temporal são gravados como se o rótulo estivesse lá desde o início.
Se você quer 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 Como excluir métricas para ver mais informações.
Não é possível renomear uma métrica.