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 obtenir des informations sur la création de requêtes à l'aide de l'éditeur de requêtes, consultez la page Utiliser l'éditeur de requêtes. L'éditeur fournit à la fois des fonctionnalités de correction des erreurs et une aide à la saisie semi-automatique.

Utiliser MQL à partir de l'API

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

  • Pour sélectionner et manipuler des données de séries temporelles à l'aide du langage MQL, appelez la méthode timeSeries.query. Pour consulter des exemples, reportez-vous à la section Utiliser timeSeries.query.

  • Pour sélectionner et manipuler des données de séries temporelles pour des graphiques, vous devez fournir la requête à une spécification TimeSeriesQuery lorsque vous appelez la méthode dashboards.create. Pour consulter un exemple, reportez-vous à la section Graphiques.

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

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

  • Le champ timeSeriesData contient les données décrites dans le descripteur de séries temporelles. 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 ...},
    ]
  }

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.

Un graphique basé sur des requêtes

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 section Combiner les sélections avec union.

Créer un graphique

Vous pouvez placer le tableau de bord JSON dans un fichier, puis le transmettre à gcloud beta monitoring dashboards create ou utiliser curl pour le publier dans https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. Pour 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.

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 et les transmettre ainsi à curl.

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

  1. Créez une variable d'environnement destinée à contenir l'ID de votre espace de travail Cloud Monitoring. 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....