O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Filtros de monitoramento

Os filtros na API Cloud Monitoring permitem selecionar série temporal, tipos de métricas e recursos monitorados específicos em solicitações de API.

Antes de começar

Se você não conhece 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:

Selecione os dados de série temporal específicos que são retornados de uma solicitação de API list. O filtro pode selecionar série temporal com base nas propriedades de recursos monitorados e de métricas dos dados. Para mais informações e exemplos, consulte Como recuperar dados de série temporal.

Liste determinados tipos de métrica. Para mais informações e exemplos, consulte Como listar descritores de métrica.
Listar determinados tipos de recursos monitorados. Para mais informações e exemplos, consulte Como listar descritores de recursos monitorados.

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ífico 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, é preciso 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
Objetos de filtro: 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, e esse seletor precisa especificar exatamente um tipo de métrica:

Para retornar todas série temporal de um tipo de métrica específico, use o seguinte filtro:
```
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"

Para retornar todas série temporal de instâncias do Compute Engine com nomes que começam com frontend-, use o seguinte filtro:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = starts_with("frontend-")
```

Para retornar todas as série temporal de instâncias do Compute Engine com nomes que começam com gke-hipster ou gke-nginx, use 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 os descritores de métricas que você recupera.

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

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

Consulte a 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 a 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 provided 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 de 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 de cada dispositivo:

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

Para refinar a solicitação de 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-a:

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 que consiste em 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 para seletores diferentes não podem ser misturadas.

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 conter 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, que pode ser um dos seguintes:
```
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
    
```
[KEY] é um nome, como zone ou instance_id.

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

[OPERATOR]: um operador de comparação, que pode ser 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; uma das seguintes opções:
```
<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 usa um segundo argumento opcional, que especifica se a correspondência ignora maiúsculas e minúsculas 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, somente o formato has_substring(<string>) é aceito.

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

(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 você pode escrever qualquer uma das seguintes opções:

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

Filtros de monitoramento Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Como usar filtros

Seletores de filtros

Como recuperar dados de séries temporais

Como listar descritores de métrica

Como listar descritores de recursos monitorados

Exemplos

Exemplos de recuperação de métrica

Referência: sintaxe do filtro

Comparações

Seletores de filtros

Seletor de recursos

Seletor de métricas

Filtros de monitoramento