Monitoring-Filter

In diesem Leitfaden wird die Verwendung von Überwachungsfiltern beschrieben, um überwachte Ressourcen, Messwerttypen, Gruppendefinitionen und Zeitachsen anzugeben.

Eine Einführung in Messwerte, Zeitachsen und überwachte Ressourcen finden Sie unter Messwerte, Zeitachsen und Ressourcen.

Filter verwenden weitgehend Labels. Weitere Informationen finden Sie unter Labels.

Filter verwenden

Sie können Filter in der Monitoring API v3 für Folgendes verwenden:

Zeitachsen abrufen Verwenden Sie einen Filter, um Zeitachsendaten basierend auf dem Projekt, der Gruppe, den überwachten Ressourceneigenschaften und den Messwerteigenschaften auszuwählen. Weitere Informationen und Beispiele finden Sie unter Zeitachsendaten abrufen.
Definieren Sie die Ressourcen in einer Gruppe. Verwenden Sie einen Filter, um Ressourcen einem Group basierend auf den Ressourcenattributen und dem Projekt zuzuweisen, zu dem sie gehören. Weitere Informationen und Beispiele finden Sie unter Gruppenmitgliedschaft definieren.
Gruppenmitglieder auflisten Verwenden Sie einen Filter, um Ressourcen innerhalb einer Gruppe basierend auf den Eigenschaften der Ressourcen und dem Projekt auszuwählen, zu dem sie gehören. Weitere Informationen und Beispiele finden Sie unter Gruppenmitglieder auflisten.
#list-metric-descriptors Verwenden Sie einen Filter, um bestimmte Messwerttypen aus den Hunderten von definierten Typen in Monitoring zu untersuchen. Weitere Informationen und Beispiele finden Sie unter Messwertdeskriptoren auflisten.
Listen Sie überwachte Ressourcendeskriptoren auf. Verwenden Sie einen Filter, um bestimmte überwachte Ressourcentypen aus den zahlreichen definierten Typen in Monitoring zu untersuchen. Weitere Informationen und Beispiele finden Sie unter Überwachte Ressourcendeskriptoren auflisten.

Je nachdem, welchen der vorherigen Vorgänge Sie einschränken, kann Ihr Filter aus dem logischen AND der Selektoren in der folgenden Liste bestehen. Dies sind einfache Beispiele, z. B. mehrere Arten von Vergleichsoperatoren.

Projektauswahl: Beschränkt die Filterübereinstimmung auf Objekte, die zu einem oder mehreren Projekten innerhalb des Arbeitsbereichs gehören, der im Parameter name der Methode angegeben ist.
```
project = "project-id-or-number" OR project = "another-id-or-number"
```
Gruppenauswahl: Findet Ressourcen, die zu einem (einzelnen) Group gehören. Beispiel:
```
group.id = "group-id"
```
Ressourcenauswahl: Entspricht überwachten Ressourcen eines bestimmten Typs oder mit bestimmten Labelwerten. Es gibt beispielsweise verschiedene Möglichkeiten, Ressourceninformationen anzugeben:
```
resource.type = "the_resource_type"
resource.labels.a_label_for_the_resource_type = "label_value"
```
Messwertauswahl: Filtern Sie den Filter auf Messwerte oder Zeitachsen eines bestimmten Messwerttyps oder mit bestimmten Labelwerten. Es gibt beispielsweise verschiedene Möglichkeiten, Messwerttypen anzugeben:
```
metric.type = "the_metric_type"
metric.labels.a_label_for_the_metric_type = "label_value"
```

In der folgenden Tabelle sehen Sie, welche Selektoren in Filtern je nach ihrer Verwendung zulässig sind:

Zweck des Filters	Projektauswahl	Gruppenauswahl	Ressourcenauswahl	Messwertauswahl
Gruppen definieren	Ja		Ja¹
Gruppenmitglieder auflisten	Ja		Ja
Zeitachsen auflisten	Ja	Ja	Ja	Ja²
Messwertdeskriptoren auflisten	Ja			Ja
Listen Sie überwachte Ressourcendeskriptoren auf.			Ja

¹ Die Ressourcenauswahl bietet zusätzliche Optionen für die Definition der Gruppenmitgliedschaft.
² 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. Filter müssen einen Messwertselektor enthalten, der genau einen Messwerttyp angibt.

Alle Zeitachsen für einen bestimmten Messwerttyp:

metric.type = "compute.googleapis.com/instance/cpu/usage_time"

Zeitachsen, die sich auf Ressourcen in einer bestimmten Gruppe beziehen Die Auswahl group funktioniert nur mit ausgerichteten Zeitachsendaten. Weitere Informationen finden Sie unter Gruppenauswahl:
```
group.id = "2468013579" AND
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```

Zeitachsen von einer bestimmten Compute Engine-Instanz:

metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = "my-instance-name"

Zeitachsen von ähnlich benannten Compute Engine-Instanzen:

metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = starts_with("frontend-")

Zeitachsen von Compute Engine-Instanzen, die mit gke-hipster oder gke-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 den zugehörigen Arbeitsbereich an. Wenn das Objekt project im Filter verwendet wird, muss es ein Projekt angeben, das Mitglied des Arbeitsbereichs ist.

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 der Methode gibt einen Arbeitsbereich und eine im Arbeitsbereich definierte Gruppe an. Wenn das Objekt project im Filter verwendet wird, muss es ein Projekt angeben, das Mitglied des Arbeitsbereichs ist.

Alle Cloud 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:

Alle Compute Engine-Messwerte:

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:

Alle von Cloud Pub/Sub überwachten Ressourcendeskriptoren.
```
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, aber Vergleiche für verschiedene Selektoren dürfen nicht miteinander 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 oder instance_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 Filter has_substring ein optionales zweites Argument, das angibt, ob beim Abgleich die Groß-/Kleinschreibung ignoriert wird. Der Standardwert ist false. 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 Form has_substring(<string>) unterstützt.

Der Filter monitoring.regex.full_match verwendet einen String mit regulärem Ausdruck in der RE2-Syntax.

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 vor einem Vergleich verwenden, jedoch nicht vor einem in Klammern gesetzten 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] und metadata.user_labels.[KEYSTRING] in Vergleichen auf die gleiche Weise verwenden wie resource.labels.[KEY]. Die Schlüssel für metadata.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 jedem Ressourcenvergleich einen einzelnen NOT-Operator verwenden. Beispiel: NOT resource.labels.zone:"europe" ist "true", wenn die Zone der Ressource nicht "europe" enthält. Sie können NOT nicht vor einem in Klammern gesetzten Ausdruck verwenden.
Mit dem Operator "Vorhanden" (:) können Sie testen, ob Schlüssel vorhanden sind. Der Vergleich resource.labels.zone ist beispielsweise "true", wenn der Labelschlüssel zone 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 Arbeitsbereich definiert werden, 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"