Monitoring-Filter

In diesem Leitfaden wird beschrieben, wie Sie Filter bei der Verwendung der Monitoring API konfigurieren. Sie verwenden Filter, um überwachte Ressourcen, Messwerttypen, Gruppendefinitionen und Zeitreihen. Sie können auch einen Filter verwenden, um eine Benachrichtigungsrichtlinie zu konfigurieren, Monitore auf Ihren Systemen ausgeführt werden. Informationen zu diesen Filtern Siehe Process-health-Filter.

Hinweise

Wenn Sie mit Messwerten, Zeitachsen und überwachten Ressourcen nicht vertraut sind, lesen Sie den Hilfeartikel 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 der von einer list-API-Anfrage zurückgegeben wurde. Mit dem Filter können Zeitreihen ausgewählt werden basierend auf dem Projekt, der Gruppe, den Eigenschaften der überwachten Ressourcen und Messwert-Properties. 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.

Die Auswahl filtern

Ein Filter besteht aus mindestens einem Selektor, bei dem es sich um ein Filter-Keyword handelt. Die folgenden 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 Parameter name erwähnt wird.

    Verwenden Sie die Auswahl project, wenn in einem Google Cloud-Projekt die Messwerte mehrerer Google Cloud-Projekte oder AWS-Konten angezeigt werden können und Sie nur Messwerte für ein einzelnes Projekt benötigen. Wenn beispielsweise Messwertbereich für Project-A beinhaltet Project-B, dann Übereinstimmung tritt auf, wenn name den Wert Project-A und Sie verwenden den folgenden Filter:

    project = "Project-B"
  • group: Stimmt mit Ressourcen überein, die zu einer Group gehören.

    Der folgende Filter stimmt mit der Gruppe mit der ID group-id:

    group.id = "group-id"
        
  • resource: Stimmt mit überwachten Ressourcen eines bestimmten Typs oder mit bestimmten Labelwerten überein.

    • Der folgende Filter stimmt mit allen überwachten Ressourcen überein, die sind Compute Engine-VM-Instanzen:

      resource.type = "gce_instance"
    • Der folgende Filter stimmt mit allen Ressourcen überein, deren Zone beginnt mit europe-:

      resource.labels.zone = starts_with("europe-")
  • metric: entspricht einem bestimmten Messwerttyp oder Zeitachse mit mit einem bestimmten Label, das einem bestimmten Wert entspricht.

    • Der folgende Filter entspricht einem bestimmten Messwerttyp:

      metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    • Der folgende Filter gleicht Zeitreihen mit einem Label namens instance_name, deren Wert mit beginnt gke-hipster oder gke-nginx:

      metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

In der folgenden Tabelle sehen Sie, welche Selektoren in Filtern zulässig sind. den Aufruf der Monitoring API:

Zweck des Filters project-Selektor group-Selektor resource-Auswahl metric-Auswahl
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, wenn sie für zum Definieren 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
Objekte filtern: project, group.id, resource.type, resource.labels.[KEY], metric.type metric.labels.[KEY]

Eine Zeitreihe ist eine Liste von Datenpunkten eines Messwerttyps, bestimmte überwachte Ressource. Weitere Informationen finden Sie unter Messwertmodell. Der Messwerttyp wird durch einen Messwertdeskriptor angegeben. wird die überwachte Ressource durch einen Deskriptor der überwachten Ressource.

Der für die Methode timeSeries.list angegebene Filter muss Folgendes enthalten: metric-Auswahl. Diese Auswahl muss genau einen Messwerttyp angeben:

  • So geben Sie alle Zeitreihen für einen bestimmten Messwerttyp zurück:
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Alle Zeitreihen für eine bestimmte Gruppe zurückgeben 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"
    
  • Verwenden Sie den folgenden Filter, um alle Zeitachsen einer bestimmten Compute Engine-Instanz zurückzugeben:

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

  • Alle Zeitachsen von Compute Engine-Instanzen zurückgeben, deren Namen mit frontend- beginnen, verwenden Sie folgenden Filter:

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

  • Alle Zeitachsen von Compute Engine-Instanzen zurückgeben, deren Namen die mit gke-hipster oder gke-nginx beginnen, verwenden Sie folgenden Filter:

    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. Gruppe Mitgliedschaft ist dynamisch; mehr oder weniger Ressourcen entsprechen möglicherweise dem Filter alle Zeitpunkt der Filterauswertung. Der Parameter name im Objekt Group gibt die Gruppe und das Scoping-Projekt eines Messwertbereichsmetrics-scope-concept an. Wenn der project-Selektor im Filter verwendet wird, muss er einen Projekt, dessen Metriken für das den Umfang festlegende Projekt sichtbar sind.

