Utiliser MQL à partir de l'API Monitoring

Cette page explique comment fournir des requêtes en langage MQL (Monitoring Query Language) à l'API Cloud Monitoring.

Cette page ne couvre pas la création de requêtes MQL. Pour consulter un ensemble d'exemples de requêtes, consultez la page Exemples. La documentation de référence sur MQL fournit des informations exhaustives sur ce langage.

Pour obtenir des informations générales sur les règles d'alerte basées sur MQL, consultez la page Règles d'alerte avec MQL.

Utiliser MQL à partir de l'API

Vous pouvez fournir des requêtes MQL aux emplacements suivants dans l'API Monitoring :

Obtenir des données avec timeSeries.query

Pour récupérer des données de séries temporelles depuis l'API à l'aide d'une requête MQL, utilisez la méthode timeSeries.query.

La méthode timeSeries.query utilise une structure minimale qui ressemble à ceci en JSON:

{
  "query": string
}

Pour la valeur du champ query, spécifiez une chaîne en MQL, comme indiqué dans les requêtes simples suivantes:

{
  "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 votre requête crée une table de sortie non alignée, vous devez indiquer une durée à l'aide de l'opération de table within lorsque vous appelez directement l'API. Les outils de création de graphiques tels que l'Explorateur de métriques fournissent une durée de requête par défaut. Dans l'extrait de code JSON suivant, la requête fonctionne dans l'éditeur de code MQL de l'Explorateur de métriques, mais échoue lorsqu'elle est fournie directement à l'API:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}

Il est possible de fournir l'exemple précédent directement à l'API en ajoutant une opération de table within à la requête précédente:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}

Pour tester l'API, vous pouvez utiliser l'outil APIs Explorer sur la page de référence de timeSeries.query. Pour obtenir une présentation de l'outil APIs Explorer, consultez la page APIs Explorer.

Une autre façon de tester l'API consiste à placer la requête dans un fichier texte, puis à exécuter la requête à l'aide de curl. L'exemple suivant transmet la requête du fichier query.json à la méthode 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

Pour plus d'informations sur l'utilisation de curl, consultez la section Appeler curl.

Si la requête aboutit, la requête affiche une table contenant les séries temporelles demandées. La table est divisée en deux composants :

  • timeSeriesDescriptor décrit les clés de libellés, les valeurs de libellés et les points de données dans la table. Il ne contient aucune donnée ; il décrit simplement les données.

  • timeSeriesData contient les données décrites dans le descripteur de série temporelle. Ces données sont présentées sous la forme d'un tableau de paires.

    • Le premier élément de la paire, labelValues, enregistre un ensemble de valeurs pour les libellés répertoriés dans le descripteur de série temporelle.
    • Le second, pointData, est un tableau intégré de paires valeur/horodatage, qui représente les données collectées avec l'ensemble spécifié de valeurs de libellés.

La réponse, légèrement remodelée, se présente comme suit :

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

Créer des graphiques

Vous pouvez utiliser la méthode dashboards.create pour programmer la création de tableaux de bord et les graphiques qu'ils contiennent.

La seule différence entre la création de graphiques basés sur MQL et d'autres graphiques est le type de requête TimeSeriesQuery utilisé pour remplir l'ensemble de données du graphique.

Créer un graphique basé sur MQL

Pour les requêtes MQL, utilisez la requête comme valeur du champ de chaîne timeSeriesQueryLanguage dans le tableau DataSet du graphique.

Voici une définition simple de tableau de bord incluant 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"
          }
        }
      }
    ]
  }
}

Ce code crée un tableau de bord intitulé "Dashboard for MQL chart (API)" (Tableau de bord pour le graphique MQL (API)) dans votre projet. Le tableau de bord contient un graphique appelé "Min/Max Compute Engine CPU Utilization" (Utilisation minimale et maximale du processeur Compute Engine) qui affiche deux lignes, une pour les valeurs les plus élevées et une pour la valeur la plus basse.

Le graphique montre les séries temporelles présentant les valeurs les plus élevées et les plus faibles.

Pour plus d'informations sur cet exemple de requête, consultez la page Combiner les sélections avec union.

Créer un graphique

Vous pouvez placer le tableau de bord JSON dans un fichier, puis transmettre ce fichier à gcloud beta monitoring dashboards create ou utiliser curl pour le publier dans https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. Pour voir plus d'exemples, consultez la section Créer un tableau de bord. Pour plus d'informations sur l'utilisation de curl, consultez la section Appeler curl.

Pour obtenir des informations générales sur la création de graphiques et de tableaux de bord, consultez la page Gérer les tableaux de bord à l'aide d'API. Pour obtenir des informations de référence, reportez-vous à la documentation de Dashboards.

