In diesem Dokument wird erläutert, wie Messwertdaten, auch als Zeitreihendaten bezeichnet, mithilfe der Methode timeSeries.list
in der Monitoring API gelesen werden.
Es gibt mehrere Möglichkeiten, die Methode timeSeries.list
aufzurufen:
- Auf den Tabs Protokoll auf dieser Seite können Sie den formularbasierten APIs Explorer verwenden.
- Sie können eine sprachspezifische Clientbibliothek verwenden.
- Sie können den Metrics Explorer verwenden.
Eine weitere Möglichkeit zum Lesen von Messwertdaten besteht darin, einen Befehl an die Methode timeSeries.query
zu senden, für die Monitoring Query Language (MQL) erforderlich ist. In diesem Dokument wird weder MQL noch die Methode timeSeries.query
beschrieben. Informationen zu diesen Themen finden Sie unter Daten mit timeSeries.query
abrufen.
Überblick
Bei jedem Aufruf der timeSeries.list
-Methode kann eine beliebige Anzahl von Zeitachsen eines einzelnen Messwerttyps zurückgegeben werden. Wenn Sie beispielsweise Compute Engine verwenden, hat der Messwerttyp compute.googleapis.com/instance/cpu/usage_time
für jede Ihrer VM-Instanzen eine separate Zeitachse.
Eine Einführung in Messwerte und Zeitachsen finden Sie unter Messwerte, Zeitachsen und Ressourcen.
Zum Angeben der gewünschten Zeitachsendaten stellen Sie die folgenden Informationen für die Methode timeSeries.list
bereit:
- Einen Filterausdruck, der den Messwerttyp festlegt. Mit dem Filter können Sie optional eine Teilmenge der Zeitachsen des Messwerts auswählen. Geben Sie hierfür die zum Erstellen der Zeitachsen verwendeten Ressourcen oder Werte für bestimmte Labels der Zeitachsen an.
- Ein Zeitintervall, das den Umfang der zurückgegebenen Daten einschränkt.
- Eine optionale Spezifikation dazu, wie mehrere Zeitachsen für eine aggregierte Zusammenfassung der Daten kombiniert werden sollen. Weitere Informationen und Beispiele finden Sie unter Daten aggregieren.
Zeitachsenfilter
Durch die Übergabe eines Zeitachsenfilters an die Methode timeSeries.list
geben Sie an, welche Zeitachse abgerufen werden soll.
Im Folgenden sind die gängigen Filterkomponenten aufgeführt:
Der Filter muss einen einzelnen Messwerttyp angeben. Beispiel:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Um benutzerdefinierte Messwerte abzurufen, ändern Sie das Präfix „metric.type“ im Filter in
custom.googleapis.com
oder, falls verwendet, ein anderes Präfix. Häufig wirdexternal.googleapis.com
verwendet.Der Filter kann Werte für die Dimensionslabels des Messwerts angeben. Welche Labels verfügbar sind, richtet sich nach dem Messwerttyp. Beispiel:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Im vorherigen Ausdruck ist
label
korrekt, obwohl das tatsächliche Messwertobjektlabels
als Schlüssel verwendet.Mit dem Filter können nur Zeitachsen ausgewählt werden, die einen bestimmten Typ überwachter Ressource enthalten:
resource.type = "gce_instance"
Die Filterkomponenten lassen sich zu einem einzigen Zeitachsenfilter zusammenfassen. Beispiel:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
(metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
Wenn Sie nicht für alle Messwertlabels Werte angeben, gibt die Methode list
für jede Kombination von Werten in den nicht festgelegten Labels eine Zeitachse zurück. Die Methode gibt nur Zeitachsen zurück, die Daten enthalten.
Zeitintervalle
Wenn Sie die API zum Lesen von Daten verwenden, geben Sie das Zeitintervall an, für das Sie Daten abrufen möchten, indem Sie Start- und Endzeiten festlegen.
Die API ruft Daten aus dem Intervall (start, end]
ab, also von der Startzeit bis zum Ende.
Der Beginn darf nicht nach dem Ende liegen. Wenn Sie einen Beginn angeben, der nach dem Ende liegt, gibt die API einen Fehler zurück.
Wenn Sie nur Daten mit einem bestimmten Zeitstempel abrufen möchten, legen Sie die Startzeit auf die Endzeit fest oder geben keine Startzeit an.
Zeitformat
Die Start- und Endzeit muss als Zeichenfolge im Format RFC 3339 angegeben werden. Beispiel:
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
Mit dem Befehl date -Iseconds
kann man unter Linux Zeitstempel erzeugen lassen.
Grundlegende Listenoperationen
Mit der Methode timeSeries.list
können einfache Rohdaten oder stark verarbeitete Daten zurückgegeben werden. In diesem Abschnitt wird gezeigt, wie Sie die verfügbaren Zeitachsen auflisten und die Werte in einer bestimmten Zeitachse abrufen.
Beispiel: Verfügbare Zeitachsen auflisten
In diesem Beispiel wird gezeigt, wie man nur die Namen und Beschreibungen der Zeitachsen auflisten kann, die einer Filterbedingung entsprechen, statt alle verfügbaren Daten zurückzugeben:
Protokoll
Öffnen Sie die Referenzseite für
timeSeries.list
.Geben Sie im Bereich Testen Sie diese Methode Folgendes ein:
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
projects/PROJECT_ID
-
filter: Geben Sie den Messwerttyp an.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: Geben Sie die Endzeit ein.
- interval.startTime: Geben Sie die Startzeit ein und achten Sie darauf, dass sie 20 Minuten vor dem Ende liegt.
Klicken Sie auf Standardparameter anzeigen und geben Sie in den Feldern Folgendes ein:
timeSeries.metric
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
Klicken Sie auf Execute.
Das Ausgabebeispiel zeigt Zeitachsen für zwei verschiedene VM-Instanzen:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
Wenn Sie die Anfrage als curl
-Befehl, HTTP-Anfrage oder in JavaScript ansehen möchten, klicken Sie in APIs Explorer auf fullscreen Vollbild.
C#
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Go
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Informationen zur Behebung von Problemen finden Sie unter Fehlerbehebung bei der Monitoring API.
Beispiel: Zeitachsendaten abrufen
Dieses Beispiel gibt die CPU-Auslastungsmessungen zurück, die über ein 20-Minuten-Intervall für eine bestimmte Compute Engine-Instanz aufgezeichnet wurden. Die Menge der zurückgegebenen Daten hängt von der Abtastrate des Messwerts ab. Da die CPU-Auslastung jede Minute erfasst wird, ergeben sich aus dieser Abfrage etwa 20 Datenpunkte. Werden für eine Zeitreihe mehrere Datenpunkte zurückgegeben, gibt die API die Datenpunkte in jeder Zeitachse in umgekehrter Zeitreihenfolge zurück. Diese Punktreihenfolge kann nicht überschrieben werden.
Protokoll
Im Protokollbeispiel wird die Ausgabe weiter eingeschränkt, um die zurückgegebenen Daten im Antwortfeld übersichtlicher zu gestalten:
- Der Wert filter begrenzt die Zeitreihe auf eine einzelne VM-Instanz.
- Der Wert fields legt nur die Zeit und den Wert der Messwerte fest.
Die Menge der im Ergebnis zurückgegebenen Zeitachsendaten wird durch diese Einstellungen begrenzt
Öffnen Sie die Referenzseite für
timeSeries.list
.Geben Sie im Bereich Testen Sie diese Methode Folgendes ein:
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
projects/PROJECT_ID
filter: Geben Sie den Messwerttyp an.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime: Geben Sie die Endzeit ein.
interval.startTime: Geben Sie die Startzeit ein und achten Sie darauf, dass sie 20 Minuten vor dem Ende liegt.
Klicken Sie auf Standardparameter anzeigen und geben Sie in den Feldern Folgendes ein:
timeSeries.points.interval.endTime,timeSeries.points.value
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
Klicken Sie auf Execute.
Die Anfrage liefert ein Ergebnis wie dieses:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
Wenn Sie die Anfrage als curl
-Befehl, HTTP-Anfrage oder in JavaScript ansehen möchten, klicken Sie in APIs Explorer auf fullscreen Vollbild.
C#
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Go
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Informationen zur Behebung von Problemen finden Sie unter Fehlerbehebung bei der Monitoring API.
Daten aggregieren
Die Methode timeSeries.list
kann statistische Aggregationen und Reduzierungen der zurückgegebenen Zeitachsendaten liefern. In den folgenden Abschnitten werden zwei Beispiele gezeigt.
Weitere Informationen finden Sie unter Filtern und Aggregation: Zeitreihen bearbeiten.
Beispiel: Zeitreihen ausrichten
In diesem Beispiel werden die 20 individuellen Auslastungsmessungen in jeder Zeitachse auf 2 Messungen reduziert: die durchschnittliche Auslastung für die beiden 10-Minuten-Zeiträume innerhalb des 20-Minuten-Intervalls. Die Daten aus jeder Zeitreihe werden zuerst in Perioden von 10 Minuten angeordnet und dann werden die Werte in jedem 10-Minuten-Zeitraum gemittelt.
Der Ausrichtungsvorgang bietet zwei Vorteile: Die Daten werden geglättet und die Daten aus allen Zeitreihendaten werden an exakten 10-Minuten-Grenzen ausgerichtet. Die ausgerichteten Daten können dann weiter verarbeitet werden.
Protokoll
Öffnen Sie die Referenzseite für
timeSeries.list
.Geben Sie im Bereich Testen Sie diese Methode Folgendes ein:
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Geben Sie
600s
ein. -
aggregation.perSeriesAligner Wählen Sie
ALIGN_MEAN
aus. -
filter: Geben Sie den Messwerttyp an.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: Geben Sie die Endzeit ein.
- interval.startTime: Geben Sie die Startzeit ein und achten Sie darauf, dass sie 20 Minuten vor dem Ende liegt.
-
Klicken Sie auf Standardparameter anzeigen und geben Sie in den Feldern Folgendes ein:
timeSeries.metric,timeSeries.points
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
Klicken Sie auf Execute.
Der Filter für eine einzelne Instanz aus dem vorherigen Beispiel wird entfernt. Diese Abfrage gibt viel weniger Daten zurück, sodass weniger die Notwendigkeit besteht, sie auf eine VM-Instanz einzuschränken.
Das folgende Beispielergebnis enthält für jede der drei VM-Instanzen eine Zeitachse. Jede Zeitachse hat zwei Datenpunkte, die durchschnittliche Auslastung für die 10-minütigen Ausrichtungszeiträume:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
Wenn Sie die Anfrage als curl
-Befehl, HTTP-Anfrage oder in JavaScript ansehen möchten, klicken Sie in APIs Explorer auf fullscreen Vollbild.
C#
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Go
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Informationen zur Behebung von Problemen finden Sie unter Fehlerbehebung bei der Monitoring API.
Beispiel: Zeitachsen reduzieren
Dieses Beispiel erweitert das vorherige Beispiel, indem die ausgerichteten Zeitachsen der drei VM-Instanzen in einer einzigen Zeitachse kombiniert werden, die die durchschnittliche Auslastung aller Instanzen misst.
Protokoll
Öffnen Sie die Referenzseite für
timeSeries.list
.Geben Sie im Bereich Testen Sie diese Methode Folgendes ein:
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Geben Sie
600s
ein. -
aggregation.perSeriesAligner Wählen Sie
ALIGN_MEAN
aus. -
aggregation.crossSeriesReducer: Wählen Sie
REDUCE_MEAN
aus. -
filter: Geben Sie den Messwerttyp an.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: Geben Sie die Endzeit ein.
- interval.startTime: Geben Sie die Startzeit ein und achten Sie darauf, dass sie 20 Minuten vor dem Ende liegt.
-
Klicken Sie auf Standardparameter anzeigen und geben Sie in den Feldern Folgendes ein:
timeSeries.metric,timeSeries.points
-
Name: Geben Sie den Pfad zu Ihrem Projekt ein.
Klicken Sie auf Execute.
Das folgende Beispielergebnis hat nur eine Zeitreihe und zwei Datenpunkte. Jeder Punkt gibt die durchschnittliche Auslastung aller drei VM-Instanzen innerhalb des Zeitraums an:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
Wenn Sie die Anfrage als curl
-Befehl, HTTP-Anfrage oder in JavaScript ansehen möchten, klicken Sie in APIs Explorer auf fullscreen Vollbild.
C#
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Go
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Informationen zur Behebung von Problemen finden Sie unter Fehlerbehebung bei der Monitoring API.