Usa MQL desde la API de Monitoring

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.

Nota: El editor de código permite que los intervalos de tiempo se especifiquen de forma explícita en las consultas y de manera implícita mediante las opciones del gráfico. Si copias consultas de MQL desde el editor y usas la selección de tiempo implícita basada en gráficos, es posible que tus consultas no sean válidas si intentas proporcionarlas directamente a la API. Para obtener más información, consulta Intervalos de tiempo, gráficos y el editor de código.

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 Usa timeSeries.query.

• Para seleccionar y manipular datos de series temporales en gráficos, proporciona la consulta a una especificación TimeSeriesQuery cuando llames al método dashboards.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 a alertPolicies.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.

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.

Nota: Una política de alertas que use MQL solo puede tener la única condición basada en MQL. No se admiten las políticas con varias condiciones si una condición usa MQL.

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:

1. 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
   

2. Autentica en la CLI de Google Cloud:

   gcloud auth login
   

3. 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}
   

4. 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.

5. Para verificar que cuentas con un token de acceso, reproduce la variable TOKEN:

   echo ${TOKEN}
   ya29.GluiBj8o....