+ Um eine Liste aller virtuellen Maschinen (VMs) in Compute Engine zurückzugeben verwenden, verwenden Sie den folgenden Filter:
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 name-Parameter gibt ein Umfangsprojekt eines Messwertbereichs und ein die in diesem Projekt definiert ist. Wenn der Selektor project im Filter verwendet wird, muss er ein Projekt angeben, dessen Messwerte für das Scoping-Projekt sichtbar sind.

  • Um eine Liste aller Pub/Sub-Themenressourcen zurückzugeben, die zu Projekt my-project verwenden, verwenden Sie folgenden Filter:
    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:

  • Um nur die Compute Engine-Messwertdeskriptoren zurückzugeben, verwenden Sie folgenden Filter:
    metric.type = starts_with("compute.googleapis.com")
    

Eine vollständige Liste der verfügbaren Messwerttypen finden Sie unter Messwertliste. Eine Übersicht über die Benennung von Messwerten finden Sie unter Benennung von Messwerten .

Überwachte Ressourcendeskriptoren auflisten

Methode: projects.monitoredResourceDescriptors.list
Objekte filtern: resource.type

Verwenden Sie einen Filter, um einzuschränken, welche überwachten Ressourcendeskriptoren Sie abrufen:

  • Wenn Sie nur die von Pub/Sub überwachten Ressourcendeskriptoren abrufen möchten, verwenden Sie den folgenden Filter:
    resource.type = starts_with("pubsub")
    

Eine vollständige Liste der überwachten Ressourcen finden Sie in der Liste der überwachten Ressourcen. Die von Monitoring definierten überwachten Ressourcentypen.

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 zum Lesen von Laufwerken für alle Instanzen und Geräte anzufordern, definieren Sie einen Filter wie folgt. Dieser Filter gibt für jede Instanz separaten Zeitreihen, die die Lesebandbreite für jedes Gerät melden:

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Zur Verfeinerung der Anfrage, um nur die Lesebandbreite für das Laufwerkgerät abzufragen bekannt als „log_partition“ definieren Sie den Filter für jede Instanz wie folgt. Dieser Filter gibt für jede Instanz maximal 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 des Gruppenauswahl in Filtern zum Einschränken überwachter Ressourcen einer bestimmten Gruppe zugeordnet werden. Weitere Informationen finden Sie unter Ressourcenauswahl für Gruppendefinitionen finden Sie Informationen zu den Auswahlelementen, die zum Definieren der Gruppenmitgliedschaft verwendet werden.

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

In einem Aufruf der Methode projects.timeSeries.list fordert der folgende Filter die Bandbreitennutzung für alle Compute Engine-Instanzen in einer bestimmten Gruppe. 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"

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 einige Selektoren mehrere Vergleiche verbunden durch AND oder OR. Die Reihenfolge der Selektoren in der Filter keine Rolle, aber Vergleiche für verschiedene Selektoren dürfen nicht vermischt.

Je nach Zweck des Filters können bestimmte Selektoren erforderlich, optional oder unzulässig sein. Der Filter, mit dem Zeitreihen aufgelistet werden, muss eine Messwertauswahl enthalten. Mit dem Filter, der die Ressourcen in einer Gruppe definiert, eine Messwertauswahl enthalten, weil Gruppen keine Messwerttypen oder Zeitreihe.

Vergleiche

