Codeeditor für MQL verwenden

In diesem Abschnitt werden die Features des Codeeditors für Monitoring Query Language (MQL) beschrieben. Der Editor ist in der Google Cloud Console verfügbar und bietet Vorschläge, Fehlererkennung und andere 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 im Metrics Explorer auf den Codeeditor zu:

1. Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.

   Zum Metrics Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

2. Klicken Sie in der Symbolleiste des Bereichs "Query Builder" auf die Schaltfläche  MQL oder  PromQL.
3. Prüfen Sie, ob MQL im Schalter Sprache ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.

Wenn Sie ein Diagramm in einem Dashboard erstellen, gehen Sie ähnlich vor, um auf den Code-Editor zuzugreifen.

Codeeditor verwenden

Um den Codeeditor zu verwenden, geben Sie Ihre Abfrage in den Abfrageeditor ein und klicken Sie auf Abfrage ausführen:

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, die festlegen, wie er mit Ihrer 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 die Abfrage während der Eingabe automatisch ausgeführt wird. Diese Option ist jedoch standardmäßig deaktiviert.

Über die Ein/Aus-Schaltfläche Automatisch ausführen können Sie die Option „Automatisch ausführen“ 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 zu bewerten.

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 Codeeditor im Metrics Explorer können Sie Ihr Diagramm in einem Dashboard speichern. So speichern Sie das Diagramm:

1. Wenn die Option zur automatischen Ausführung nicht aktiviert ist, führen Sie die Abfrage aus, indem Sie vor dem Speichern des Diagramms auf Abfrage ausführen klicken. 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 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 die Option zur automatischen Ausführung nicht aktiviert ist, führen Sie die Abfrage aus, indem Sie vor dem Speichern des Diagramms auf Abfrage ausführen klicken. 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 beenden

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 strikter Form ansehen

Wenn Sie mit dem Codeeditor eine Abfrage in der strikten Form ansehen möchten, klicken Sie auf Weitere Optionen und wählen Sie Strikte Form ansehen 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 sollen. Der Zeitraum kann implizit mithilfe der Zeitraumauswahl des Diagramms oder explizit im MQL-Abfragetext ausgedrückt werden.

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

Um den Zeitraum eines Diagramms zu ändern, verwenden Sie die Zeitraumauswahl. Wenn Sie beispielsweise die Daten für die vergangene Woche ansehen möchten, wählen Sie in der Zeitraumauswahl Letzte 1 Woche aus. Sie können auch eine Start- und Endzeit oder eine Uhrzeit angeben, zu der Sie sich umsehen möchten.

Informationen zum Erstellen von Benachrichtigungsrichtlinien mit dem Code-Editor 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 basierend auf dem Wert der Zeitraumauswahl des Diagramms und der maximalen Anzahl von Punkten festgelegt, die in einem Diagramm angezeigt werden können. Beispiel: Wenn Sie eine Woche auswählen, kann der Diagrammzeitraum eine Stunde betragen. Klicken Sie bei Diagrammen in Dashboards auf Abfragestatistiken, um den Grafikzeitraum aufzurufen.

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 Zeitraum für die Abfrageausrichtung nahe am Diagrammzeitraum liegt, stellt das Diagramm jede grafisch dargestellte Zeitachse mit einer einzigen 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 wir beispielsweise die folgende MQL-Abfrage an:

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

Diese Abfrage gibt die durchschnittliche CPU-Auslastung von VMs nach Zone mit einem einstündigen Ausrichtungszeitraum zurück.

Wenn die Zeitauswahl des Diagramms auf eine Woche festgelegt ist, beträgt der Diagrammzeitraum eine Stunde, was 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, der in der vorherigen Abfrage an den every-Vorgang von 1h in 1m übergeben wurde, ändern, wird mit der Abfrage ein Diagramm erstellt, das die Minimal-/Maximalbereiche enthält:

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 Code-Editor verwenden, um Abfragen für Benachrichtigungsrichtlinien zu erstellen.

Zum Erstellen einer MQL-basierten Benachrichtigungsrichtlinie über die Google Cloud Console führen Sie die unter Benachrichtigungsrichtlinien verwalten beschriebenen Schritte aus. Beim Erstellen der Bedingung für die Benachrichtigungsrichtlinie verwenden Sie jedoch den Code-Editor 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 zu konvertieren. Die entsprechende MQL-Abfrage wird im Editor angezeigt.

So konvertieren Sie mit dem Metrics Explorer eine in einem Menü erstellte Abfrage in MQL:

1. Klicken Sie in der Symbolleiste des Bereichs "Query Builder" auf die Schaltfläche  MQL oder  PromQL.
2. Prüfen Sie, ob MQL im Schalter Sprache ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.

Wenn Sie eine formularbasierte Abfrage in MQL konvertieren möchten, klicken Sie beim Anzeigen eines Diagramms in einem Dashboard auf MQL (MQL).

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 Konvertierung 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 und nicht gespeichert.