Codeeditor für MQL verwenden

In diesem Abschnitt werden die Funktionen des Codeeditors für die Monitoring Query Language (MQL) beschrieben. Der Editor ist in der Google Cloud Console verfügbar und bietet Vorschläge, Fehlererkennung und weitere Unterstützung zum Erstellen gültiger MQL-Abfragen.

Die MQL-Sprache wird auf dieser Seite nicht behandelt. Eine Reihe von Beispielen sowie weitere Informationen zu dieser Sprache finden Sie unter Beispiele und Informationen zur MQL-Sprache. Die MQL-Referenz ist eine umfassende Referenz für die Sprache.

Auf den Code-Editor zugreifen

So greifen Sie über den Metrics Explorer auf den Codeeditor zu:

1. Wählen Sie im Navigationsbereich der Google Cloud Console Monitoring und anschließend  Metrics Explorer aus:

   Zum Metrics Explorer

2. Wählen Sie in der Symbolleiste des Bereichs „Query Builder“ die Schaltfläche mit dem Namen  MQL oder  PromQL aus.
3. Prüfen Sie, ob im Umschalter Sprache MQL ausgewählt ist. Die Ein-/Aus-Schaltfläche für die Sprache befindet sich in derselben Symbolleiste, mit der Sie die Abfrage formatieren können.

Ähnliche Schritte werden für den Zugriff auf den Code-Editor verwendet, wenn Sie ein Diagramm in einem Dashboard erstellen.

Codeeditor verwenden

Geben Sie Ihre Abfrage in das Textfeld ein und klicken Sie auf Abfrage ausführen, um den Codeeditor zu verwenden:

Automatische Vervollständigung

Während Sie Ihre Abfrage eingeben, zeigt der Editor eine Liste mit syntaxaktisch gültigen Vervollständigungen an. Sie können das Menü zur automatischen Vervollständigung manuell aufrufen. Dazu drücken Sie Control+Space und schließen es mit Escape.

Verwenden Sie die Pfeiltasten, um durch die Liste der Optionen zu gehen. Durch Drücken von Enter wird die ausgewählte Auswahl eingefügt.

Um das Präfix für alle verfügbaren Optionen einzufügen, drücken Sie Tab.

Fehlermeldungen

Fehlermeldungen werden unten im Editorfenster angezeigt.

Wenn die Abfrage Fehler enthält, die die Vorschläge zur automatischen Vervollständigung beeinträchtigen, werden während der Eingabe Fehlermeldungen angezeigt. Andernfalls werden beim Ausführen der Abfrage Fehlermeldungen angezeigt.

Code Folding

Der Editor bietet Code Colding, also die Möglichkeit, Segmente Ihrer Abfragen zu minimieren, sodass Sie sie vorübergehend in der Ansicht ausblenden können.

Der Editor zeigt faltbare Segmente Ihrer Abfrage mit Carets neben den Zeilennummern an, wie im folgenden Screenshot gezeigt:

Suchen und ersetzen

Der Editor unterstützt die Funktion „Suchen und Ersetzen“. Drücken Sie Control+F (oder Command+F für Mac), um Begriffe in Ihrer Abfrage zu finden und zu ersetzen. Der folgende Screenshot zeigt die Funktion:

Editor-Steuerelemente

Der Editor verfügt über zwei Steuerelemente, mit denen Sie festlegen können, wie er mit der Abfrage interagiert.

Standardmäßig wird Ihre Abfrage nur ausgeführt, wenn Sie auf Abfrage ausführen klicken. Sie können den Codeeditor so einrichten, dass Ihre Abfrage automatisch während der Eingabe ausgeführt wird. Diese Option ist jedoch standardmäßig deaktiviert.

Verwenden Sie die Ein-/Aus-Schaltfläche Automatisch ausführen, um die Option für die automatische Ausführung zu aktivieren. Wenn diese Option aktiviert ist, funktioniert der Editor so:

• Die Schaltfläche Abfrage ausführen wird nicht angezeigt.
• Während der Eingabe werden ständig Fehlermeldungen angezeigt.

• Befindet sich der Cursor am Ende einer Abfrage, die unvollständig, aber fehlerfrei ist, wird im Editor ein gelbes Dreieck in der Steuerleiste angezeigt. Wenn Platz vorhanden ist, wird auch der Text Unvollständige Abfrage angezeigt.

  Der Code-Editor versucht nicht, unvollständige Abfragen auszuwerten.

Außerdem gibt es eine Leiste zwischen dem Code-Editor und dem Diagrammbereich. Mit dieser Leiste können Sie die relativen Größen der beiden Regionen ändern.

Diagramme speichern

Über den Metrics Explorer

Im Code-Editor im Metrics Explorer haben Sie die Möglichkeit, das Diagramm in einem Dashboard zu speichern. So speichern Sie das Diagramm:

