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 una introducción a la creación de consultas con el editor de consultas, consulta Usa el editor de consultas. El editor proporciona asistencia para el autocompletado y la corrección de errores.

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 del Explorador de API en la página de referencia de timeSeries.query. Para obtener una introducción a la herramienta del 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 Invoca 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 ...},
    ]
  }

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.

Un gráfico basado en consultas

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

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 retener el ID de tu lugar de trabajo de Cloud Monitoring. 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....