Créer des conditions pour les règles d'alerte

Utilisez la méthode alertPolicies.create pour créer des règles d'alerte par programmation.

La seule différence entre la création de règles d'alerte basées sur MQL et d'autres règles d'alerte réside dans le type de Condition que vous utilisez. Sinon, vous créez ces règles comme toute autre règle d'alerte.

Voici une requête MQL simple pour une condition de règle d'alerte qui teste si l'utilisation du processeur Compute Engine est supérieure à 15 % :

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

Pour plus d'informations sur l'opération d'alerte MQL condition, consultez la page Règles d'alerte avec MQL.

Construire la règle d'alerte

Pour créer une règle d'alerte basée sur une requête MQL, utilisez le type de condition AlertPolicy MonitoringQueryLanguageCondition. MonitoringQueryLanguageCondition présente la structure suivante :

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

La valeur du champ query est une chaîne de requête d'alerte MQL au format concis ou strict. Les exemples de ce document sont présentés au format concis. Pour en savoir plus sur le format strict, consultez la section Requêtes au format strict.

Le champ duration indique la durée pendant laquelle chaque évaluation de la requête doit générer une valeur true pour que la règle d'alerte soit déclenchée. Pour en savoir plus, consultez la section Comportement des règles d'alerte basées sur les métriques. La valeur doit être un nombre de minutes, exprimé en secondes. Par exemple, 600s pour une durée de 10 minutes.

Le champ trigger indique le nombre de séries temporelles qui doivent remplir la condition pendant la période duration, exprimées sous forme de nombre ou de pourcentage. La valeur par défaut est un nombre égal à 1. Pour en savoir plus, consultez la section Trigger.

Pour l'exemple de requête d'alerte, avec une durée de 10 minutes et un déclencheur de 1, la structure se présente comme suit :

{
  "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
  }
}

Utilisez cette structure comme valeur d'un champ conditionMonitoringQueryLanguage dans une condition, qui à son tour est intégrée dans une structure de règle d'alerte. Pour en savoir plus sur ces structures, consultez la section AlertPolicy.

Vous trouverez ci-dessous une règle minimale complète comprenant une condition 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
        },
     },
   }
  ],
}

Créer une règle d'alerte

Pour créer la règle, vous pouvez placer la règle d'alerte JSON dans un fichier, puis transmettre ce fichier à gcloud alpha monitoring policies create ou utiliser curl pour le publier dans https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

Pour plus d'informations sur l'API Monitoring pour les règles d'alerte, consultez la page Gérer des règles d'alerte à l'aide d'API.

Pour plus d'informations sur l'utilisation de curl, consultez la section Appeler curl.

Appeler curl

Chaque appel curl inclut un ensemble d'arguments, suivi de l'URL d'une ressource d'API. Les arguments courants incluent un ID de projet Google Cloud et un jeton d'authentification. Ces valeurs sont représentées ici par les variables d'environnement PROJECT_ID et TOKEN.

Vous devrez peut-être également spécifier d'autres arguments pour définir des éléments tels que le type de la requête HTTP (-X DELETE, par exemple). La requête par défaut est GET. Les exemples ne la spécifient donc pas.

Chaque appel curl possède la structure générale suivante :

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Pour utiliser curl, vous devez spécifier l'ID de votre projet et un jeton d'accès. Pour réduire la saisie et les erreurs, vous pouvez les placer dans des variables d'environnement en les transmettant à curl de cette manière.

Pour définir ces variables, procédez comme suit :

  1. Créez une variable d'environnement destinée à contenir l'ID de votre projet de champ d'application de métriques. Ces étapes appellent la variable PROJECT_ID :

    PROJECT_ID=a-sample-project

  2. Authentifiez-vous sur Google Cloud CLI :

    gcloud auth login

  3. Facultatif. Pour éviter de devoir spécifier votre ID de projet dans chaque commande gcloud, définissez votre ID de projet comme ID par défaut à l'aide de gcloud CLI:

    gcloud config set project ${PROJECT_ID}

  4. Créez un jeton d'autorisation et placez-le dans une variable d'environnement. Ces étapes appellent la variable TOKEN :

    TOKEN=`gcloud auth print-access-token`

    Vous devez actualiser régulièrement le jeton d'accès. Si des commandes auparavant fonctionnelles indiquent soudainement que vous n'êtes pas authentifié, exécutez à nouveau cette commande.

  5. Pour vérifier que vous disposez bien d'un jeton d'accès, renvoyez la variable TOKEN :

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