1. Wenn Sie die Option für die automatische Ausführung nicht aktiviert haben, klicken Sie vor dem Speichern des Diagramms auf Abfrage ausführen, um die Abfrage auszuführen. Wenn Sie die Abfrage nicht zuerst ausführen, speichert der Code-Editor die zuletzt ausgeführte Abfrage.

2. Klicken Sie auf Diagramm speichern. In einem Dialogfeld werden Sie aufgefordert, die Speicherung des Diagramms durch eine strikte Form zu ersetzen. Weitere Informationen finden Sie unter Strict-Form-Abfragen.

3. So speichern Sie das Diagramm weiter:

   1. Geben Sie dem Diagramm einen aussagekräftigen Titel.
   2. Wählen Sie das gewünschte Dashboard für das neue Diagramm aus.
   3. Klicken Sie im Dialogfeld auf Speichern.

Über ein Dashboard

So speichern Sie ein Diagramm, das Sie einem Dashboard hinzufügen:

1. Geben Sie dem Diagramm einen aussagekräftigen Titel.

2. Wenn Sie die Option für die automatische Ausführung nicht aktiviert haben, klicken Sie vor dem Speichern des Diagramms auf Abfrage ausführen, um die Abfrage auszuführen. Wenn Sie die Abfrage nicht zuerst ausführen, speichert der Code-Editor die zuletzt ausgeführte Abfrage.

3. Klicken Sie auf Speichern. In einem Dialogfeld werden Sie aufgefordert, die Speicherung des Diagramms durch eine strikte Form zu ersetzen. Weitere Informationen finden Sie unter Strict-Form-Abfragen.

4. Klicken Sie im Dialogfeld auf Speichern, um das Diagramm zu speichern und zum Dashboard zurückzukehren.

Code-Editor schließen

Wenn Sie den Codeeditor beenden möchten, ohne ein Diagramm oder eine Bedingung zu speichern, klicken Sie auf Zurück zum Abfrageauswahl-Widget. Jeglicher Abfragetext im Editor wird verworfen, Sie haben jedoch die Möglichkeit, ihn in der Zwischenablage zu speichern.

Abfragen in strenger Form anzeigen

Wenn Sie eine Abfrage mit dem Codeeditor in strenger Form anzeigen möchten, klicken Sie auf Weitere Optionen und wählen Sie Strenge Form anzeigen aus.

Weitere Informationen finden Sie unter Strict-Form-Abfragen.

Zeiträume, Diagramme und der Code-Editor

Mit Ausnahme von MQL-Abfragen, die in Bedingungen für Benachrichtigungsrichtlinien verwendet werden, müssen MQL-Abfragen im Codeeditor einen Zeitraum enthalten. Der Zeitraum gibt die Teilmenge der Daten an, die im Rahmen der Abfrage zurückgegeben werden soll. Der Zeitraum kann implizit über die Zeitraumauswahl des Diagramms oder explizit im MQL-Abfragetext ausgedrückt werden.

Standardmäßig ist die Zeitraumauswahl auf eine Stunde eingestellt.

Über die Zeitraumauswahl können Sie den Zeitraum eines Diagramms ändern. Wenn Sie beispielsweise die Daten für die vergangene Woche sehen möchten, wählen Sie Letzte 1 Woche in der Zeitraumauswahl aus. Sie können auch eine Start- und Endzeit oder eine Zeit für den Rundgang angeben.

Informationen zum Erstellen von Benachrichtigungsrichtlinien mit dem Codeeditor finden Sie unter MQL-Benachrichtigungsrichtlinien erstellen.

Diagrammeinstellungen für die Zeitauswahl verwenden

Sie können den Zeitraum für eine Abfrage über die Zeitauswahlfunktion des Diagramms festlegen. Diese Funktion ist die Standardmethode zur Festlegung des Zeitraums. Um den Zeitraum zu ändern, wählen Sie eine andere Zeitoption im Diagramm aus. Beispiel: Wenn Sie eine Woche auswählen, gibt die Abfrage die Daten von jetzt bis zu einer Woche in der Vergangenheit zurück.

Wenn Sie diesen Standardmechanismus verwenden, müssen Sie im Text Ihrer Abfrage keinen expliziten Zeitraum angeben. Der Wert im Diagramm wird implizit verwendet.

within wird für die Zeitauswahl verwendet

Sie können den Zeitraum für die Abfrage explizit in der Abfrage mit dem Vorgang within angeben. Dieser Vorgang bestimmt den Bereich der zurückgegebenen Daten. Wenn Ihre Abfrage einen within-Vorgang enthält, werden die Optionen zur Zeitauswahl im Diagramm deaktiviert und der in der Abfrage angegebene Zeitraum verwendet.

