En este documento, se describe cómo crear métricas definidas por el usuario y cómo escribir estos datos de métricas con la API de Cloud Monitoring. Las métricas definidas por el usuario usan los mismos elementos que usan las métricas integradas de Cloud Monitoring:
- Un conjunto de datos
- Información sobre tipos de métricas, que te indica qué representan los datos
- Información de recursos supervisados, que te indica dónde se originaron los datos
Las métricas definidas por el usuario, a veces llamadas métricas personalizadas, se pueden usar de la misma manera que las métricas integradas. Es decir, puedes crear gráficos y alertas para estos datos de métricas.
Para instrumentar tu aplicación, te recomendamos que uses un framework de instrumentación con proveedor neutro y que sea de código abierto, como OpenTelemetry, en lugar de las API específicas de proveedor y producto. o bibliotecas cliente. Para obtener más información sobre la instrumentación de tu aplicación, consulta Instrumentación y observabilidad.
Antes de comenzar
Para obtener información sobre las estructuras subyacentes de 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 página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
-
Comprueba que la facturación esté habilitada en tu proyecto.
- 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, el proyecto de Google Cloud debe autenticar la aplicación. Por lo general, la autenticación se configura mediante la creación de una cuenta de servicio para el proyecto y la configuración de una variable de entorno.
Para las aplicaciones que ejecutas en una instancia de Amazon Elastic Compute Cloud (Amazon EC2), crea la cuenta de servicio para el proyecto de AWS Connector de la instancia.
Para obtener información sobre cómo crear una cuenta de servicio, consulta Comienza a usar la autenticación.
Crea un tipo de métrica definido por el usuario
Para crear una métrica definida por el usuario, define un objeto MetricDescriptor
que especifique información diversa sobre la métrica o escribe 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.
Si deseas 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 una MetricDescriptor
nueva 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 los datos de la MetricDescriptor
:
type
: El tipo se copia del campotype
del objetoMetric
.name
: El nombre se crea a partir del ID del proyecto en la llamada de método y el valor detype
en el objetoMetric
labels
: 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ámetrometricKind
del objetoTimeSeries
. Cuando especificas elmetricKind
, la métrica nueva tiene ese tipo. Solo puedes especificar las categoríasGAUGE
yCUMULATIVE
.valueType
: El tipo de valor se toma del valor escrito delPoint
que se escribe. El tipo de valor debe serBOOL
,INT64
,DOUBLE
oDISTRIBUTION
. Cuando especificas un tipo de valor en el campovalueType
deTimeSeries
, 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 en el nuevo descriptor de métrica consisten en la unión de todas las etiquetas en los objetos Metric
en todas las series temporales de esta llamada a create
.
Siguiente paso: Consulta Cómo escribir 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. Si deseas obtener ayuda para tomar estas decisiones, puedes explorar las métricas integradas y ver sus datos de series temporales:
Elige un nombre de métrica para la 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 varios proyectos en los que definirás la métrica definida por el usuario y escribe sus datos de series temporales. Cuando necesites la misma métrica en varios proyectos, realiza definiciones idénticas de la métrica en cada proyecto.
Para escribir métricas definidas por el usuario a partir de recursos administrados por una cuenta de AWS, crea el descriptor de métrica en el proyecto de conector de AWS para esa cuenta.
Determina la clase, el tipo de valor y las unidades (opcionalmente) de la métrica. No todos los tipos de valores y las 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 tipos 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 métricas. Elige una opción de la siguiente lista:
aws_ec2_instance
: Instancia de Amazon EC2dataflow_job
: Trabajo de Dataflowgae_instance
: Instancia de App Enginegce_instance
: Instancia de Compute Enginegeneric_node
: Nodo de procesamiento especificado por el usuario.generic_task
: Tarea definida por el usuariogke_container
: Instancia de contenedor de GKEglobal
: Usa este recurso cuando ningún otro tipo de recurso sea adecuado. En la mayoría de los casos de uso,generic_node
ogeneric_task
son mejores opciones queglobal
.k8s_cluster
: Clúster de Kubernetesk8s_container
: Contenedor de Kubernetesk8s_node
: Nodo de Kubernetesk8s_pod
: Pod de Kubernetes
Crea un objeto
MetricDescriptor
y, 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 nuevo objeto MetricDescriptor
coinciden exactamente con los campos del descriptor existente, esto no es un error, pero no tiene 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 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
MetricDescriptor
como 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 para los campos del widget mediante el uso del ID del 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, el campo name
en MetricDescriptor
se ignora 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"
Si, por ejemplo, quieres obtener un descriptor de métrica, usa este nombre.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Cómo solucionar problemas de llamadas a la API si tienes dificultades.
Siguiente paso: Consulta Cómo escribir métricas definidas por el usuario.
Escribir 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
metric
yresource
identifican un objetoTimeSeries
especí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
metricKind
yvalueType
. Se ignoran cuando se escriben datos. Cada objeto
TimeSeries
debe 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. Si quieres obtener información sobre los intervalos de tiempo para 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. Si quieres obtener información sobre los intervalos de tiempo para diferentes tipos de métricas, consulta
Para escribir más de un dato en la misma serie temporal, usa una llamada independiente al método
timeSeries.create
para cada punto. No escribas datos en una sola serie temporal más rápido 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 Explorador de APIs para obtener más información.
Para escribir un punto en la métrica stores/daily_sales
creada en la Creación manual de descriptores de métricas, sigue estos pasos:
- 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Cómo solucionar problemas de llamadas a la API si tienes dificultades.
Borrar 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 serán inaccesibles. Los datos caducan y se borran de acuerdo con la política de retención de datos.
No puedes borrar el descriptor de métrica de una métrica integrada.
Para borrar tu 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 Explorador de APIs para obtener más información.
Para borrar la métrica stores/daily_sales
que se creó 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_sales
Haz clic en el botón Ejecutar.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas 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. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta Cómo solucionar problemas de llamadas a la API si tienes dificultades.
Cómo modificar 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 existente definida por el usuario, 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 el número total de etiquetas es menor que 30.
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 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 previamente 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?
- Consulta el uso y diagnóstico de las métricas
- Lista de métricas integradas
- Lista de recursos supervisados