Crear métricas definidas por el usuario (también llamadas métricas personalizadas) con la API de Cloud Monitoring te permite capturar mediciones específicas de la aplicación y crear gráficos o alertas sobre ellas, al igual que las métricas integradas de Cloud Monitoring. Al igual que las métricas integradas, cada métrica definida por el usuario combina datos, un tipo de métrica que define lo que representan los puntos y un recurso supervisado que identifica el origen de los datos.
Para instrumentar tu aplicación, te recomendamos que uses un framework de instrumentación de código abierto y neutral con respecto al proveedor, como OpenTelemetry, en lugar de las APIs o bibliotecas cliente específicas del proveedor y del producto. Para obtener información sobre estos frameworks, consulta Observabilidad para desarrolladores de aplicaciones y Elige un enfoque de instrumentación.
No puedes usar la API de Monitoring para crear métricas basadas en registros, que derivan datos de métricas de las entradas de registro. En su lugar, Cloud Logging crea las estructuras de métricas y envía los datos a Cloud Monitoring por ti. Consulta Crea métricas de contadores y Crea métricas de distribución. Las métricas definidas por el usuario son una función con cargo de Cloud Monitoring. Para obtener detalles sobre los precios, consulta las secciones de Cloud Monitoring en la página Precios de Google Cloud Observability.
Antes de comenzar
Para obtener información sobre las estructuras que subyacen a todas las métricas, consulta Métricas, series temporales y recursos.
Para usar Cloud Monitoring, debes tener un proyecto de Google Cloud con la facturación habilitada. Cuando sea necesario, haz lo siguiente:
-
En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
-
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos
(
roles/resourcemanager.projectCreator), que contiene el permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
- Asegúrate de que la API de Monitoring esté habilitada. Para obtener más información, consulta Habilita la API de Monitoring.
- Para las aplicaciones que se ejecutan fuera de Google Cloud, tu proyecto de Google Cloud debe autenticar tu aplicación con las credenciales predeterminadas de la aplicación (ADC) locales. Para obtener más información, consulta Configura ADC para un entorno local o con otro proveedor de servicios en la nube.
Crea un tipo de métrica definido por el usuario
Para crear una métrica definida por el usuario, debes definir un objeto
MetricDescriptor
que especifique información diversa sobre la métrica
o escribir datos de métricas. Cuando escribes datos de métricas,
Monitoring crea el descriptor de métrica por ti según
la estructura de los datos que proporcionas.
Para obtener información sobre cómo diseñar un descriptor de métrica, consulta
Descriptores de métricas para métricas definidas por el usuario.
Creación automática de descriptores de métricas
Si escribes datos de métricas cuando aún no existe un descriptor de métrica para esa métrica definida por el usuario, se crea un descriptor de métrica automáticamente. 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.
Cloud Monitoring crea un nuevo MetricDescriptor cuando
el objeto TimeSeries incluido en una llamada a
timeSeries.create hace referencia a un
objeto Metric que especifica un
nombre de tipo de métrica inexistente.
Cloud Monitoring usa las siguientes reglas para propagar el
MetricDescriptor:
type: El tipo se copia del campotypedel objetoMetric.name: El nombre se crea a partir del ID del proyecto en la llamada de método y el valor detypeen el objetoMetriclabels: Son las etiquetas que aparecen en el objetoMetric. Cada descriptor de etiqueta en el nuevo descriptor de métrica posee los siguientes campos:key: Es la clave de etiqueta en el objetoMetric.valueType:STRING.description: No se establece.
metricKind: El tipo de métrica se establece enGAUGE, a menos que especifiques el parámetrometricKinddel objetoTimeSeries. Cuando especificas elmetricKind, la métrica nueva tiene ese tipo. Solo puedes especificar los tiposGAUGEyCUMULATIVE.valueType: El tipo de valor se toma del valor con tipo de laPointque se escribe. El tipo de valor debe serBOOL,INT64,DOUBLEoDISTRIBUTION. Cuando especificas un tipo de valor en el campovalueTypedeTimeSeries, ese tipo debe coincidir con el tipo dePoint.unit: No se establece.description:"Auto created custom metric.".displayName: No se establece.
En una sola llamada a timeSeries.create, puedes incluir varios objetos TimeSeries que hagan referencia al mismo tipo de métrica. En ese caso,
las etiquetas del descriptor de métrica nuevo consisten en la unión de todas las etiquetas
en los objetos Metric de todas las series temporales en esta llamada a
create.
Próximo paso: Consulta Escribe métricas definidas por el usuario.
Creación manual de descriptores de métricas
Para crear un descriptor de métrica, haz lo siguiente:
Determina la estructura de tu descriptor de métrica. Para ayudarte a tomar estas decisiones, puedes explorar las métricas integradas y consultar sus datos de series temporales:
Elige un nombre de métrica para tu métrica definida por el usuario.
Elige un nombre visible y una descripción para tu métrica. El nombre visible se usa en la consola de Google Cloud .
Elige uno o más proyectos en los que definirás tu métrica definida por el usuario y escribirás sus datos de serie temporal. Cuando necesites la misma métrica en varios proyectos, crea definiciones idénticas de la métrica en cada proyecto.
Determina el tipo de métrica, el tipo de valor y, de manera opcional, las unidades. No todos los tipos de valores y categorías de métricas son compatibles con las métricas definidas por el usuario. Para obtener más información sobre estos campos, consulta Tipos de valores y clases de métricas.
Elige las etiquetas de la métrica: sus nombres, tipos de valor y descripciones.
Determina los recursos supervisados en los que se escriben los datos de la métrica. Elige una de las siguientes opciones:
aws_ec2_instance: Instancia de Amazon EC2.dataflow_job: Es el trabajo de Dataflow.gae_instance: Instancia de App Engine.gce_instance: Instancia de Compute Engine.generic_node: Es el nodo de procesamiento especificado por el usuario.generic_task: Es la tarea definida por el usuario.gke_container: Es la instancia de contenedor de GKE.global: Usa este recurso cuando no haya otro tipo de recurso adecuado. Para la mayoría de los casos de uso,generic_nodeogeneric_taskson mejores opciones queglobal.k8s_cluster: Es el clúster de Kubernetes.k8s_container: Contenedor de Kubernetes.k8s_node: Es el nodo de Kubernetes.k8s_pod: Pod de Kubernetes.
Crea un objeto
MetricDescriptory, luego, pásalo como argumento a una llamada al métodometricDescriptors.create.
Por lo general, es un error llamar a
metricDescriptors.create con el mismo nombre de tipo
que un descriptor de métrica existente. Sin embargo, si todos los campos del
objeto MetricDescriptor nuevo coinciden exactamente con los campos del
descriptor existente, no se produce un error, pero no tiene ningún efecto.
En el siguiente ejemplo, se crea una métrica de indicador.
Protocolo
Para crear un descriptor de métricas, usa el método metricDescriptors.create.
Puedes ejecutar este método con el widget del Explorador de APIs en la página de referencia del método. Consulta el Explorador de APIs para
obtener más información.
Los siguientes son los parámetros de muestra de metricDescriptors.create:
- Nombre (URL):
projects/[PROJECT_ID] Cuerpo de la solicitud: Proporciona un objeto
MetricDescriptorcomo el siguiente:{ "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." }, ], }
Proporciona estos valores a los campos del widget con el ID de tu proyecto
en lugar de [PROJECT_ID]:
Haz clic en el botón Ejecutar (Execute) para ejecutar el método.
Cuando se crea una métrica nueva, se ignora el campo name en MetricDescriptor y se puede omitir. El método create muestra el nuevo descriptor de métrica con el campo name completo, que en este ejemplo sería el siguiente:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Por ejemplo, si quieres obtener el descriptor de una métrica, usa este nombre.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
Próximo paso: Consulta Escribe métricas definidas por el usuario.
Escribe métricas definidas por el usuario
Solo puedes escribir datos en tipos de métricas para métricas definidas por el usuario. Para escribir tus datos, usa el método timeSeries.create.
Cuando la serie temporal existe, este
método agrega un dato nuevo a la serie temporal existente. Cuando la serie temporal no existe, este método la crea y agrega los datos.
Para escribir datos, pasa una lista de objetos TimeSeries a 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 valores de los campos
metricyresourceidentifican un objetoTimeSeriesespecífico. Estos campos representan el tipo de métrica de los datos y el recurso supervisado desde el que se recopilaron los datos. - Omite los campos
metricKindyvalueType. Se ignoran cuando se escriben datos. Cada objeto
TimeSeriesdebe contener solo un único objetoPoint:- El valor y el intervalo temporal del dato deben ser coherentes con la definición del tipo de métrica. Para obtener información sobre los intervalos de tiempo de los diferentes
tipos de métricas, consulta
TimeInterval. - 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 superar las 25 horas en el pasado o 5 minutos en el futuro.
- El valor y el intervalo temporal del dato deben ser coherentes con la definición del tipo de métrica. Para obtener información sobre los intervalos de tiempo de los diferentes
tipos de métricas, consulta
Para escribir más de un punto en la misma serie temporal, usa una llamada independiente al método
timeSeries.createpara cada punto. No escribas datos en una sola serie temporal con una frecuencia mayor que un punto cada 5 segundos. Cuando agregas datos a diferentes series temporales, no hay límite de frecuencia.
Protocolo
Para escribir datos de métricas, usa el método timeSeries.create.
Puedes ejecutar este método con el widget del Explorador de APIs en la página de referencia del método. Consulta el Explorador de APIs
para obtener más información.
Para escribir un punto en la métrica stores/daily_sales creada en
Creación manual de 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 Ejecutar.
Usa los siguientes parámetros de muestra:
- name:
projects/[PROJECT_ID] Cuerpo de la 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#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
Borra métricas definidas por el usuario
Para borrar una métrica definida por el usuario, borra su descriptor de métrica. No puedes borrar los datos de series temporales almacenados en tu proyecto de Google Cloud . Sin embargo, si borras el descriptor de métrica, los datos no estarán disponibles. Los datos vencen y se borran según la política de retención de datos.
No puedes borrar el descriptor de métrica de una métrica integrada.
Para borrar el descriptor de métrica, llama al
método metricDescriptors.delete.
Protocolo
Para borrar un descriptor de métricas, usa el método metricDescriptors.delete.
Puedes ejecutar este método con el widget del Explorador de APIs en la página de referencia del método. Consulta el Explorador de APIs
para obtener más información.
Para borrar la métrica stores/daily_sales creada en
Creación manual de 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 del Explorador de API:
name:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_salesHaz clic en el botón Ejecutar.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Soluciona problemas de llamadas a la API si tienes dificultades.
Modifica una métrica definida por el usuario
Para modificar una métrica definida por el usuario, debes actualizar el objeto MetricDescriptor que define la métrica.
La única modificación admitida es agregar etiquetas.
Para agregar etiquetas a una métrica definida por el usuario existente, usa el
método timeSeries.create y, luego, incluye las etiquetas nuevas
con los datos de series temporales. Las etiquetas se agregan al descriptor de métrica
cuando las etiquetas que intentas escribir son válidas y la cantidad total
de etiquetas es inferior a 30.
Luego, los datos de series temporales se escriben como si la etiqueta hubiera estado allí desde el principio.
Si deseas hacer algo más que agregar etiquetas nuevas, debes borrar y volver a crear el descriptor de métrica. En este caso, perderás todos los datos de series temporales recopilados anteriormente para el descriptor de métrica anterior. Consulta Borra métricas definidas por el usuario para obtener más información.
No puedes cambiar el nombre de una métrica.
¿Qué sigue?
- Visualiza y administra el uso de métricas
- Lista de métricas integradas
- Lista de recursos supervisados