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.

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

Zum Experimentieren mit der API können Sie den APIs Explorer auf der timeSeries.query-Referenzseite verwenden. Eine Einführung in APIs Explorer finden Sie unter APIs 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.

Im Folgenden finden Sie eine einfache MQL-Abfrage für eine Benachrichtigungsrichtlinienbedingung, die die CPU-Auslastung von Compute Engine über 15 % testet:

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

Weitere Informationen zu MQLcondition Benachrichtigungsvorgang, siehe Benachrichtigungsrichtlinien mit MQL aus.

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 Feldes query ist ein MQL-Benachrichtigungsabfragestring in prägnanter oder strenger Form. Die Beispiele in diesem Dokument sind kurz und prägnant. Weitere Informationen zur Verwendung von strikten Formularen finden Sie unter Strikte Formabfragen.

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 im duration-Zeitraum erfüllen müssen, und zwar als Anzahl oder Prozentsatz. 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 | group_by sliding(5m), mean(val()) | condition val() > 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 | group_by sliding(5m), mean(val()) | condition val() > 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 Ihres Scoping-Projekts eines Messwertbereichs 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....