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:
Rufen Sie die Methode
timeSeries.queryauf, um Zeitachsendaten mithilfe von MQL auszuwählen und zu bearbeiten. Beispiele finden Sie untertimeSeries.queryVerwenden.Zur Auswahl und Bearbeitung von Zeitachsendaten für Diagramme stellen Sie die Abfrage an eine
TimeSeriesQuery-Spezifikation, wenn Sie die Methodedashboards.createaufrufen. Ein Beispiel finden Sie unter Diagramme erstellen.Um MQL-basierte Bedingungen in Benachrichtigungsrichtlinien zu erstellen, beschreiben Sie die Bedingung für die Benachrichtigungsrichtlinie mit dem
MonitoringQueryLanguageConditionBedingungstyp, wenn SiealertPolicies.createaufrufen. Beispiele finden Sie unter Bedingungen für Benachrichtigungsrichtlinien erstellen.
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, wie in den folgenden einfachen Abfragen gezeigt:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}
Wenn durch die Abfrage eine nicht ausgerichtete Ausgabetabelle erstellt wird, müssen Sie mit dem Tabellenvorgang within eine Dauer angeben, wenn Sie die API direkt aufrufen. Diagrammtools wie Metrics Explorer bieten eine Standardabfragedauer. Die Abfrage im folgenden JSON-Snippet funktioniert im MQL-Codeeditor im Metrics Explorer, schlägt aber fehl, wenn sie direkt an die API übergeben wird:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}
Durch Hinzufügen eines within-Tabellenvorgangs zur vorherigen Abfrage kann das vorherige Beispiel direkt an die API übergeben werden:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}
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 Zeitreihe zurück. Die Tabelle ist in zwei Komponenten unterteilt:
timeSeriesDescriptorbeschreibt die Labelschlüssel, Labelwerte und Datenpunkte in der Tabelle. Sie enthält keine Daten. Sie beschreibt einfach die Daten.timeSeriesDataenthä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.
- Das erste Element im Paar,
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.
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.
Das folgende Beispiel zeigt eine einfache 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 | group_by sliding(5m), mean(val()) | condition val() > 0.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 in prägnanter oder strikter Form. Die Beispiele in diesem Dokument sind übersichtlich. Weitere Informationen zu Strict-Form-Abfragen finden Sie unter Strict-Form-Abfragen.
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 Verhalten von messwertbasierten Benachrichtigungsrichtlinien.
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, ausgedrückt 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:
Erstellen Sie eine Umgebungsvariable, die die ID Ihres Scoping-Projekts eines Messwertbereichs enthält. Mit diesen Schritten wird die Variable
PROJECT_IDaufgerufen:PROJECT_ID=a-sample-projectAuthentifizieren Sie sich in der Google Cloud CLI:
gcloud auth loginOptional. Damit Sie Ihre Projekt-ID nicht bei jedem
gcloud-Befehl angeben müssen, legen Sie die Projekt-ID über die gcloud CLI als Standard fest:gcloud config set project ${PROJECT_ID}Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen. Mit diesen Schritten wird die Variable
TOKENaufgerufen: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.
Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable
TOKENzurück:echo ${TOKEN} ya29.GluiBj8o....