Filtros de monitoramento

Este guia descreve como configurar filtros quando você usa a API Monitoring. Os filtros são usados para especificar recursos monitorados, tipos de métricas e série temporal.

Antes de começar

Se você não estiver familiarizado com métricas, série temporal e recursos monitorados, consulte Métricas, série temporal e recursos.

Se você não estiver familiarizado com rótulos, consulte Rótulos para uma introdução.

Como usar filtros

É possível usar filtros na API Monitoring para fazer o seguinte:

Seletores de filtros

Um filtro consiste em pelo menos um seletor, que é uma palavra-chave de filtro. Os exemplos a seguir ilustram os diferentes seletores:

  • resource: corresponde a recursos monitorados de um tipo específico ou com valores de rótulo específicos.

    • O filtro a seguir corresponde a todos os recursos monitorados que são instâncias de máquina virtual (VM) do Compute Engine:

      resource.type = "gce_instance"

  • metric: corresponde a um tipo de métrica ou série temporal específica com um rótulo específico que corresponde a um valor específico.

    • O filtro a seguir corresponde a um tipo de métrica específico:

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

    • O filtro a seguir corresponde a série temporal com um rótulo chamado instance_name, cujo valor começa com gke-hipster ou gke-nginx:

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

A tabela a seguir mostra quais seletores são permitidos em filtros com base na chamada da API Monitoring:

Finalidade do filtro Seletor de resource Seletor de metric
Listar séries temporais sim sim *
Listar descritores de métrica yes
Listar descritores de recursos monitorados sim
* Ao listar série temporal, você precisa especificar exatamente um tipo de métrica.

As seções a seguir mostram exemplos de usos típicos de filtros de monitoramento. Consulte Sintaxe de filtro para uma discussão completa sobre os objetos e operadores de filtro disponíveis.

Como recuperar dados de séries temporais

Método: projects.timeSeries.list
Filtrar objetos: project, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

Uma série temporal é uma lista de pontos de dados com carimbo de data/hora de um tipo de métrica de um recurso monitorado específico. Para mais detalhes, consulte O modelo de métrica. O tipo de métrica é especificado por um descritor de métrica, e o recurso monitorado é especificado por um descritor de recurso monitorado.

O filtro especificado para o método timeSeries.list precisa incluir um seletor metric, que precisa especificar exatamente um tipo de métrica:

  • Para retornar todas as série temporal de um determinado tipo de métrica: 
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"

  • Para retornar todas as série temporal de uma instância específica do Compute Engine, use o seguinte filtro: 

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

  • Retorne todas as série temporal de instâncias do Compute Engine com nomes que começam com frontend-: 

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

  • Retorne todas as série temporal de instâncias do Compute Engine em que os nomes começam com gke-hipster ou gke-nginx usando o seguinte filtro: 

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")

Como listar descritores de métrica

Método: projects.metricDescriptors.list
Filtrar objetos: project, metric.type

Use um filtro para limitar quais descritores de métrica você recupera.

Por exemplo, para retornar apenas os descritores de métrica do Compute Engine, use o seguinte filtro: 

metric.type = starts_with("compute.googleapis.com")

Consulte Lista de métricas para ver uma lista completa dos tipos de métricas disponíveis. Para uma visão geral de como as métricas são nomeadas, consulte Convenções de nomenclatura de métricas.

Como listar descritores de recursos monitorados

Método: projects.monitoredResourceDescriptors.list
Filtrar objetos: resource.type

Use um filtro para limitar os descritores de recursos monitorados que você recupera.

Por exemplo, para recuperar apenas os descritores de recursos monitorados do Pub/Sub, use o seguinte filtro: 

resource.type = starts_with("pubsub")

Consulte Lista de recursos monitorados para ver uma lista completa dos tipos de recursos monitorados definidos pelo Monitoring.

Exemplos

Nos exemplos de filtragem, usamos o seguinte descritor de métrica, descritor de recurso monitorado e instância de máquina virtual, simplificado para ilustração:

    # 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" }

Exemplos de recuperação de métrica

