En este documento, se explica cómo leer datos de métricas, también llamados datos de series temporales, mediante el método timeSeries.list
en la API de Monitoring.
Existen varias formas de llamar al método timeSeries.list
:
- Puedes usar las pestañas Protocolo de esta página para usar el Explorador de APIs basado en formularios.
- Puedes usar una biblioteca cliente específica de un lenguaje.
- Puedes usar el Explorador de métricas.
Otra forma de leer tus 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 esos temas, consulta Cómo recuperar datos con timeSeries.query
.
Descripción general
Cada llamada al método timeSeries.list
puede mostrar cualquier cantidad de series temporales de un único 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 separada para cada una de tus instancias de VM.
Para obtener una introducción a las métricas y las series temporales, consulta Métricas, series temporales y recursos.
Para especificar los datos de series temporales que deseas, 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 las series temporales de la métrica si especificas los recursos que producen las series temporales o los valores para ciertas etiquetas en las series temporales.
- Un intervalo de tiempo que limita la cantidad de datos que se muestran.
- De manera opcional, una especificación de cómo combinar varias series temporales para producir un resumen agregado de los datos. Para obtener más información y ejemplos, consulta Agrega datos.
Filtros de series temporales
Puedes especificar qué series temporales deseas recuperar si pasas un filtro de serie temporal al método timeSeries.list
.
A continuación, se indican los componentes de filtro comunes:
El filtro debe especificar un solo tipo de métrica. Por ejemplo:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Para recuperar métricas definidas por el usuario, cambia el prefijo metric.type en el filtro a
custom.googleapis.com
o a otro prefijo si se usa;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 correcta, aunque el objeto de la métrica real usalabels
como su clave.El filtro puede seleccionar solo aquellas series temporales que contienen un tipo de recurso supervisado específico:
resource.type = "gce_instance"
Los componentes del filtro se pueden combinar en un solo filtro de series temporales, 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 especificas valores para todas las etiquetas de métrica, el método list
mostrará una serie temporal para cada combinación de valores en las etiquetas no especificadas. El método muestra solo series temporales que tienen datos.
Intervalos
Cuando usas la API para leer datos, debes especificar el intervalo de tiempo para el que deseas recuperar datos configurando las horas de inicio y finalización.
La API recupera 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 puede ser posterior a la de finalización. Si especificas una hora de inicio que es posterior a la hora de finalización, la API muestra un error.
Si deseas recuperar solo datos con una marca de tiempo específica, establece la hora de inicio igual a la hora de finalización o, de manera equivalente, no configures la hora de inicio.
Formato de hora
Las horas de inicio y finalización deben especificarse como strings 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.
Lista de operaciones básicas
El método timeSeries.list
se puede usar para mostrar datos simples y sin procesar o para mostrar datos muy procesados. En esta sección, se ilustra cómo enumerar las series temporales disponibles y cómo obtener los valores en una serie temporal específica.
Ejemplo: Listado de series temporales disponibles
Este ejemplo muestra cómo listar solo los nombres y descripciones de las series temporales que coincide con un filtro, en lugar de mostrar todos los datos disponibles:
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel etiquetado Probar este método, ingresa lo siguiente:
-
name: Ingresa la ruta de acceso a tu proyecto.
projects/PROJECT_ID
-
filter: Especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: Ingresa la hora de finalización.
- interval.startTime: Ingresa la hora de inicio y asegúrate de que sea 20 minutos antes que la hora de finalización.
Haz clic en Mostrar parámetros estándar y, en los campos, ingresa lo siguiente:
timeSeries.metric
-
name: Ingresa la ruta de acceso a tu proyecto.
Haz clic en Ejecutar.
La salida de muestras presenta series temporales para 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 el Explorador de API.
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.
Si tienes dificultades, consulta Cómo solucionar problemas de la API de Monitoring.
Ejemplo: Obtén datos de series temporales
En este ejemplo, se muestran las mediciones de uso de CPU que se registraron durante un intervalo de 20 minutos para una instancia específica de Compute Engine. La cantidad de datos que se muestran depende de la tasa de muestreo de la métrica. Debido a que el uso de la CPU se muestrea cada minuto, los resultados de esta consulta son alrededor de 20 datos. Cuando se muestran varios datos para una serie temporal, la API muestra los datos en cada serie temporal en orden inverso; no hay anulación para este orden de puntos.
Protocolo
El ejemplo del protocolo limita aún más la salida para que los datos mostrados sean más manejables en el cuadro de respuesta:
- El valor del filtro limita las series temporales a una sola instancia de VM.
- El valor de los campos especifica solo el tiempo y el valor de las mediciones.
Estos limitan la cantidad de datos de series temporales que se muestran en el resultado.
Abre la página de referencia de
timeSeries.list
.En el panel etiquetado Probar este método, ingresa lo siguiente:
-
name: Ingresa la ruta de acceso 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: Ingresa la hora de finalización.
interval.startTime: Ingresa la hora de inicio y asegúrate de que sea 20 minutos antes que la hora de finalización.
Haz clic en Mostrar parámetros estándar y, en los campos, ingresa lo siguiente:
timeSeries.points.interval.endTime,timeSeries.points.value
-
name: Ingresa la ruta de acceso a tu proyecto.
Haz clic en Ejecutar.
La solicitud muestra 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 el Explorador de API.
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.
Si tienes dificultades, consulta Cómo solucionar problemas de la API de Monitoring.
Agrega datos
El método timeSeries.list
puede realizar agregaciones y reducciones estadísticas en los datos de series temporales que se muestran. En las siguientes secciones, se muestran dos ejemplos.
Para obtener más información, consulta Filtrado y agregación: manipula series temporales.
Ejemplo: Alineación de series temporales
En este ejemplo, se reducen las 20 mediciones de uso individuales en cada serie temporal a solo dos mediciones: El uso medio para los dos períodos de 10 minutos dentro del intervalo de 20 minutos. Los datos de cada serie temporal se alinean primero en períodos de 10 minutos y luego se promedian los valores de cada período 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 límites exactos de 10 minutos. Los datos alineados se pueden procesar aún más.
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel etiquetado Probar este método, ingresa lo siguiente:
-
name: Ingresa la ruta de acceso a tu proyecto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Ingresa
600s
. -
aggregation.perSeriesAligner: Selecciona
ALIGN_MEAN
. -
filter: Especifica el tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: Ingresa la hora de finalización.
- interval.startTime: Ingresa la hora de inicio y asegúrate de que sea 20 minutos antes que la hora de finalización.
-
Haz clic en Mostrar parámetros estándar y, en los campos, ingresa lo siguiente:
timeSeries.metric,timeSeries.points
-
name: Ingresa la ruta de acceso a tu proyecto.
Haz clic en Ejecutar.
El filtro para una sola instancia que se muestra en el ejemplo anterior se quita: Esta consulta muestra muchos menos datos, por lo que hay menos necesidad de restringirlo a una instancia de VM.
El siguiente resultado de muestra tiene una serie temporal para cada una de las tres instancias de VM. Cada serie temporal tiene dos datos, el uso medio para los períodos 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 el Explorador de API.
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.
Si tienes dificultades, consulta Cómo solucionar problemas de la API de Monitoring.
Ejemplo: Reducción a través de series temporales
En este ejemplo, se extiende el ejemplo anterior cuando combina las series temporales alineadas de las tres instancias de VM en una sola serie temporal que mide el uso promedio de todas las instancias.
Protocolo
Abre la página de referencia de
timeSeries.list
.En el panel etiquetado Probar este método, ingresa lo siguiente:
-
name: Ingresa la ruta de acceso a tu proyecto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Ingresa
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: Ingresa la hora de finalización.
- interval.startTime: Ingresa la hora de inicio y asegúrate de que sea 20 minutos antes que la hora de finalización.
-
Haz clic en Mostrar parámetros estándar y, en los campos, ingresa lo siguiente:
timeSeries.metric,timeSeries.points
-
name: Ingresa la ruta de acceso a tu proyecto.
Haz clic en Ejecutar.
El siguiente resultado de muestra tiene solo una serie temporal y dos datos. Cada punto es el promedio del uso entre las tres instancias de VM durante el período:
{
"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 el Explorador de API.
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.
Si tienes dificultades, consulta Cómo solucionar problemas de la API de Monitoring.
¿Qué sigue?
- Obtén información sobre la retención y latencia de los datos de métricas.
- Obtén información sobre Filtrado y agregación: manipula series temporales.