Monitoring-Filter

In diesem Leitfaden wird beschrieben, wie Sie Filter konfigurieren, wenn Sie die Monitoring API verwenden. Mit Filtern geben Sie überwachte Ressourcen, Messwerttypen und Zeitachsen an.

Hinweise

Wenn Sie mit Messwerten, Zeitachsen und überwachten Ressourcen nicht vertraut sind, lesen Sie den Abschnitt 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 Zeitachsendaten aus, die von einer list-API-Anfrage zurückgegeben werden. Mit dem Filter können Zeitachsen basierend auf den Eigenschaften der überwachten Ressource und den Messwerteigenschaften der Daten ausgewählt werden. Weitere Informationen und Beispiele finden Sie unter Zeitachsendaten abrufen.

Die Auswahl filtern

Ein Filter besteht aus mindestens einem Selektor, der ein Filter-Keyword ist. Die folgenden Beispiele veranschaulichen die verschiedenen Selektoren:

  • resource: Stimmt mit überwachten Ressourcen eines bestimmten Typs oder mit bestimmten Labelwerten überein.

    • Der folgende Filter stimmt mit allen überwachten Ressourcen überein, bei denen es sich um Compute Engine-VM-Instanzen handelt:

      resource.type = "gce_instance"
  • metric: Stimmt mit einem bestimmten Messwerttyp oder einer Zeitachse mit einem bestimmten Label überein, das mit einem bestimmten Wert übereinstimmt.

    • Der folgende Filter entspricht einem bestimmten Messwerttyp:

      metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    • Der folgende Filter stimmt mit Zeitachsen mit einem Label namens instance_name überein, dessen Wert mit gke-hipster oder gke-nginx beginnt:

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

In der folgenden Tabelle sehen Sie, welche Selektoren in Filtern je nach Monitoring API-Aufruf zulässig sind:

Zweck des Filters resource-Selektor metric-Selektor
Zeitachsen auflisten Ja Ja *
Messwertdeskriptoren auflisten Ja
Listen Sie überwachte Ressourcendeskriptoren auf. Ja
* 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
Filterobjekte: project, 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 für die timeSeries.list-Methode angegebene Filter muss einen metric-Selektor enthalten, der genau einen Messwerttyp angibt:

  • So geben Sie alle Zeitachsen für einen bestimmten Messwerttyp zurück:
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • 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"
    

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

  • Verwenden Sie den folgenden Filter, um alle Zeitachsen von Compute Engine-Instanzen zurückzugeben, deren Namen 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).*")
    

Messwertdeskriptoren auflisten

Methode: projects.metricDescriptors.list
Filterobjekte: project, metric.type

Verwenden Sie einen Filter, um einzuschränken, welche Messwertdeskriptoren Sie abrufen.

Wenn Sie beispielsweise nur die Compute Engine-Messwertdeskriptoren zurückgeben möchten, verwenden Sie den 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 Namenskonventionen für Messwerte.

Ü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 beispielsweise nur die überwachten Ressourcendeskriptoren für Pub/Sub abrufen möchten, verwenden Sie den folgenden Filter:

resource.type = starts_with("pubsub")

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

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. Dieser Filter gibt für jede Instanz eine separate Zeitachse zurück, 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"

Referenz: Filtersyntax

Eine Übersicht über Filter mit Beispielen finden Sie unter Filter verwenden.

Ein Monitoring-Filter ist ein String, der aus bis zu zwei Selektortypen besteht:

    <monitoring_filter> ::= <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. Die Reihenfolge der Selektoren im Filter spielt keine Rolle, aber Vergleiche für verschiedene Selektoren dürfen nicht miteinander vermischt werden.

Je nach Zweck des Filters können bestimmte Selektoren erforderlich, optional oder unzulässig sein. Der Filter zum Auflisten von Zeitachsen muss beispielsweise eine Messwertauswahl enthalten.

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:

    metric.type
    metric.labels.[KEY]
    resource.type
    resource.labels.[KEY]
        

    [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]: Ein Literalwert oder ein integrierter Funktionsaufruf, einer der folgenden:

    <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 Methode 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ß-/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 Methode timeSeries.list wird nur das Formular has_substring(<string>) unterstützt.

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

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

(x = "a" OR x = "b" OR x = "c")

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

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 Selektor verwenden, setzen Sie diese zur besseren Lesbarkeit in Klammern.

Messwertauswahl

Eine Messwertauswahl gibt bestimmte Messwerte oder Messwertdeskriptoren an, indem der Messwerttyp und die Messwertlabels begrenzt werden. Bei Verwendung mit der Methode projects.timeSeries.list 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_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>}

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