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 semblable à celle-ci en JSON) :

{
  "query": string
}

Pour la valeur du champ query, spécifiez une chaîne dans MQL :

{

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

Pour tester l'API, vous pouvez utiliser l'outil APIs Explorer sur la page de référence de timeSeries.query. Pour en savoir plus sur 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 en savoir plus 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 en savoir plus sur cet exemple de requête, consultez la section 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 en savoir plus 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 l'article Gérer les tableaux de bord par 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 l'utilisation du processeur Compute Engine 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 en savoir plus sur l'opération d'alerte condition MQL, 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, sous forme concise ou stricte. Les exemples de ce document sont concis. Pour plus d'informations sur les formulaires stricts, 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 page Comportement des règles d'alerte. 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ée en nombre ou en 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 page sur 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 en savoir plus 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 au SDK Cloud :

    gcloud auth login
    
  3. Facultatif. Pour éviter d'avoir à spécifier votre ID de projet avec chaque commande gcloud, définissez votre ID de projet par défaut à l'aide du SDK Cloud :

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