En esta página, se describe cómo proporcionar consultas del lenguaje de consulta de Monitoring (MQL) a la API de Cloud Monitoring.
En esta página, no se explica cómo crear las consultas de MQL. Para obtener un conjunto de consultas de ejemplo, visita Ejemplos. La Referencia de MQL proporciona una referencia completa para el lenguaje.
Para obtener información sobre las políticas de alertas basadas en MQL, consulta Políticas de alertas con MQL.
Usa MQL desde la API
Puedes proporcionar consultas de MQL en las siguientes ubicaciones de la API de Monitoring:
Para seleccionar y manipular los datos de series temporales mediante MQL, llama al método
timeSeries.query
. Para ver ejemplos, consulta UsatimeSeries.query
.Para seleccionar y manipular datos de series temporales en gráficos, proporciona la consulta a una especificación
TimeSeriesQuery
cuando llames al métododashboards.create
. Para ver un ejemplo, consulta Compila gráficos.Para crear condiciones basadas en MQL en las políticas de alertas, describe la condición de la política de alertas con el tipo de condición
MonitoringQueryLanguageCondition
cuando llames aalertPolicies.create
. Si deseas ver ejemplos, consulta Crea condiciones para las políticas de alertas.
Recupera datos con timeSeries.query
Para recuperar datos de series temporales de la API con una consulta de MQL, usa el método timeSeries.query
.
El método timeSeries.query
usa una estructura mínima que se ve de la siguiente manera en JSON:
{ "query": string }
Para el valor del campo query
, especifica una string en MQL, como se muestra en las siguientes consultas simples:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m" }
Si tu consulta crea una tabla de salida no alineada, debes proporcionar una duración con la operación de tabla within
cuando llames directamente a la API. Las herramientas de gráficos, como el Explorador de métricas, proporcionan una duración de consulta predeterminada. La consulta del siguiente fragmento JSON funciona en el editor de código MQL del Explorador de métricas, pero falla cuando se suministra directamente a la API:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)" }
Si se agrega una operación de tabla within
a la consulta anterior, se puede suministrar el ejemplo anterior directamente a la API:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h" }
Para experimentar con la API, puedes usar el Explorador de API en la página de referencia de timeSeries.query
.
Para obtener una introducción al Explorador de API, consulta Explorador de API.
Otra forma de probar la API es colocar la consulta en un archivo de texto y, luego, ejecutarla mediante curl
. En el siguiente ejemplo, se pasa la consulta del archivo query.json
al método timeSeries.query
:
curl -d @query.json -H "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/json" -X POST \ https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query
Para obtener más información sobre el uso de curl
, consulta Cómo invocar a curl
.
Si se realiza de forma correcta, la consulta muestra una tabla que contiene la serie temporal solicitada. La tabla se divide en dos componentes:
El
timeSeriesDescriptor
describe las claves de etiqueta, los valores de etiqueta y los datos de la tabla. No contiene datos; solo los describe.El
timeSeriesData
contiene los datos descritos en el descriptor de series temporales. Estos datos se presentan como un arreglo de pares.- El primer elemento del par,
labelValues
, registra un conjunto de valores para las etiquetas que se enumeran en el descriptor de series temporales. - El segundo,
pointData
, es un arreglo incorporado de pares de valor y marca de tiempo que representan los datos recopilados con el conjunto especificado de valores de etiquetas.
- El primer elemento del par,
La respuesta, ligeramente modificada, se verá así:
[{ "timeSeriesTable": { "timeSeriesDescriptor": { "labelDescriptors": [ { "key": "resource.project_id" }, { "key": "resource.zone" }, { "key": "resource.instance_id" }, { "key": "metric.instance_name" } ], "valueDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ], "pointDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ] }, "timeSeriesData": [ { "labelValues": [ { "stringValue": "632526624816" }, { "stringValue": "us-central1-a" }, { "stringValue": "5106847938297466291" }, { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" } ], "pointData": [ { "values": [ { "doubleValue": 0.063896992710942874 } ], "timeInterval": { "startTime": "1969-12-31T23:59:59.999999Z", "endTime": "2020-03-02T20:17:00Z" } }, { ... additional value/timestamp pairs ...} ] }, { ... additional labelValue/pointData pairs ...}, ] }
Compila gráficos
Puedes usar el método dashboards.create
para crear paneles y los gráficos que contienen de manera programática.
La única diferencia entre crear gráficos basados en MQL y otros gráficos es el tipo de consulta TimeSeriesQuery
que usas para propagar el conjunto de datos del gráfico.
Crea un gráfico basado en MQL
Para las consultas de MQL, usa la consulta como el valor del campo de string timeSeriesQueryLanguage
en el arreglo DataSet
del gráfico.
La siguiente es una definición simple del panel en la que se incluye MQL:
{ "displayName": "Dashboard for MQL chart (API)", "gridLayout": { "widgets": [ { "title": "Min/Max Compute Engine CPU utilization", "xyChart": { "dataSets": [ { "timeSeriesQuery": { "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union" }, "plotType": "LINE", } ], "timeshiftDuration": "0s", "yAxis": { "label": "y1Axis", "scale": "LINEAR" }, "chartOptions": { "mode": "COLOR" } } } ] } }
Mediante esta, se crea un panel titulado "Panel para el gráfico de MQL (API)" en tu proyecto. El panel contiene un gráfico denominado “Uso de CPU mínimo/máximo de Compute Engine”, en el que se muestran dos líneas, una para los valores más altos y otra para los más bajos.
Para obtener más información sobre esta consulta de ejemplo, consulta Combina selecciones con union
.
Crea un gráfico
Puedes colocar el JSON del panel en un archivo y, luego, pasarlo a gcloud beta monitoring dashboards create
o usar curl
para publicarlo en https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards
.
Para obtener más ejemplos, consulta Crea un panel.
Para obtener más información sobre el uso de curl
, consulta Cómo invocar a curl
.
Para obtener información general sobre la creación de gráficos y paneles, consulta Administra paneles por API. Para obtener material de referencia, consulta Dashboards
.
Crea condiciones para las políticas de alertas
Usa el método alertPolicies.create
para crear políticas de alertas de manera programática.
La única diferencia entre crear políticas de alertas basadas en MQL y otras políticas de alertas es el tipo de Condition
que usas. De lo contrario, puedes crear estas políticas como cualquier otra política de alertas.
A continuación, se muestra una consulta simple de MQL para una condición de política de alertas que prueba el uso de CPU de Compute Engine que supera el 15 por ciento:
fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'
Para obtener más información sobre la operación de alerta condition
de MQL, consulta Políticas de alertas con MQL.
Crea la política de alertas
Para crear una política de alertas basada en una consulta de MQL, usa el tipo de condición AlertPolicy
MonitoringQueryLanguageCondition
.
MonitoringQueryLanguageCondition
tiene la siguiente estructura:
{ "query": string, "duration": string, "trigger": { object (Trigger) } }
El valor del campo query
es una string de consulta de alertas de MQL en forma concisa o estricta. Los ejemplos de este documento están concisos. Para obtener más información sobre el formato estricto, consulta Consultas de formato estricto.
El campo duration
especifica el período durante el cual cada evaluación de la consulta debe generar un valor true
antes de que se active la política de alertas. Para obtener más información, consulta Comportamiento de las políticas de alertas basadas en métricas.
El valor debe ser una cantidad de minutos, expresados en segundos; por ejemplo, 600s
para una duración de 10 minutos.
El campo trigger
especifica cuántas series temporales deben satisfacer la condición durante el período duration
, expresadas como un recuento o un porcentaje. El valor predeterminado es un recuento de 1. Para obtener más información, consulta Trigger
.
Para la consulta de alerta de ejemplo, con una duración de 10 minutos y un recuento de activadores de 1, la estructura se ve de la siguiente manera:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 } }
Usa esta estructura como el valor de un campo conditionMonitoringQueryLanguage
en una condición que, a su vez, está incorporada en una estructura de política de alertas.
Para obtener más información sobre estas estructuras, consulta AlertPolicy
.
A continuación, se muestra una política mínima completa con una condición MonitoringQueryLanguageCondition
en JSON:
{ "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)", "combiner":"OR", "conditions":[ { "displayName":"MQL-based utilization condition, API", "conditionMonitoringQueryLanguage": { "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 }, }, } ], }
Crea una política de alertas
Para crear la política, puedes colocar el JSON de la política de alertas en un archivo y, luego, pasarlo a gcloud alpha monitoring policies create
o usar curl
para publicarlo en https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies
.
Si quieres obtener más información sobre la API de Monitoring para las políticas de alertas, consulta Administra las políticas de alertas con la API.
Para obtener más información sobre el uso de curl
, consulta Cómo invocar a curl
.
Invoca curl
Cada invocación curl
incluye un conjunto de argumentos, seguido de la URL de un recurso de la API. En los argumentos comunes, se incluyen un ID del proyecto de Google Cloud y un token de autenticación. Estos valores se representan aquí mediante las variables de entorno PROJECT_ID
y TOKEN
.
Es posible que también debas especificar otros argumentos, por ejemplo, el tipo de solicitud HTTP (por ejemplo, -X DELETE
). La solicitud predeterminada es GET
, por lo que los ejemplos no lo especifican.
Cada invocación curl
tiene esta estructura general:
curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
Para usar curl
, debes especificar el ID del proyecto y un token de acceso. Para reducir la escritura y los errores, puedes colocarlos en variables de entorno a fin de pasarlos a curl
de esa manera.
Para configurar estas variables, haz lo siguiente:
Crea una variable de entorno para conservar el ID de tu proyecto de permisos de un permiso de métricas. Mediante estos pasos, se llama a la variable
PROJECT_ID
:PROJECT_ID=a-sample-project
Autentica en la CLI de Google Cloud:
gcloud auth login
Opcional. Para evitar tener que especificar el ID del proyecto con cada comando
gcloud
, establece el ID del proyecto como predeterminado con gcloud CLI:gcloud config set project ${PROJECT_ID}
Crea un token de autorización y captúralo en una variable de entorno. Mediante estos pasos, se llama a la variable
TOKEN
:TOKEN=`gcloud auth print-access-token`
Deberás actualizar el token de acceso de forma periódica. Si los comandos que funcionaban de repente informan que no estás autenticado, vuelve a emitir este comando.
Para verificar que cuentas con un token de acceso, reproduce la variable
TOKEN
:echo ${TOKEN} ya29.GluiBj8o....