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 general 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:

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.

Mediante el método timeSeries.query, se toma una estructura mínima similar a la siguiente en JSON:

{
  "query": string
}

En el valor del campo query, especifica una string en MQL:

{

  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
            | within 5m"
}

Para experimentar con la API, puedes usar la herramienta 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 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.

En el gráfico, se muestran las series temporales con los valores más altos y los más bajos.

Para obtener más información sobre esta consulta de ejemplo, consulta Cómo combinar 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 curl.

Para obtener información general sobre la creación de gráficos y paneles, consulta Administra paneles mediante 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 de MQL simple para una condición de política de alertas que prueba el uso de CPU de Compute Engine que supera el 15%:

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 alerta de MQL en forma concisa o estricta. Los ejemplos de este documento tienen un formato conciso. Para obtener más información sobre formularios estrictos, 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 alertas. El valor debe ser un número de minutos, expresado 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 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 a fin de publicarlo en https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

Si deseas obtener más información sobre la API de Monitoring para las políticas de alertas, consulta Administra las políticas de alertas según la API.

Para obtener más información sobre el uso de curl, consulta Cómo invocar 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 guardar el ID del proyecto de alcance de un permiso de métricas. Mediante estos pasos, se llama a la variable PROJECT_ID:

    PROJECT_ID=a-sample-project
    
  2. Realiza la autenticación en el SDK de Cloud:

    gcloud auth login
    
  3. Opcional Para evitar tener que especificar el ID del proyecto con cada comando gcloud, configúralo como predeterminado mediante el SDK de Cloud:

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