In dieser Anleitung wird beschrieben, wie Sie Filter konfigurieren, wenn Sie die Monitoring API verwenden. Sie verwenden Filter, um überwachte Ressourcen, Messwerttypen, Gruppendefinitionen und Zeitachsen festzulegen.
Sie können auch einen Filter verwenden, um eine Benachrichtigungsrichtlinie zu konfigurieren, die auf Ihren Systemen ausgeführte Prozesse überwacht. Informationen zu diesen Filtern finden Sie unter Prozessintegritätsfilter.
Hinweis
Wenn Sie mit Messwerten, Zeitachsen und überwachten Ressourcen nicht vertraut sind, lesen Sie Messwerte, Zeitachsen und Ressourcen.
Wenn Sie mit Labels nicht vertraut sind, finden Sie eine Einführung unter Labels.
Filter verwenden
Sie können Filter in der Monitoring API für Folgendes verwenden:
Wählen Sie die spezifischen Zeitachsendaten aus, die von einer
list
-API-Anfrage zurückgegeben werden. Mit dem Filter können Zeitachsen auf Grundlage des Projekt-, Gruppen-, überwachten Ressourcen- und Messwertattributs der Daten ausgewählt werden. Weitere Informationen und Beispiele finden Sie unter Zeitachsendaten abrufen.Weisen Sie Ressourcen basierend auf den Attributen der Ressourcen und dem Projekt, zu dem sie gehören, einer
Group
zu. Weitere Informationen und Beispiele finden Sie unter Gruppenmitgliedschaft definieren.Wählen Sie Ressourcen innerhalb einer Gruppe basierend auf den Attributen der Ressourcen und dem Projekt aus, zu dem sie gehören. Weitere Informationen und Beispiele finden Sie unter Gruppenmitglieder auflisten.
Listen Sie bestimmte Messwerttypen auf. Weitere Informationen und Beispiele finden Sie unter Messwertdeskriptoren auflisten.
Listen Sie bestimmte überwachte Ressourcentypen au. Weitere Informationen und Beispiele finden Sie unter Überwachte Ressourcendeskriptoren auflisten.
Die Auswahl filtern
Ein Filter besteht aus mindestens einem Selektor, bei dem es sich um ein Filter-Keyword handelt. Die folgenden einfachen Beispiele veranschaulichen die verschiedenen Selektoren:
project
: Stimmt überein, wenn die Messwerte des angegebenen Projekts für das Scoping-Projekt eines Messwertbereichs sichtbar sind, der im Parametername
erwähnt wird.Verwenden Sie den Selektor
project
, wenn ein Google Cloud-Projekt die Messwerte mehrerer Google Cloud-Projekte oder AWS-Konten ansehen kann und Sie nur Messwerte für ein einzelnes Projekt möchten. Wenn der Messwertbereich fürProject-A
beispielsweiseProject-B
enthält, erfolgt eine Übereinstimmung, wennname
den WertProject-A
hat und Sie Verwenden Sie den folgenden Filter:project = "Project-B"
group
: Stimmt mit Ressourcen überein, die zu einerGroup
gehören.Stimmt mit der Gruppe mit der Kennung
group-id
überein:group.id = "group-id"
resource
: Stimmt mit überwachten Ressourcen eines bestimmten Typs oder mit bestimmten Labelwerten überein.Stimmt mit allen überwachten Ressourcen überein, bei denen es sich um Compute Engine-VM-Instanzen handelt:
resource.type = "gce_instance"
Stimmt mit allen Ressourcen überein, deren Zone mit
europe-
beginnt:resource.labels.zone = starts_with("europe-")
metric
: Stimmt mit einem bestimmten Messwerttyp überein oder mit einer Zeitachse mit einem bestimmten Label, das mit einem bestimmten Wert übereinstimmt.Stimmt mit einem bestimmten Messwert überein:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Stimmt mit Zeitachsen mit einem Label namens
instance_name
überein, dessen Wert mitgke-hipster
odergke-nginx
beginnt:metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
In der folgenden Tabelle sehen Sie, welche Selektoren in Filtern basierend auf dem Aufruf der Monitoring API zulässig sind:
Zweck des Filters | "Projekt"-Selektor | "Gruppen"-Selektor | "Ressourcen"-Selektor | "Messwert"-Selektor |
---|---|---|---|---|
Gruppen definieren | Ja | Ja1 | ||
Gruppenmitglieder auflisten | Ja | Ja | ||
Zeitachsen auflisten | Ja | Ja | Ja | Ja2 |
Messwertdeskriptoren auflisten | Ja | Ja | ||
Listen Sie überwachte Ressourcendeskriptoren auf. | Ja |
2 Beim Auflisten von Zeitachsen müssen Sie genau einen Messwerttyp angeben.
In den folgenden Abschnitten finden Sie Beispiele für typische Anwendungsfälle von Monitoring-Filtern. Eine vollständige Beschreibung der verfügbaren Filterobjekte und Operatoren finden Sie unter Filtersyntax.
Zeitachsendaten werden abgerufen
Methode:
projects.timeSeries.list
Filtern der Objekte: project
, group.id
, resource.type
,
resource.labels.[KEY]
, metric.type
, metric.labels.[KEY]
Eine Zeitachse ist eine Liste von Datenpunkten mit Zeitstempeln, die einem Messwerttyp aus einer bestimmten überwachten Ressource zugeordnet werden können. Weitere Informationen finden Sie unter Messwertmodell. Der Messwerttyp wird durch einen Messwertdeskriptor und die überwachte Ressource durch einen Deskriptor für überwachte Ressourcen angegeben.
Der im Befehl list
angegebene Filter muss einen metric
-Selektor enthalten. Dieser Selektor muss genau einen Messwerttyp angeben:
Geben Sie alle Zeitachsen für einen bestimmten Messwerttyp zurück:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Geben Sie alle Zeitachsen für eine bestimmte Gruppe zurück. Der
group
-Selektor funktioniert nur mit ausgerichteten Zeitachsendaten. Weitere Informationen finden Sie unter Gruppen-Selektor:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND group.id = "2468013579"
Geben Sie alle Zeitachsen einer bestimmten Compute Engine-Instanz zurück:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Geben Sie alle Zeitachsen von Compute Engine-Instanzen zurück, deren Namen mit
frontend-
beginnen:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")
Geben Sie alle Zeitachsen von Compute Engine-Instanzen zurück, deren Namen mit
gke-hipster
odergke-nginx
beginnen:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
Gruppenmitgliedschaft definieren
Methode:
projects.groups
Filtern der Objekte: project
, resource.type
, resource.labels.key
,
metadata.system_labels.[KEY]
, metadata.user_labels.[KEY]
Eine Gruppe kann je nach Filter beliebig viele Ressourcen enthalten. Die Gruppenmitgliedschaft ist dynamisch. Bei jeder Auswertung des Filters können mehr oder weniger Ressourcen mit dem Filter übereinstimmen. Der Parameter name
im Objekt Group
gibt die Gruppe und das Scoping-Projekt eines Messwertbereichs an.
Wenn der Selektor project
im Filter verwendet wird, muss er ein Projekt angeben, dessen Messwerte für das Scoping-Projekt sichtbar sind.
Alle Compute Engine-VM-Instanzen in Europa:
resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
Gruppenmitglieder auflisten
Methode: projects.groups.members.list
Filterobjekte: project
, resource.type
, resource.labels.[KEY]
Verwenden Sie einen Filter, um einzuschränken, welche Gruppenmitglieder Sie abrufen. Der Parameter name
gibt ein Scoping-Projekt eines Messwertbereichs und eine in diesem Projekt definierte Gruppe an.
Wenn der Selektor project
im Filter verwendet wird, muss er ein Projekt angeben, dessen Messwerte für das Scoping-Projekt sichtbar sind.
Alle Pub/Sub-Themenressourcen, die zum Projekt
my-project
gehören:project = "my-project" AND resource.type = "pubsub_topic"
Messwertdeskriptoren auflisten
Methode: projects.metricDescriptors.list
Filterobjekte: project
, metric.type
Verwenden Sie einen Filter, um einzuschränken, welche Messwertdeskriptoren Sie abrufen:
Verwenden Sie den folgenden Filter, um nur die Compute Engine-Messwertdeskriptoren zurückzugeben:
metric.type = starts_with("compute.googleapis.com")
Eine vollständige Liste der von Monitoring definierten Messwerttypen finden Sie unter Messwertliste. Eine Übersicht über die Benennung von Messwerten finden Sie unter Namenskonventionen und Anforderungen.
Überwachte Ressourcendeskriptoren auflisten
Methode: projects.monitoredResourceDescriptors.list
Objekte filtern: resource.type
Verwenden Sie einen Filter, um einzuschränken, welche überwachten Ressourcendeskriptoren Sie abrufen:
Verwenden Sie den folgenden Filter, um nur die von Pub/Sub überwachten Ressourcendeskriptoren abzurufen:
resource.type = starts_with("pubsub")
Eine vollständige Liste der von Monitoring definierten überwachten Ressourcentypen finden Sie unter Liste der überwachten Ressourcen.
Referenz: Filtersyntax
Eine Übersicht über Filter mit Beispielen finden Sie unter Filter verwenden.
Ein Monitoring-Filter ist ein String, der aus bis zu vier Selektortypen besteht:
<monitoring_filter> ::= <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>
Der Filter stimmt mit einem Element überein, wenn alle enthaltenen Selektoren mit dem Element übereinstimmen. Wie in den folgenden Abschnitten beschrieben, können bei einigen Selektoren mehrere Vergleiche durch AND
oder OR
verknüpft werden.
Je nach Zweck des Filters können bestimmte Selektoren erforderlich, optional oder unzulässig sein. Beispielsweise kann der Filter, der die Ressourcen in einer Gruppe definiert, keine Messwertauswahl enthalten, da Gruppen keine Messwerttypen oder Zeitachsen enthalten. Der Filter zum Auflisten von Zeitachsen muss dagegen eine Messwertauswahl enthalten. Die Reihenfolge der Selektoren im Filter spielt keine Rolle, Vergleiche für verschiedene Selektoren dürfen jedoch nicht vermischt werden.
Vergleiche
Filter und ihre Selektoren werden aus Vergleichen erstellt. Jeder Vergleich hat das folgende Format:
[OBJECT] [OPERATOR] [VALUE]
Diese Elemente werden im Folgenden beschrieben:
[OBJECT]: Wählt einen der folgenden zu testenden Werte aus:
project group.id metric.type metric.labels.[KEY] resource.type resource.labels.[KEY] metadata.system_labels.[KEY] metadata.user_labels.[KEYSTRING]
[KEY] ist ein Name wie
zone
oderinstance_id
. [KEYSTRING] kann ein Name sein. Wenn er Sonderzeichen enthält, muss er in Anführungszeichen ("
) gesetzt werden.[OPERATOR] ist einer dieser Vergleichsoperatoren:
= # equality (case-sensitive) > < >= <= # numeric ordering != # not equal : # "has" substring match and test for key (case-sensitive)
[VALUE]: ist einer der folgenden Literalwerte oder integrierten Funktionsaufrufe:
<string> # "a Unicode string". Don't use apostrophes (`'`) to quote strings. <bool> # true or false <number> # 0, -2, 123456, 3.14156 <function> # operators on the right side of '=' or '!=': # starts_with(<string>) # ends_with(<string>) # has_substring(<string> [, ignore_case=false]) # one_of(<string>,...,<string>) for up to 100 strings # monitoring.regex.full_match(<RE2-string>)
Abgesehen von
timeSeries.list
verwendet der Filterhas_substring
ein optionales zweites Argument, das angibt, ob beim Abgleich die Groß-/Kleinschreibung ignoriert wird. Der Standardwert istfalse
. Die Groß-/Kleinschreibung wird daher standardmäßig berücksichtigt:- Groß- und Kleinschreibung wird berücksichtigt:
display_name=has_substring("Demo")
- Groß- und Kleinschreibung wird berücksichtigt:
display_name=has_substring("Demo", false)
- Groß- und Kleinschreibung wird nicht berücksichtigt:
display_name=has_substring("Demo", true)
Bei
timeSeries.list
wird nur die Formhas_substring(<string>)
unterstützt.Der Filter
monitoring.regex.full_match
verwendet einen String mit regulärem Ausdruck in der RE2-Syntax.- Groß- und Kleinschreibung wird berücksichtigt:
Mit den folgenden Operatoren können Sie Vergleiche gruppieren oder ändern. OR
hat eine höhere Priorität als AND
. Die Operatoren müssen in Großbuchstaben geschrieben werden:
(...) # grouping comparisons
AND # conjunction (optional but recommended)
OR # disjunction
Der Operator AND
kann zwischen Operatoren weggelassen werden, ist jedoch klarer und weniger fehleranfällig.
Der Vergleich x = one_of("a", "b", "c")
entspricht
(x = "a" OR x = "b" OR x = "c")
Nur in Gruppendefinitionen können Sie den unären Negationsoperator NOT
vor einem Vergleich verwenden, nicht aber mit einem vorhandenen Operator (:
) oder vor einem eingeklammerten Ausdruck:
NOT # negates the following comparison
Die Auswahl filtern
Verwenden Sie Selektoren, um die Filterauswahl auf bestimmte Elemente zu beschränken.
In den folgenden Abschnitten werden Klammern zur Darstellung von Wiederholungen verwendet. Die Schreibweise <x> {OR <y>}
bedeutet beispielsweise, dass Sie Folgendes schreiben können:
<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...
Projektauswahl
Mit einer Projektauswahl wird die Filterauswahl auf Elemente beschränkt, die zu einem einzelnen Projekt oder einem Projektsatz gehören. Jedes Projekt kann durch seine ID oder seine Nummer angegeben werden:
<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}
Wenn Ihr Projektselektor mehr als einen Vergleich enthält, setzen Sie den gesamten Selektor in Klammern, um die Lesbarkeit zu verbessern. Beispiel:
(project=12345 OR project="my-project-id") AND resource.type="gce_instance"
Gruppenauswahl
Eine Gruppenauswahl beschränkt die Filterauswahl auf Elemente, die zu einer einzelnen Gruppe gehören:
<group_selector> ::= group.id '=' <string>
Der folgende Filter könnte beispielsweise verwendet werden, um eine Zeitachse von jeder der VM-Instanzen in einer Gruppe abzurufen:
group.id = 12345 AND
resource.type = "gce_instance" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Die Gruppenauswahl ist nur in Filtern zulässig, die an projects.timeSeries.list
übergeben werden. Darüber hinaus erfordert die Gruppenauswahl ausgerichtete Daten. Das heißt, der Aufruf von projects.timeSeries.list
muss Werte für perSeriesAligner
und alignmentPeriod
enthalten. Dies liegt daran, dass die Gruppenmitgliedschaft selbst eine Art Zeitachse ist, die mit den Messwertdaten verknüpft werden muss. Durch die Angabe von Ausrichtungsparametern können Sie steuern, wie diese Verknüpfung erfolgt.
Weitere Informationen zu Ausrichtungsparametern finden Sie unter Daten aggregieren.
Ressourcenauswahl
Eine Ressourcenauswahl beschränkt die Filterauswahl auf Ressourcen oder mit Ressourcen verknüpfte Elemente, die einen bestimmten Ressourcentyp oder bestimmte Labelwerte haben:
<resource_selector> ::= <resource_type_expression>
| <resource_label_expression>
| <resource_type_expression> AND <resource_label_expression>
<resource_type_expression> ::= resource.type '=' <string>
| resource.type ':' <string>
| resource.type '=' starts_with '(' <string>')'
| resource.type '=' ends_with '(' <string> ')'
<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
| <r_label_comparison> {OR <r_label_comparison>}
<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
| resource.labels.[KEY] ':' <string>
| resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
| resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>
Wenn Sie mehrere <r_label_comparison>
im Selector verwenden, setzen Sie diese zur besseren Lesbarkeit in Klammern. Mit dem folgenden Filter können Sie beispielsweise eine Gruppe definieren, die alle VM-Instanzen in den USA und Europa enthält:
resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
Ressourcenauswahl für Gruppendefinitionen
Ressourcenauswahlen, die zum Definieren von Gruppenmitgliedschaften verwendet werden, verwenden Erweiterungen für die Syntax <resource_selector>
:
Sie können die Namen
metadata.system_labels.[KEY]
undmetadata.user_labels.[KEYSTRING]
in Vergleichen auf die gleiche Weise verwenden wieresource.labels.[KEY]
. Die Schlüssel fürmetadata.user_labels
müssen in Anführungszeichen gesetzt werden, da sie Sonderzeichen wie Bindestriche enthalten können.Sie können den Nicht-Gleich-Operator (
!=
) verwenden, um Ressourcentypen, Ressourcenlabels und Metadaten zu vergleichen. Der Operator kann beim Vergleich von Strings, Zahlen, booleschen Werten oder Teilstringfunktionen verwendet werden. Beispiel:resource.type!=starts_with("gce")
ist "true", wenn der Ressourcentyp nicht mit"gce"
beginnt.Sie können vor einem Ressourcenvergleich einen einzelnen
NOT
-Operator verwenden. Beispiel:NOT resource.labels.zone="europe"
ist wahr, wenn die Zone der Ressource"europe"
nicht enthält. Sie könnenNOT
nicht vor einem vorhandenen Operator (:
) oder einem Ausdruck in Klammern verwenden.Mit dem Operator "Vorhanden" (
:
) können Sie testen, ob Schlüssel vorhanden sind. Der Vergleichresource.labels.zone
ist beispielsweise "true", wenn der Labelschlüsselzone
in der Ressource vorhanden ist.
Einer der Metadatenschlüssel für Plattformressourcen für VM-Instanzen ist beispielsweise spot_instance
. Mit der folgenden Filterauswahl werden Instanzen ausgewählt, bei denen es sich um Spot-Instanzen handelt:
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
Messwertauswahl
Eine Messwertauswahl gibt bestimmte Messwerte oder Messwertdeskriptoren an, indem der Messwerttyp und die Messwertlabels begrenzt werden. Beim Auflisten von Zeitachsendaten muss in der Messwertauswahl ein einzelner Messwerttyp angegeben werden:
<metric_selector> ::= <metric_name_expression> [AND <metric_label_expression>]
<metric_name_expression> ::= metric.type '=' <string>
| metric.type ':' <string>
| metric.type '=' starts_with '(' <string> ')'
| metric.type '=' ends_with '(' <string> ')'
<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
| <metric_label_comparison> {OR <metric_label_comparison>}
<metric_label_comparison> ::= metric.labels.[KEY] '=' <string> | <bool>
| metric.labels.[KEY] ':' <string>
| metric.labels.[KEY] '=' starts_with '(' <string> ')'
| metric.labels.[KEY] '=' ends_with '(' <string> ')'
| metric.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>
Mit dem folgenden Filter können Sie beispielsweise eine Zeitachse für eine bestimmte Datenbankinstanz abrufen:
metric.type = "cloudsql.googleapis.com/database/state" AND
(metric.labels.resource_type = "instance" AND
metric.labels.resource_id = "abc-123456")
Beispiele
In den Filterbeispielen werden der folgende Messwertdeskriptor, der überwachte Ressourcendeskriptor und die VM-Instanz vereinfacht verwendet:
# Metric descriptor:
{ "name": "projects/my-project-id/metricDescriptors/compute.googleapis.com%2Finstance%2Fdisk%2Fread_bytes_count"
"type": "compute.googleapis.com/instance/disk/read_bytes_count",
"labels": [ { "key": "device_name",
"description": "The name of the disk device." } ] }
# Monitored resource descriptor:
{ "name": "monitoredResourceDescriptors/gce_instance"
"type": "gce_instance",
"labels": [
{ "key": "instance_id",
"description": "The instance ID provide by Google Compute Engine." },
{ "key": "zone",
"description": "The Google Cloud Platform zone hosting the instance."
} ] }
# Resource descriptor for a virtual machine instance.
{ "type": "gce_instance",
"instance_id": "1472038649266883453",
"zone": "us-east-1b",
"disks": [ "log_partition" ],
"machine_type": "n1-standard-2",
"tags": { "environment": "bleeding-edge",
"role": "frobulator" },
"project_id": "my-project-id" }
Beispiele zum Abrufen von Messwerten
Um die Bandbreitennutzung für alle Instanzen und Geräte anzufordern, definieren Sie einen Filter wie unten gezeigt. Dadurch wird für jede Instanz eine separate Zeitachse zurückgegeben, die die Lesebandbreite für jedes Gerät angibt:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Definieren Sie den Filter wie unten gezeigt, um die Anfrage für die Abfrage der Lesebandbreite nur für das Laufwerk "log_partition" auf jeder Instanz zu verfeinern. Dieser Filter gibt für jede Instanz höchstens eine Zeitachse zurück, je nachdem, ob ein Gerät mit diesem Namen in der Instanz vorhanden ist:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"
Wenn Sie die Anfrage auf eine einzelne Instanz beschränken möchten, geben Sie diese Instanz an:
resource.type = "gce_instance" AND
resource.labels.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"
Nach Gruppen filtern
Die folgenden Beispiele veranschaulichen die Verwendung der Gruppenauswahl in Filtern, um überwachte Ressourcen auf Ressourcen in einer bestimmten Gruppe zu beschränken. Informationen zu den Selektoren, die zum Definieren der Gruppenmitgliedschaft verwendet werden, finden Sie unter Gruppendefinitionen.
{ "name": "projects/my-test-project/groups/024681012",
"display_name": "My Redis Cluster",
"filter": "metadata.user_labels.role=redis" }
Bei einem Aufruf der Methode projects.timeSeries.list
fordert der folgende Filter die Bandbreitennutzung für alle Compute Engine-Instanzen in einer bestimmten Gruppe an. Die Gruppe muss im Scoping-Projekt eines Messwertbereichs definiert sein, der im Parameter name
der Methode angegeben ist:
resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"