Filter und ihre Selektoren werden aus Vergleichen erstellt. Jeder Vergleich hat das folgende Format:

  • [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, z. B. zone oder instance_id.

    [KEYSTRING] kann ein Name sein, aber wenn er Sonderzeichen enthält, dann muss es in Anführungszeichen gesetzt werden (").

  • [OPERATOR]: ein Vergleichsoperator eines der folgenden:

    =            # equality (case-sensitive)
    > < >= <=    # numeric ordering
    !=           # not equal
    :            # "has" substring match and test for key (case-sensitive)
        
  • [VALUE]: ein Literalwert oder ein integrierter Funktionsaufruf. einer von Folgendes:

    <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>)
        

    Außer bei Verwendung in der timeSeries.list-Methode gilt: Für den has_substring-Filter wird ein optionales zweites Argument verwendet, gibt an, ob bei der Übereinstimmung die Groß-/Kleinschreibung ignoriert wird. Standardeinstellung Der Wert ist false. Bei der Standardübereinstimmung wird also zwischen Groß- und Kleinschreibung unterschieden:

    • Groß-/Kleinschreibung beachten: display_name=has_substring("Demo")
    • Groß-/Kleinschreibung beachten: display_name=has_substring("Demo", false)
    • Groß- und Kleinschreibung wird nicht berücksichtigt: display_name=has_substring("Demo", true)

    Bei Verwendung in der timeSeries.list-Methode wird nur das has_substring(<string>)-Format unterstützt.

    Der Filter monitoring.regex.full_match nimmt eine String für regulären Ausdruck in 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.

Die Vergleichs-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. Beispiel: bedeutet die Notation <x> {OR <y>}, dass Sie alle Folgendes:

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

<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 kann beispielsweise verwendet werden, um eine Zeitachse aus jeder VM-Instanz in einer Gruppe:

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 die Methode 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 die Felder perSeriesAligner und alignmentPeriod enthalten. Das liegt daran, dass die Gruppenmitgliedschaft eine Art Zeitreihe, die mit den Messwertdaten verknüpft werden muss. Mit Ausrichtungsparametern können Sie steuern, wie dieser Join 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> ')'

<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
                       | resource.labels.[KEY] ':' <string>
                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
                              | <r_label_comparison> {OR <r_label_comparison>}

Wenn Sie mehrere <r_label_comparison> im Selector verwenden, setzen Sie diese zur besseren Lesbarkeit in Klammern. Der folgende Filter könnte beispielsweise verwendet werden, um eine Gruppe zu definieren, die Folgendes enthält: alle Compute Engine-VM-Instanzen in den USA und Europa.

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 nehmen Filter auf Basis des Werts von Metadatensystem-Labels, metadata.system_labels.[KEY] und Metadaten-Nutzerlabels metadata.user_labels.[KEYSTRING]. Wir empfehlen, Schlüssel für metadata.user_labels, da sie besondere wie Bindestriche verwenden.

    Wenn ein Selektor einen Metadatenfilter und einen Ressourcenfilter enthält, müssen mit AND kombiniert werden. Sie können OR nicht verwenden. In einem Diagramm mit der folgenden Auswahl wird beispielsweise die CPU-Auslastung für alle VM-Instanzen mit dem Maschinentyp e2-medium oder e2-micro angezeigt:

    metric.type="compute.googleapis.com/instance/cpu/utilization"
    resource.type="gce_instance" AND
    (metadata.system_labels."machine_type"="e2-medium" OR
    metadata.system_labels."machine_type"="e2-micro")
    
  • 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. Für Beispiel: NOT resource.labels.zone="europe" ist „true“, wenn die die Zone der Ressource "europe" nicht enthält. Sie können NOT erst verwenden, wenn Sie Ein Exist-Operator (:) oder ein Ausdruck in Klammern.

  • Mit dem Feld „exists“ Operator (:), um das Vorhandensein von Schlüsseln zu prüfen. Beispielsweise ist der Vergleichs-resource.labels:zone „true“, wenn das Label Schlüssel zone ist in der Ressource vorhanden.

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. Bei Verwendung mit dem projects.timeSeries.list-Methode, Die Messwertauswahl muss einen einzelnen Messwerttyp angeben:

<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_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>

<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

Der folgende Filter könnte z. B. verwendet werden, um eine Uhrzeit abzurufen, für eine bestimmte Datenbankinstanz:

metric.type = "cloudsql.googleapis.com/database/state" AND
(metric.labels.resource_type = "instance" AND
 metric.labels.resource_id = "abc-123456")