En este documento se explica cómo leer datos de métricas, también llamados datos de serie temporal, mediante el método timeSeries.list
de la API Monitoring.
Hay varias formas de llamar al método timeSeries.list
:
- Puede usar las pestañas Protocolo de esta página para usar el Explorador de APIs basado en formularios.
- Puedes usar una biblioteca de cliente específica de un lenguaje.
- Puedes usar el explorador de métricas.
Otra forma de leer los datos de métricas es enviar un comando al método timeSeries.query
, que requiere el lenguaje de consulta de Monitoring (MQL). En este documento no se describe MQL ni el método timeSeries.query
. Para obtener información sobre estos temas, consulta Recuperar datos con timeSeries.query
.
Información general
Cada llamada al método timeSeries.list
puede devolver cualquier número de series temporales de un solo tipo de métrica. Por ejemplo, si usas Compute Engine, el tipo de métrica compute.googleapis.com/instance/cpu/usage_time
tiene una serie temporal independiente para cada una de tus instancias de VM.
Para obtener una introducción a las métricas y las series temporales, consulta el artículo Métricas, series temporales y recursos.
Para especificar los datos de serie temporal que quieras, proporciona la siguiente información al método timeSeries.list
:
- Una expresión de filtro que especifica el tipo de métrica. Opcionalmente, el filtro selecciona un subconjunto de la serie temporal de la métrica especificando los recursos que producen la serie temporal o especificando valores de determinadas etiquetas de la serie temporal.
- Intervalo de tiempo que limita la cantidad de datos devueltos.
- Opcionalmente, una especificación de cómo combinar varias series temporales para generar un resumen agregado de los datos. Para obtener más información y ejemplos, consulta Agregar datos.
Filtros de series temporales
Para especificar qué serie temporal quieres obtener, debes enviar un filtro de serie temporal al método timeSeries.list
.
A continuación se enumeran los componentes de filtro habituales:
El filtro debe especificar un único tipo de métrica. Por ejemplo:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Para recuperar métricas definidas por el usuario, cambie el prefijo metric.type del filtro por
custom.googleapis.com
u otro prefijo si se ha usado.external.googleapis.com
se usa con frecuencia.El filtro puede especificar valores para las etiquetas de dimensión de la métrica. El tipo de métrica determina qué etiquetas están presentes. Por ejemplo:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
En la expresión anterior,
label
es correcto aunque el objeto de métrica real uselabels
como clave.El filtro solo puede seleccionar las series temporales que contengan un tipo de recurso monitorizado específico:
resource.type = "gce_instance"
Los componentes del filtro se pueden combinar en un solo filtro de serie temporal, como el siguiente:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
(metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
Si no especifica valores para todas las etiquetas de métricas, el método list
devuelve una serie temporal para cada combinación de valores de las etiquetas no especificadas. El método solo devuelve series temporales que tienen datos.
Intervalos de tiempo
Cuando usas la API para leer datos, especificas el intervalo de tiempo del que quieres obtener datos definiendo las horas de inicio y de finalización.
La API obtiene datos del intervalo (start, end]
, es decir, desde después de la hora de inicio hasta la hora de finalización.
La hora de inicio no debe ser posterior a la hora de finalización. Si especificas una hora de inicio posterior a la hora de finalización, la API devuelve un error.
Si solo quieres recuperar datos con una marca de tiempo específica, define la hora de inicio como la hora de finalización o, lo que es lo mismo, no definas la hora de inicio.
Formato de hora
Las horas de inicio y finalización deben especificarse como cadenas en formato RFC 3339. Por ejemplo:
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
El comando date -Iseconds
en Linux es útil para generar marcas de tiempo.
Operaciones básicas de listas
El método timeSeries.list
se puede usar para devolver datos sin procesar o para devolver datos muy procesados. En esta sección se muestra cómo enumerar las series temporales disponibles y cómo obtener los valores de una serie temporal específica.
Ejemplo: Mostrar las series temporales disponibles
En este ejemplo se muestra cómo enumerar solo los nombres y las descripciones de las series temporales que coinciden con un filtro, en lugar de devolver todos los datos disponibles:
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel Probar este método, introduce lo siguiente:
-
Nombre: introduce la ruta a tu proyecto.
projects/PROJECT_ID
-
filter: especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime introduce la hora de finalización.
- interval.startTime introduce la hora de inicio y asegúrate de que sea 20 minutos anterior a la hora de finalización.
Haga clic en Mostrar parámetros estándar y, en los campos, introduzca lo siguiente:
timeSeries.metric
-
Nombre: introduce la ruta a tu proyecto.
Haz clic en la opción para ejecutar.
En la salida de ejemplo se muestran series temporales de dos instancias de VM diferentes:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
Para ver la solicitud como un comando curl
, como una solicitud HTTP o en JavaScript, haz clic en fullscreen Pantalla completa en Explorador de APIs.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en un entorno de desarrollo local.
Si tienes dificultades, consulta Solucionar problemas de la API Monitoring.
Ejemplo: Obtener datos de series temporales
En este ejemplo se devuelven las mediciones de utilización de la CPU que se registraron durante un intervalo de 20 minutos para una instancia de Compute Engine específica. La cantidad de datos devueltos depende de la frecuencia de muestreo de la métrica. Como la utilización de la CPU se muestrea cada minuto, los resultados de esta consulta son unos 20 puntos de datos. Cuando se devuelven varios puntos de datos de una serie temporal, la API devuelve los puntos de datos de cada serie temporal en orden cronológico inverso. No se puede anular este orden.
Protocolo
El ejemplo de protocolo limita aún más la salida para que los datos devueltos sean más fáciles de gestionar en el cuadro de respuesta:
- El valor filter limita la serie temporal a una sola instancia de VM.
- El valor fields especifica solo la hora y el valor de las mediciones.
Estos ajustes limitan la cantidad de datos de series temporales que se devuelven en el resultado.
Abre la página de referencia de
timeSeries.list
.En el panel Probar este método, introduce lo siguiente:
-
Nombre: introduce la ruta a tu proyecto.
projects/PROJECT_ID
filter: especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime introduce la hora de finalización.
interval.startTime introduce la hora de inicio y asegúrate de que sea 20 minutos anterior a la hora de finalización.
Haga clic en Mostrar parámetros estándar y, en los campos, introduzca lo siguiente:
timeSeries.points.interval.endTime,timeSeries.points.value
-
Nombre: introduce la ruta a tu proyecto.
Haz clic en la opción para ejecutar.
La solicitud devuelve un resultado como el siguiente:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
Para ver la solicitud como un comando curl
, como una solicitud HTTP o en JavaScript, haz clic en fullscreen Pantalla completa en Explorador de APIs.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en un entorno de desarrollo local.
Si tienes dificultades, consulta Solucionar problemas de la API Monitoring.
Agregar datos
El método timeSeries.list
puede realizar agregaciones y reducciones estadísticas en los datos de serie temporal devueltos. En las siguientes secciones se muestran dos ejemplos.
Para obtener más información, consulta Filtrado y agregación: manipular series temporales.
Ejemplo: alinear series temporales
En este ejemplo, las 20 mediciones de utilización individuales de cada serie temporal se reducen a 2 mediciones: la utilización media de los dos periodos de 10 minutos del intervalo de 20 minutos. Los datos de cada serie temporal se alinean primero en periodos de 10 minutos y, a continuación, se calcula la media de los valores de cada periodo de 10 minutos.
La operación de alineación tiene dos ventajas: suaviza los datos y alinea los datos de todas las series temporales en intervalos de 10 minutos exactos. Los datos alineados se pueden procesar más adelante.
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel Probar este método, introduce lo siguiente:
-
Nombre: introduce la ruta a tu proyecto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod introduce
600s
. -
aggregation.perSeriesAligner selecciona
ALIGN_MEAN
. -
filter: especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime introduce la hora de finalización.
- interval.startTime introduce la hora de inicio y asegúrate de que sea 20 minutos anterior a la hora de finalización.
-
Haga clic en Mostrar parámetros estándar y, en los campos, introduzca lo siguiente:
timeSeries.metric,timeSeries.points
-
Nombre: introduce la ruta a tu proyecto.
Haz clic en la opción para ejecutar.
Se ha quitado el filtro de una sola instancia que se muestra en el ejemplo anterior. Esta consulta devuelve muchos menos datos, por lo que no es necesario restringirla a una instancia de VM.
El siguiente resultado de ejemplo tiene una serie temporal para cada una de las tres instancias de máquina virtual. Cada serie temporal tiene dos puntos de datos, la utilización media de los periodos de alineación de 10 minutos:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
Para ver la solicitud como un comando curl
, como una solicitud HTTP o en JavaScript, haz clic en fullscreen Pantalla completa en Explorador de APIs.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en un entorno de desarrollo local.
Si tienes dificultades, consulta Solucionar problemas de la API Monitoring.
Ejemplo: Reducción en series temporales
En este ejemplo se amplía el anterior combinando las series temporales alineadas de las tres instancias de VM en una sola serie temporal que mide la utilización media de todas las instancias.
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel Probar este método, introduce lo siguiente:
-
Nombre: introduce la ruta a tu proyecto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod introduce
600s
. -
aggregation.perSeriesAligner selecciona
ALIGN_MEAN
. -
aggregation.crossSeriesReducer selecciona
REDUCE_MEAN
. -
filter: especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime introduce la hora de finalización.
- interval.startTime introduce la hora de inicio y asegúrate de que sea 20 minutos anterior a la hora de finalización.
-
Haga clic en Mostrar parámetros estándar y, en los campos, introduzca lo siguiente:
timeSeries.metric,timeSeries.points
-
Nombre: introduce la ruta a tu proyecto.
Haz clic en la opción para ejecutar.
El siguiente resultado de ejemplo solo tiene una serie temporal y dos puntos de datos. Cada punto es la media de la utilización entre las tres instancias de VM durante el periodo:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
Para ver la solicitud como un comando curl
, como una solicitud HTTP o en JavaScript, haz clic en fullscreen Pantalla completa en Explorador de APIs.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en 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 el artículo Configurar la autenticación en un entorno de desarrollo local.
Si tienes dificultades, consulta Solucionar problemas de la API Monitoring.
Siguientes pasos
- Consulta información sobre la retención y la latencia de los datos de métricas.
- Consulta información sobre filtrado y agregación: manipular series temporales.