Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

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 Reihe von Beispielabfragen finden Sie unter Beispiele. Die MQL-Referenz bietet eine umfassende Referenz für die Sprache.

Informationen zu MQL-basierten Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungsrichtlinien mit MQL.

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 erstellen

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.

MQL-basiertes Diagramm erstellen

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.

Bedingungen für Benachrichtigungsrichtlinien erstellen

Benachrichtigungsrichtlinien erstellen Sie mit der Methode alertPolicies.create programmatisch.

Der einzige Unterschied zwischen dem Erstellen von MQL-basierten Benachrichtigungsrichtlinien und anderen Benachrichtigungsrichtlinien ist der von Ihnen verwendete Typ von Condition. Andernfalls erstellen Sie diese Richtlinien wie alle anderen Benachrichtigungsrichtlinien.

Die in einer Benachrichtigungsbedingung verwendete MQL-Abfrage muss streng formuliert sein. Sie können die Abfrage mit strikter Formatierung manuell schreiben. Einfacher geht es aber, wenn Sie den Abfrageeditor verwenden und auf Hinzufügen klicken, als ob Sie die Bedingung speichern möchten. Die strikte Abfrage muss zur Bestätigung eingereicht werden. Sie können diese Version der Abfrage kopieren, um sie mit der API zu verwenden. Klicken Sie dann auf Abbrechen, um die Bedingung in der UI zu verwerfen.

Weitere Informationen finden Sie unter Strict-Form-Abfragen.

Das folgende Beispiel zeigt eine einfache, nicht strikte MQL-Abfrage für eine Bedingung einer Richtlinie für Benachrichtigungen, mit der getestet wird, ob die Compute Engine-CPU-Auslastung 15 % übersteigt:

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

Das folgende Beispiel zeigt die strikte Form der Abfrage:

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

Weitere Informationen zum MQL-condition-Benachrichtigungsvorgang finden Sie unter Benachrichtigungsrichtlinien mit MQL.

Benachrichtigungsrichtlinie aufbauen

Verwenden Sie zum Erstellen einer Benachrichtigungsrichtlinie, die auf einer MQL-Abfrage basiert, den Bedingungstyp AlertPolicy MonitoringQueryLanguageCondition. MonitoringQueryLanguageCondition hat die folgende Struktur:

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

Der Wert des Felds query ist ein MQL-Benachrichtigungs-Abfragestring.

Das Feld duration gibt an, wie lange bei jeder Auswertung der Abfrage ein true-Wert generiert werden muss, bevor die Benachrichtigungsrichtlinie ausgelöst wird. Weitere Informationen finden Sie unter Benachrichtigungsverhalten. Der Wert muss in Minuten und Sekunden angegeben werden. Beispiel: 600s für eine Dauer von 10 Minuten.

Das Feld trigger gibt an, wie viele Zeitachsen die Bedingung während des duration-Zeitraums erfüllen müssen. Der Standardwert ist 1. Weitere Informationen finden Sie unter Trigger.

Für die Beispiel-Benachrichtigungsabfrage mit einer Dauer von 10 Minuten und ein Triggerzähler von 1 sieht die Struktur so aus:

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

Verwenden Sie diese Struktur als Wert des Felds conditionMonitoringQueryLanguage in einer Bedingung, die wiederum in eine Struktur für Benachrichtigungsrichtlinien eingebettet ist. Weitere Informationen zu diesen Strukturen finden Sie unter AlertPolicy.

Das folgende Beispiel zeigt eine vollständige minimale Richtlinie mit einer Bedingung MonitoringQueryLanguageCondition in 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
        },
     },
   }
  ],
}

Benachrichtigungsrichtlinie erstellen

Um die Richtlinie zu erstellen, können Sie die Benachrichtigungsrichtlinien-JSON in eine Datei einfügen und dann die Datei an gcloud alpha monitoring policies create übergeben oder curl verwenden, um sie unter https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies zu posten.

Weitere Informationen zur Monitoring API für Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungsrichtlinien über API verwalten.

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

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, die die ID des Hostprojekts Ihres Arbeitsbereichs enthält. 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....