Wenn Sie einen expliziten within-Vorgang aus Ihrer Abfrage entfernen, werden die Diagrammoptionen automatisch wieder aktiviert, sodass Ihre Abfrage immer einen Zeitraum enthält.

Sie müssen die explizite Zeitauswahl verwenden, wenn Sie die API-Methode timeSeries.query für die Abfrage verwenden möchten. Weitere Informationen finden Sie unter MQL über die Monitoring API verwenden.

Zeiteinstellungen und gespeicherte Diagramme

Wenn Sie MQL verwenden, um ein Diagramm zu erstellen und das Diagramm dann in einem Dashboard zu speichern, passiert mit Ihrer Abfrage Folgendes:

1. Die Abfrage, die Sie im Editor angegeben haben, wird in eine kanonische oder strenge Form konvertiert. Die Conversion ändert nicht die Bedeutung Ihrer Abfrage, macht jedoch explizite Dinge, die in der Abfrage angenommen werden, wie vollständige Spaltennamen oder Ausrichtungsvorgänge. Weitere Informationen finden Sie unter Strict-Form-Abfragen.

2. Die Zeitraumauswahl in Ihrer Abfrage wird entfernt. Diagramme in Dashboards haben dieselbe Zeitauswahl. Änderungen an dieser Auswahl gelten für alle Diagramme im Dashboard. Daher wird die Zeitraumauswahl aus der ursprünglichen Abfrage nicht mehr benötigt.

Informationen zum Verwalten von Dashboards und zum Bearbeiten von Diagrammen finden Sie unter Benutzerdefinierte Dashboards verwalten.

Abfrage-, Ausrichtungs- und Anzeigezeiträume

MQL nutzt eine Reihe potenziell verwirrender Vorgänge, die Zeiträume angeben. Folgende Vorgänge beziehen sich auf den Bereich einer Abfrage:

• within: Gibt das Abfrage-/Ausgabefenster an. Dieser Vorgang bestimmt, wie viele Daten zurückgegeben werden. Wenn Sie beispielsweise within 1h angeben, erzeugt die Abfrage nur Punkte, deren Zeitstempel innerhalb der letzten Stunde liegen. Aus diesem Grund überschreibt dieser Vorgang die Optionen zur Zeitauswahl des Diagramms.

• Folgende Vorgänge beziehen sich auf den Ausrichtungszeitraum ihrer Ausgabetabellen. In beiden Fällen muss entweder eine ausgerichtete Tabelle als Eingabe oder eine Standardeinstellung festgelegt werden:

  • every: Gibt den Zeitraum für die ausgerichtete Tabellenausgabe an.

  • window: Gibt das Fenster für Ausrichtungsvorgänge an.

  In beiden Fällen muss ein align-Vorgang mit einem expliziten Ausrichtungsfenster bereitgestellt werden, sofern es mit dem für den window-Vorgang angegebenen Zeitraum übereinstimmt. Für die Ausrichtungsfunktion delta müssen Ausrichtungsfenster und -periode identisch sein. Wenn ein explizites Ausrichtungsfenster angegeben ist, muss der every-Vorgang, sofern angegeben, übereinstimmen. In allen Fällen muss das Ausrichtungsfenster mindestens so groß sein, wie der Ausrichtungszeitraum, oder die Eingabedaten werden ignoriert.

MQL bietet auch einen graph_period-Vorgang, der den Zeitraum für Ausgabepunkte in Diagrammen bestimmt. Dieser Vorgang ist in Abfragen nützlich, die an die API übergeben werden und deren Ausgabe über Drittanbietersoftware läuft. Die Monitoring-Diagrammsoftware ignoriert den graph_period-Vorgang in Abfragen und legt den Punktebereich entsprechend der Zeitdimension im Ausgabediagramm fest.

In Monitoring-Diagrammen wird der Diagrammzeitraum anhand des Werts der Zeitraumauswahl des Diagramms und der maximalen Anzahl von Punkten festgelegt, die ein Diagramm anzeigen kann. Beispiel: Wenn Sie eine Woche auswählen, kann der Diagrammzeitraum eine Stunde betragen. Klicken Sie für Diagramme in Dashboards auf Abfragestatistiken, um den Grafikzeitraum anzuzeigen.

Die Beziehung zwischen dem Abfrageausrichtungszeitraum und dem Diagrammzeitraum kann die Darstellung eines Diagramms ändern. Diese Beziehung wird im folgenden Abschnitt beschrieben.

Min./Max.-Band

