MQL über die Monitoring API verwenden

Auf dieser Seite wird beschrieben, wie Sie der Cloud Monitoring API MQL-Abfragen (Monitoring Query Language) bereitstellen.

Auf dieser Seite wird das Erstellen von MQL-Abfragen nicht behandelt. Eine Einführung in das Erstellen von Abfragen mit dem Abfrageeditor finden Sie unter Abfrageeditor verwenden. Der Editor bietet Hilfe zur Fehlerkorrektur und zur automatischen Vervollständigung.

MQL über die API verwenden

Sie können MQL-Abfragen an den folgenden Stellen in der Monitoring API bereitstellen:

Daten mit timeSeries.query abrufen

Verwenden Sie die Methode timeSeries.query, um Zeitachsendaten von der API mit einer MQL-Abfrage abzurufen.

Die Methode timeSeries.query verwendet eine minimale Struktur, die in JSON so aussieht:

{
  "query": string
}

Geben Sie für den Wert des Felds query einen String in MQL an:

{

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

Um mit der API zu experimentieren, können Sie das API Explorer-Tool auf der Referenzseite timeSeries.query verwenden. Eine Einführung in das API Explorer-Tool finden Sie unter API Explorer.

Eine weitere Möglichkeit, die API zu testen, besteht darin, die Abfrage in einer Textdatei abzulegen und dann mit curl auszuführen. Im folgenden Beispiel wird die Abfrage in der Datei query.json an die Methode timeSeries.query übergeben:

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

Weitere Informationen zur Verwendung von curl finden Sie unter curl Aufrufen.

Bei Erfolg gibt die Abfrage eine Tabelle mit der angeforderten Zeitachse zurück. Die Tabelle ist in zwei Komponenten unterteilt:

  • timeSeriesDescriptor beschreibt die Labelschlüssel, Labelwerte und Datenpunkte in der Tabelle. Sie enthält keine Daten. Sie beschreibt einfach die Daten.

  • timeSeriesData enthält die im Zeitachsendeskriptor beschriebenen Daten. Diese Daten werden als Array von Paaren dargestellt.

    • Das erste Element im Paar, labelValues, zeichnet eine Reihe von Werten für die im Zeitachsendeskriptor aufgeführten Labels auf.
    • Der zweite, pointData, ist ein eingebettetes Array von Wert/Zeitstempel-Paaren, die die mit dem angegebenen Satz von Labelwerten erfassten Daten darstellen.

Die leicht umformatierte Antwort sieht so aus:

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

Diagramme

Mit der Methode dashboards.create können Sie Dashboards und die darin enthaltenen Diagramme programmatisch erstellen.

Der einzige Unterschied zwischen dem Erstellen MQL-basierter Diagramme und dem Erstellen anderer Diagramme ist der TimeSeriesQuery-Abfragetyp, den Sie nutzen, um den Datensatz des Diagramms zu füllen.

Abfragebasiertes Diagramm

Verwenden Sie bei MQL-Abfragen die Abfrage als Wert des Stringfeldes timeSeriesQueryLanguage im Array DataSet des Diagramms.

Hier eine einfache Dashboarddefinition, die MQL enthält:

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

Dadurch wird ein Dashboard mit dem Namen "Dashboard für MQL-Diagramm (API)" in Ihrem Projekt erstellt. Das Dashboard enthält ein Diagramm mit dem Namen "Min./Max. Compute Engine-CPU-Auslastung", das zwei Zeilen zeigt: eine für den höchsten Wert und eine für den niedrigsten Wert.

Das Diagramm zeigt die Zeitachsen mit den höchsten und niedrigsten Werten.

Weitere Informationen zu dieser Beispielabfrage finden Sie unter Auswahl mit union kombinieren.

Diagramm erstellen

Sie können die JSON-Datei des Dashboards in eine Datei einfügen und die Datei dann an gcloud beta monitoring dashboards create übergeben oder sie mit curl in https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards hochladen. Weitere Beispiele finden Sie unter Dashboard erstellen. Weitere Informationen zur Verwendung von curl finden Sie unter curl aufrufen.

Allgemeine Informationen zum Erstellen von Diagrammen und Dashboards finden Sie unter Dashboards nach API verwalten. Referenzmaterial finden Sie unter Dashboards.

curl aufrufen

Jeder curl-Aufruf enthält eine Reihe von Argumenten, gefolgt von der URL einer API-Ressource. Zu den gängigen Argumenten gehören eine Google Cloud-Projekt-ID und ein Authentifizierungstoken. Diese Werte werden hier durch die Umgebungsvariablen PROJECT_ID und TOKEN dargestellt.

Möglicherweise müssen Sie auch andere Argumente angeben, um beispielsweise den Typ der HTTP-Anfrage anzugeben (z. B. -X DELETE). Die Standardanfrage ist GET. Daher wird sie in den Beispielen nicht angegeben.

Jeder curl-Aufruf hat diese allgemeine Struktur:

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

Wenn Sie curl verwenden möchten, müssen Sie Ihre Projekt-ID und einen Zugriffstoken angeben. Um Tippfehler und Fehler zu vermeiden, können Sie diese in Umgebungsvariablen einfügen, indem Sie sie auf diese Weise an curl übergeben.

So legen Sie diese Variablen fest:

  1. Erstellen Sie eine Umgebungsvariable für die ID Ihres Cloud Monitoring-Arbeitsbereichs. Mit diesen Schritten wird die Variable PROJECT_ID aufgerufen:

    PROJECT_ID=a-sample-project
    
  2. Authentifizieren Sie sich beim Cloud SDK:

    gcloud auth login
    
  3. Optional Damit Sie nicht bei jedem gcloud-Befehl Ihre Projekt-ID angeben müssen, legen Sie Ihre Projekt-ID mithilfe des Cloud SDK als Standard fest:

    gcloud config set project ${PROJECT_ID}
    
  4. Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen. Mit diesen Schritten wird die Variable TOKEN aufgerufen:

    TOKEN=`gcloud auth print-access-token`
    

    Sie müssen das Zugriffstoken regelmäßig aktualisieren. Wenn zuvor funktionierende Befehle plötzlich melden, dass Sie nicht authentifiziert sind, führen Sie diesen Befehl noch einmal aus.

  5. Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable TOKEN zurück:

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