Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance by S3NS. Consulte o artigo Diferenças em relação ao Google Cloud para mais detalhes.

Esta página foi traduzida pela API Cloud Translation.

Filtros de monitorização

Este guia descreve como configurar filtros quando usa a API Monitoring. Usa filtros para especificar recursos monitorizados, tipos de métricas e séries cronológicas.

Antes de começar

Se não estiver familiarizado com métricas, séries cronológicas e recursos monitorizados, consulte o artigo Métricas, séries cronológicas e recursos.

Se não tiver experiência em etiquetas, consulte o artigo Etiquetas para uma introdução.

Usar filtros

Pode usar filtros na API Monitoring para fazer o seguinte:

Selecione os dados de séries cronológicas específicos que são devolvidos de um pedido da API list. O filtro pode selecionar intervalos temporais com base nas propriedades dos recursos monitorizados dos dados e nas propriedades das métricas. Para mais informações e exemplos, consulte o artigo Obter dados de séries cronológicas.

Indique tipos de métricas específicos. Para mais informações e exemplos, consulte o artigo Listar descritores de métricas.
Liste tipos de recursos monitorizados específicos. Para mais informações e exemplos, consulte o artigo Listar descritores de recursos monitorizados.

Seletores de filtros

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

resource: corresponde a recursos monitorizados de um tipo específico ou com valores de etiqueta específicos.
- O filtro seguinte corresponde a todos os recursos monitorizados que são instâncias de máquinas virtuais (VMs) do Compute Engine:
```
resource.type = "gce_instance"
```
metric: corresponde a um determinado tipo de métrica ou série cronológica com com uma determinada etiqueta que corresponde a um valor específico.
- O filtro seguinte corresponde a um tipo de métrica específico:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
- O filtro seguinte corresponde a séries cronológicas com uma etiqueta denominada instance_name, cujo valor começa por gke-hipster ou gke-nginx:
```
metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
```

A tabela seguinte mostra os seletores permitidos em filtros com base na chamada da API Monitoring:

Finalidade do filtro	Seletor de `resource`	Seletor de `metric`
Indicar intervalos temporais	sim	sim ^*
Liste descritores de métricas		sim
Liste os descritores de recursos monitorizados	sim

^* Quando listar séries cronológicas, tem de especificar exatamente um tipo de métrica.

As secções seguintes mostram exemplos de utilizações típicas de filtros de monitorização. Consulte a sintaxe de filtros para uma discussão completa dos objetos e operadores de filtros disponíveis.

Obter dados de intervalos temporais

Método: projects.timeSeries.list
Objetos de filtro: project, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

Uma série cronológica é uma lista de pontos de dados com indicação de data/hora de um tipo de métrica de um recurso monitorizado específico. Para ver detalhes, consulte o artigo O modelo de métricas. O tipo de métrica é especificado por um descritor de métrica e o recurso monitorizado é especificado por um descritor de recurso monitorizado.

O filtro especificado para o método timeSeries.list tem de incluir um seletor metric e esse seletor tem de especificar exatamente um tipo de métrica:

Para devolver todos os intervalos temporais de um determinado tipo de métrica:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```

Para devolver todas as séries cronológicas 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"

Devolver todas as séries cronológicas de instâncias do Compute Engine cujos nomes começam por frontend-, use o seguinte filtro:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = starts_with("frontend-")
```

Devolva todas as séries cronológicas de instâncias do Compute Engine cujos nomes comecem por 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).*")

Listar descritores de métricas

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

Use um filtro para limitar os descritores de métricas que recupera.

Por exemplo, para devolver 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 vista geral de como as métricas são denominadas, consulte as convenções de nomenclatura das métricas.

Listar descritores de recursos monitorizados

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

Use um filtro para limitar os descritores de recursos monitorizados que recupera.

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

resource.type = starts_with("pubsub")

Consulte a lista de recursos monitorizados para ver uma lista completa dos tipos de recursos monitorizados definidos pela monitorização.

Exemplos

Nos exemplos de filtragem, usamos o seguinte descritor de métrica, descritor de recurso monitorizado e instância de máquina virtual, simplificados 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 obtenção de métricas

Para pedir a utilização da largura de banda de leitura do disco para todas as instâncias e todos os dispositivos, defina um filtro da seguinte forma. Este filtro devolve, para cada instância, uma série cronológica separada que comunica a largura de banda de leitura para cada dispositivo:

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

Para refinar o pedido 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 forma. Este filtro devolve, para cada instância, no máximo uma série cronológica, consoante exista ou não um dispositivo com esse nome nessa instância:

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

Para restringir o pedido 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 de filtros

Para uma vista geral dos filtros com exemplos, consulte o artigo Usar filtros.

Um filtro de monitorização é uma string composta por até dois tipos de seletores:

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

O filtro corresponde a um item se todos os seletores incluídos corresponderem ao item. Conforme descrito nas secções seguintes, alguns seletores podem ter várias comparações unidas por AND ou OR. A ordem dos seletores no filtro não é importante, mas as comparações para diferentes seletores não podem ser misturadas.

Consoante a finalidade do filtro, determinados seletores podem ser obrigatórios, opcionais ou proibidos. Por exemplo, o filtro usado para listar séries cronológicas tem de conter um seletor de métricas.

Comparações

Os filtros e os respetivos seletores são criados a partir de comparações. Cada comparação tem o seguinte formato:

[OBJECT]: seleciona um valor a testar; uma das seguintes opções:
```
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
    
```
[KEY] é um nome, como zone ou instance_id.

[KEYSTRING] pode ser o nome, mas se contiver carateres especiais, tem de ser colocado 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 incorporada; 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 recebe um segundo argumento opcional, que especifica se a correspondência ignora a capitalização ou não. O valor predefinido é false, pelo que a correspondência predefinida é sensível a maiúsculas e minúsculas:
- Sensível a maiúsculas e minúsculas: display_name=has_substring("Demo")
- Sensível a maiúsculas e minúsculas: display_name=has_substring("Demo", false)
- Não é sensível a maiúsculas e minúsculas: display_name=has_substring("Demo", true)
Quando usado no método timeSeries.list, apenas o formulário has_substring(<string>) é suportado.

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

Pode usar os seguintes operadores para agrupar ou modificar comparações. OR tem precedência superior a AND. Os operadores têm de ser escritos em letras 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 incluí-lo.

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 filtros a determinados itens. Nas secções seguintes, são usadas chavetas para mostrar a repetição. Por exemplo, a notação <x> {OR <y>} significa que 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 filtros a recursos, ou itens associados a recursos, que têm um tipo de recurso específico ou valores de etiqueta:

<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 usar mais de um <r_label_comparison> no seletor, inclua todos entre parênteses para melhorar a legibilidade.

Seletor de métricas

Um seletor de métricas especifica determinadas métricas ou descritores de métricas limitando o tipo de métrica e as etiquetas de métricas. Quando usado com o método projects.timeSeries.list, o seletor de métricas tem de 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 seguinte filtro pode ser usado para obter uma série cronológica para uma instância de base de dados específica:

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