Para definir una métrica personalizada, utiliza el método de API metricDescriptors.create a fin de crear un descriptor de métrica personalizada. Si bien es posible simplemente escribir datos de series temporales para tu métrica y permitir que Monitoring cree automáticamente el descriptor de métrica, debes saber qué información se incluye en una definición de métrica. Después de crear tu nuevo descriptor de métrica personalizada, puedes usar los métodos de API del descriptor de métrica y los métodos de API de series temporales. También puedes usar la métrica para generar gráficos y crear alertas en Monitoring.
Nombres de métricas personalizadas
Cuando creas una métrica personalizada, la asignas a un nombre de tipo de métrica personalizada que es única entre las métricas de tu proyecto de GCP. El nombre del tipo debe comenzar con custom.googleapis.com/
, seguido de un nombre simple o un nombre de ruta.
Los nombres de ruta pueden ayudarte a organizar tus métricas personalizadas, pero se manejan como nombres simples.
Consulta Reglas para nombres a fin de obtener más detalles.
A continuación, se incluyen ejemplos de los dos tipos de nombres de tipo:
custom.googleapis.com/cpu_utilization
custom.googleapis.com/instance/cpu/utilization
Tus métricas personalizadas también tienen nombres de recursos que son únicos entre los recursos de GCP de todos los proyectos. El formato de un nombre de recurso para una métrica es el siguiente:
projects/[PROJECT_ID]/metricDescriptors/[METRIC_TYPE]
Si los ejemplos de métricas personalizadas anteriores se crearon en el proyecto my-project-id
, entonces sus nombres de recursos serían los siguientes:
projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization
¿Nombre o tipo? En la API de Monitoring, los campos de nombre del tipo de métrica suelen estar etiquetados como type
y los campos de nombre del recurso suelen estar etiquetados como name
.
Sin embargo, en conversaciones y en algunos documentos, el nombre de tipo a menudo se denomina "nombre de métrica".
Define tu métrica personalizada
Para crear tu métrica personalizada, debes proporcionar un objeto MetricDescriptor que especifique información diversa sobre la métrica. Esta es la información que necesitarás:
Elige un nombre de tipo para la métrica personalizada, como se describe en la sección anterior.
Elige un proyecto para definir tu métrica personalizada y escribe sus datos de series temporales. Las métricas personalizadas de AWS deben crearse en el proyecto de conector de AWS para tu cuenta de AWS. El proyecto que elijas también debe ser miembro del lugar de trabajo donde se supervisa la métrica. Si necesitas la misma métrica en varios proyectos, realiza definiciones idénticas de la métrica en cada proyecto.
Elige un nombre para mostrar y una descripción de la métrica. El nombre para mostrar se utiliza en la interfaz de usuario de Monitoring.
Elige la clase, el tipo de valor y, de manera opcional, las unidades de la métrica. No todos los tipos de valores y las clases de métricas son compatibles con las métricas personalizadas. Consulta Clases de métricas.
Elige las etiquetas de la métrica: sus nombres, tipos de valor y descripciones.
Elige qué objetos de recursos supervisados incluirás con los datos de la serie temporal de tu métrica. Deberías pensar en esto antes de crear tu descriptor de métrica. El tipo de recurso supervisado que utilizas afecta a las etiquetas métricas que necesitas. Por ejemplo, si incluyes un objeto de instancia de VM con tus datos, no necesitarás una etiqueta de métrica para especificar la instancia. Para obtener más información, consulta Elige un tipo de recurso supervisado.
Para obtener más ayuda a fin de tomar estas decisiones, puedes examinar las métricas integradas y ver sus datos de series temporales.
Elige un tipo de recurso supervisado
Cada uno de los datos de tu métrica debe incluir un objeto de recurso supervisado. Los datos de diferentes objetos de recursos supervisados se mantienen en distintas series temporales.
Puedes usar solo los siguientes tipos de recursos supervisados en tus métricas personalizadas.
aws_ec2_instance
: Instancia de Amazon EC2.dataflow_job
: Trabajo de Dataflow.gce_instance
: Instancia de Google Compute Engine.gke_container
: Instancia de contenedor de Kubernetes Engine.generic_node
: Nodo de procesamiento especificado por el usuario.generic_task
: Tarea definida por el usuario.global
: Usa este recurso cuando ningún otro tipo de recurso sea adecuado. En la mayoría de los casos prácticos,generic_node
ogeneric_task
son mejores opciones queglobal
.k8s_cluster
: Clúster de Kubernetes.k8s_container
: Contenedor de Kubernetes.k8s_node
: Nodo de Kubernetes.k8s_pod
: Pod de Kubernetes.
Una práctica común es utilizar los objetos de recursos supervisados que representan los recursos físicos donde se ejecuta el código de tu aplicación. Esto tiene varias ventajas; por ejemplo, puedes hacer lo siguiente:
- Obtienes un mejor rendimiento en comparación con el uso de un solo tipo de recurso.
- Evitas los datos fuera de orden causados por múltiples procesos que escriben en la misma serie temporal.
- Tus datos de métricas personalizadas se pueden agrupar con otros datos de métricas de los mismos recursos.
Tipo de recurso global
frente a genérico
Los tipos de recurso generic_task
y generic_node
son útiles en situaciones en las cuales ninguno de los tipos de recursos específicos es apropiado.
El tipo generic_task
es útil para definir recursos similares a las tareas, como las aplicaciones. El tipo generic_node
es útil para definir recursos similares a los nodos, como máquinas virtuales.
Ambos tipos generic_*
poseen varias etiquetas comunes que puedes utilizar con el fin de definir objetos de recursos únicos, lo que facilita su uso en filtros de métricas para agregaciones y reducciones.
Por el contrario, el tipo de recurso global
solo tiene las etiquetas project_id
y location
. Si tienes muchas fuentes de métricas dentro de un proyecto, el uso del mismo objeto de recurso global
puede provocar colisiones y sobrescrituras de tus datos de métricas.
Llama al método create
Una vez que hagas tus elecciones, llama al método metricDescriptors.create mediante la transferencia del objeto MetricDescriptor. De forma alternativa, consulta Creación automática de descriptores de métricas. Puedes cambiar un descriptor existente solo de manera limitada. Consulta Modifica descriptores de métricas para obtener más información.
Por lo general, es un error llamar a metricDescriptors.create con el mismo nombre de tipo que un descriptor de métrica personalizado existente. Sin embargo, si todos los campos del nuevo objeto MetricDescriptor coinciden exactamente con los campos del descriptor existente, esto no es un error, pero no tiene efecto.
Crea descriptores de métricas
En el siguiente ejemplo, crearás una métrica personalizada de indicador: custom.googleapis.com/stores/daily_sales
. La métrica tiene una etiqueta de dimensión única: store_id
.
Protocolo
Para crear un descriptor de métrica, usa el método metricDescriptors.create. Puedes ejecutar este método mediante el uso del Explorador de API en la página de referencia del método. Consulta Explorador de API para obtener más información.
Los siguientes son los parámetros de muestra para metricDescriptors.create.
- nombre (URL):
projects/[PROJECT_ID]
cuerpo de solicitud: Brinda un objeto MetricDescriptor como el siguiente:
{ "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." }, ], }
Proporciona estos valores para los campos del widget mediante el uso del ID del proyecto en el lugar de [PROJECT_ID
]:
Haz clic en el botón Execute (Ejecutar) para accionar el método.
Cuando crees una nueva métrica personalizada, ten en cuenta que el campo name
en el MetricDescriptor
se ignora y se puede omitir. El método create
muestra el nuevo descriptor de métrica con el campo name
rellenado. En este ejemplo, sería de la siguiente manera:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Utiliza este nombre, por ejemplo, si quieres obtener un descriptor de métrica.
C#
Go
Java
Node.js
PHP
Python
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
Siguiente paso: Consulta Escribe datos de métricas.
Borra métricas
Para borrar una métrica personalizada, llama al método metricDescriptors.delete.
Protocolo
Para borrar un descriptor de métrica, usa el método metricDescriptors.delete. Puedes ejecutar este método mediante el uso del Explorador de API en la página de referencia del método. Consulta Explorador de API para obtener más información.
Solo puedes borrar tipos de métricas personalizadas
Para borrar la métrica personalizada stores/daily_sales
que se obtuvo en Crea descriptores de métricas, haz lo siguiente:
- Ve a la página de referencia de metricDescriptors.delete.
Proporciona el nombre del descriptor de métrica al widget Explorador de API:
nombre:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
Haz clic en el botón Execute (Ejecutar).
C#
Go
Java
Node.js
PHP
Python
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
No puedes borrar los datos de la serie temporal de tu métrica personalizada, pero los datos vencen y se quitan de acuerdo con la política de retención de datos.
Lee datos de métricas
Solo puedes escribir datos en tipos de métricas personalizadas. Usa el método timeSeries.create para escribir datos. El método agrega un nuevo dato a una serie temporal existente, y crea la serie temporal si es necesario.
Escribe datos mediante la transferencia de una lista de objetos TimeSeries para timeSeries.create. El tamaño máximo de la lista es 200, y cada objeto de la lista debe especificar una serie temporal diferente:
- Los campos
metric
yresource
del objeto TimeSeries identifican cada serie temporal. - Omite los campos
metricKind
yvalueType
; estos se ignoran cuando se escriben datos. Cada objeto TimeSeries debe contener un único objeto de dato:
- El valor y el intervalo temporal del dato deben ser coherentes con la definición del tipo de métrica. Si quieres obtener información sobre los intervalos temporales para las diferentes clases de métricas, consulta Clases de métricas.
- El intervalo temporal del dato debe ser posterior a cualquier dato que ya pertenezca a la serie temporal.
- La hora de finalización del intervalo no debe ser mayor que 24 horas en el pasado o que cinco minutos en el futuro.
Si quieres escribir más de un dato en la misma serie temporal, usa una llamada separada al método timeSeries.create para cada dato. No hagas las llamadas más rápido que una vez por minuto. Si estás agregando datos a diferentes series temporales, entonces no hay límite de frecuencia.
Protocolo
Para escribir datos de métricas, usa el método timeSeries.create. Puedes ejecutar este método mediante el uso del Explorador de API en la página de referencia del método. Consulta Explorador de API para obtener más información.
Para escribir un dato en la métrica personalizada stores/daily_sales
obtenida en Crea descriptores de métricas, haz lo siguiente:
- Ve a la página de referencia de timeSeries.create.
- Proporciona los parámetros a continuación para el widget Explorador de API.
- Haz clic en el botón Execute (Ejecutar).
Usa los siguientes parámetros de muestra:
- nombre:
projects/[PROJECT_ID]
cuerpo de solicitud: Incluye una lista de objetos TimeSeries. La siguiente muestra solo tiene una serie temporal en la 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
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
Creación automática de descriptores de métricas
Si escribes datos de métricas en un tipo de métrica personalizada que aún no existe, se crea automáticamente un nuevo descriptor de métrica personalizada. Sin embargo, este nuevo descriptor de métrica podría no ser exactamente lo que quieres. La creación automática de descriptores de métricas implica algunas suposiciones y predeterminaciones.
Específicamente, durante una llamada a timeSeries.create, si un objeto TimeSeries incluye un objeto Metric que especifica un nombre de tipo de métrica no existente, entonces Stackdriver Monitoring crea un nuevo MetricDescriptor con los siguientes campos:
type
: El tipo se copia desde Metric, el objeto del campotype
.name
: El nombre se crea a partir del ID del proyecto en la llamada del método y el valor deltype
en el objetoMetric
.labels
: Las etiquetas son las que aparecen en el objetoMetric
. Cada descriptor de etiqueta en el nuevo descriptor de métrica posee los campos siguientes:key
: El campo clave en el objetoMetric
.valueType
:STRING
description
: No se estableció.
metricKind
: La clase de métrica predeterminada esGAUGE
,pero si especificas el parámetrometricKind
del objeto TimeSeries, entonces la nueva métrica tiene esa clase. Solo puedes especificar las clasesGAUGE
yCUMULATIVE
.valueType
: El tipo de valor se toma del valor escrito del dato que se escribe, el cual debe serBOOL
,INT64
,DOUBLE
oDISTRIBUTION
. Si especificas un tipo de valor en el campovalueType
de TimeSeries, entonces ese tipo debe coincidir con el tipo de dato.unit
: No se estableció.description
:"Auto created custom metric."
.displayName
: No se estableció.
En una llamada timeSeries.create única, puedes incluir varios objetos TimeSeries que hagan referencia al mismo tipo de métrica personalizada no existente. En ese caso, los campos del nuevo tipo se configuran de la misma manera, excepto que las etiquetas en el nuevo descriptor de métrica consistan en la unión de todas las etiquetas de los objetos Metric, en la totalidad de las series temporales de esta llamada para create
.
Modifica descriptores de métrica
También puedes usar la llamada timeSeries.create para agregar nuevas etiquetas a las métricas personalizadas. Para agregar etiquetas a tu descriptor de métrica personalizada, puedes incluirlas con los datos de series temporales.
Si la etiqueta que intentas escribir es válida y no hace que el número de etiquetas en el descriptor de métrica exceda el límite de 10 etiquetas, la etiqueta se agrega. Los datos de la serie temporal se escriben como si la etiqueta hubiera estado allí desde el principio.
Si quieres hacer algo más que agregar nuevas etiquetas, debes quitar y volver a crear el descriptor de métrica. En este caso, perderás todos los datos de series temporales recopilados previamente para el descriptor de métrica anterior. Consulta Borra métricas para obtener más información.
No puedes renombrar una métrica.