Se usó la API de Cloud Translation para traducir esta página.
Switch to English

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.

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 ...},
    ]
  }

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

Crea condiciones para 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 uses. De lo contrario, las crearás como cualquier otra política de alertas.

La consulta MQL que se usa en una condición de alerta debe tener una forma estricta. Puedes escribir la consulta de forma estricta manualmente, pero es más fácil usar el Editor de consultas y hacer clic en Agregar como si se guardara la condición. La consulta de formato estricto se proporciona para su confirmación. Puedes copiar esa versión de la consulta para usarla con la API. Luego, haz clic en Cancelar para abandonar la condición en la IU.

Para obtener más información, consulta Consultas de formato estricto.

A continuación, se muestra una consulta MQL simple y no exclusiva para una condición de política de alertas que prueba el uso de CPU de Compute Engine por encima del 15 %:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| window 5m
| condition val() > 0.15 '10^2.%'

A continuación, se muestra la forma estricta de la consulta:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| align mean_aligner()
| window 5m
| condition value.utilization > .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 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 MQL.

El campo duration especifica el tiempo durante el que 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 por una duración de 10 minutos.

El campo trigger especifica cuántas series temporales deben satisfacer la condición durante el período duration. El valor predeterminado es 1. Para obtener más información, consulta Trigger.

Para la consulta de alertas de ejemplo, con una duración de 10 minutos y un recuento de activación de 1, la estructura se ve de la siguiente manera:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | align mean_aligner() | window 5m | condition value.utilization > 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 se incorpora 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 | align mean_aligner() | window 5m | condition value.utilization > 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, pasar el archivo 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 Invoca 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 retener el ID del proyecto host de tu lugar de trabajo. 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....