Wenn der Ausrichtungszeitraum der Abfrage nahe am Diagrammzeitraum liegt, stellt das Diagramm jede grafische Zeitreihe durch eine einzelne Linie dar. Umfasst der Abfrageausrichtungszeitraum weniger als die Hälfte des Diagrammzeitraum des Diagramms, so zeigt das Diagramm um jede Linie einen schattierten Bereich. Diese Region, die als Min./Max.-Band bezeichnet wird, zeigt den Wertebereich, der den Mittelwert erzeugt hat.

Nehmen Sie folgende einfache MQL-Abfrage an:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

Diese Abfrage gibt die mittlere CPU-Auslastung der VMs nach Zone zurück, mit einer Ausrichtungszeit von einer Stunde.

Wenn die Zeitauswahl des Diagramms auf eine Woche festgelegt ist, beträgt der Diagrammzeitraum eine Stunde, die auf einem Chip angezeigt wird. Für die Beispielabfrage sind der Diagrammzeitraum und der Ausrichtungszeitraum gleich. Durch die Abfrage wird ein Diagramm erstellt, das in etwa so aussieht:

Wenn Sie beispielsweise den Ausrichtungszeitraum ändern, der in der vorherigen Abfrage an den Vorgang every von 1h an 1m übergeben wurde, erzeugt die Abfrage ein Diagramm mit den Min./Max.-Bändern:

Die Diagrammlinien werden basierend auf der einwöchigen Auswahl für das Diagramm mit einem Diagrammzeitraum von einer Stunde grafisch dargestellt. Die Linien entsprechen denen im vorherigen Beispiel. Aber die Abfrage erzeugt jede Minute einen Punkt, sodass die Min/Max-Bänder den Bereich der Ein-Minuten-Werte aus der Abfrage zeigen, die in jeden Ein-Stunden-Diagrammpunkt fallen.

Wenn die Operation every weggelassen wird, ist der Standardzeitraum für die Abfrageausrichtung entweder der Wert des Ausrichtungsfensters oder, falls nicht angegeben, eine Minute.

MQL-basierte Benachrichtigungsrichtlinien

Sie können auch MQL und den Codeeditor verwenden, um Abfragen zur Verwendung in Benachrichtigungsrichtlinien zu erstellen.

Zum Erstellen einer MQL-basierten Benachrichtigungsrichtlinie über die Google Cloud Console führen Sie die üblichen Schritte zum Erstellen der Richtlinie aus, die unter Benachrichtigungsrichtlinien verwalten beschrieben werden. Wenn Sie jedoch die Bedingung für die Benachrichtigungsrichtlinie erstellen, verwenden Sie den Codeeditor anstelle der formularbasierten Messwertauswahl.

Weitere Informationen finden Sie unter MQL-Benachrichtigungsrichtlinien erstellen.

Abfrage-Conversion

Sie können die Messwertauswahl für Diagramme oder im Metrics Explorer verwenden, um eine Abfrage zu erstellen und diese dann in MQL umzuwandeln. Die entsprechende MQL-Abfrage wird im Editor angezeigt.

So konvertieren Sie eine menübasierte Abfrage in MQL, wenn Sie den Metrics Explorer verwenden:

1. Wählen Sie in der Symbolleiste des Bereichs „Query Builder“ die Schaltfläche mit dem Namen  MQL oder  PromQL aus.
2. Prüfen Sie, ob im Umschalter Sprache MQL ausgewählt ist. Die Ein-/Aus-Schaltfläche für die Sprache befindet sich in derselben Symbolleiste, mit der Sie die Abfrage formatieren können.

Klicken Sie beim Anzeigen eines Diagramms in einem Dashboard auf MQL, um eine formularbasierte Abfrage in MQL zu konvertieren.

Stellen Sie sich eine sehr einfache Anfrage vor, z. B. "CPU-Auslastung von meinen Compute Engine-VM-Instanzen abrufen". Diese Abfrage umfasst den Typ der überwachten Ressource gce_instance und den Messwerttyp compute.googleapis.com/instance/cpu/usage_time.

Der folgende Screenshot zeigt diese Abfrage in der formularbasierten Messwertauswahl:

Die Messwert- und überwachten Ressourcentypen wurden manuell eingegeben. Alle anderen Felder haben ihre Standardwerte.

Der folgende Screenshot zeigt das Ergebnis der Umwandlung der formularbasierten Auswahl in eine MQL-Abfrage:

Die MQL-Abfrage ruft die Zeitachsen für die angegebenen Messwerte und Ressourcentypen ab und führt eine Ratenanpassung in Intervallen von einer Minute durch. Die konvertierte Abfrage hat das strenge Format.

Hinweis: Sie können die MQL-Darstellung nicht wieder in die Einstellungen der formularbasierten Messwertauswahl umwandeln. MQL unterstützt Abfragen, die Sie nicht mit der Messwertauswahl erstellen können. Wenn Sie den Codeeditor beenden, wird der Abfragetext verworfen, wenn Sie ihn nicht speichern.