Para solicitar o uso da largura de banda de leitura do disco para todas as instâncias e todos os dispositivos, defina um filtro da seguinte maneira. Esse filtro retorna, para cada instância, uma série temporal separada que informa a largura de banda de leitura para cada dispositivo:

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

Para refinar a solicitação da consulta da largura de banda de leitura apenas para o dispositivo de disco conhecido como "log_partition" em cada instância, defina o filtro da seguinte maneira. Esse filtro retorna, para cada instância, no máximo uma série temporal, dependendo da existência de um dispositivo com esse nome:

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

Para restringir a solicitação a uma única instância, especifique essa instância:

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"

Referência: sintaxe do filtro

Para uma visão geral dos filtros com exemplos, consulte Como usar filtros.

Um filtro de monitoramento é uma string com até dois tipos de seletores:

    <monitoring_filter> ::= <resource_selector> AND
                             <metric_selector>

O filtro corresponderá a um item se todos os seletores incluídos corresponderem ao item. Conforme descrito nas seções a seguir, alguns seletores podem ter várias comparações unidas por AND ou OR. A ordem dos seletores no filtro não importa, mas as comparações de diferentes seletores não podem ser mescladas.

Dependendo da finalidade do filtro, alguns seletores podem ser obrigatórios, opcionais ou proibidos. Por exemplo, o filtro usado para listar série temporal precisa ter um seletor de métricas.

Comparações

Os filtros e os seletores são criados com base em comparações. Cada comparação tem o seguinte formato:

  • [OBJECT]: seleciona um valor a ser testado, um dos seguintes:

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

    [KEY] é um nome, como zone ou instance_id.

    [KEYSTRING] pode ser nome, mas, se tiver caracteres especiais, precisará estar entre aspas (").

  • [OPERATOR]: um operador de comparação, um dos seguintes:

    =            # equality (case-sensitive)
> < >= <=    # numeric ordering
!=           # not equal
:            # "has" substring match and test for key (case-sensitive)

  • [VALUE]: um valor literal ou uma chamada de função integrada; um dos seguintes:

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

    Exceto quando usado no método timeSeries.list, o filtro has_substring tem um segundo argumento opcional, que especifica se a correspondência ignora o caso ou não. O valor padrão é false, então, a correspondência padrão diferencia maiúsculas de minúsculas:

    • Diferencia maiúsculas de minúsculas: display_name=has_substring("Demo")
    • Diferencia maiúsculas de minúsculas: display_name=has_substring("Demo", false)
    • Não diferencia maiúsculas de minúsculas: display_name=has_substring("Demo", true)

    Quando usado no método timeSeries.list, apenas o formulário has_substring(<string>) é compatível.

    O filtro monitoring.regex.full_match usa uma string de expressão regular na sintaxe RE2.

É possível usar os seguintes operadores para agrupar ou modificar comparações. OR tem maior precedência do que AND. Os operadores precisam ser escritos em maiúsculas:

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

O operador AND pode ser omitido entre operadores, mas é mais claro e menos propenso a erros.

A comparação x = one_of("a", "b", "c") é equivalente a:

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

Seletores de filtros

Use seletores para limitar as seleções de filtro a determinados itens. Nas seções a seguir, as chaves são usadas para mostrar a repetição. Por exemplo, a notação <x> {OR <y>} significa que é possível escrever qualquer uma das opções a seguir:

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

Seletor de recursos

Um seletor de recursos limita a seleção de filtro a recursos (ou itens associados a recursos) que têm um tipo de recurso ou valores de rótulo específicos:

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

Se você usar mais de um <r_label_comparison> no seletor, coloque-os entre parênteses para facilitar a leitura.

Seletor de métricas

Um seletor de métrica especifica determinadas métricas ou descritores de métrica limitando o tipo e os rótulos das métricas. Quando usado com o método projects.timeSeries.list, o seletor de métricas precisa especificar um único tipo de métrica:

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

Por exemplo, o filtro a seguir pode ser usado para recuperar uma série temporal para uma instância de banco de dados específica:

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