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, definições de grupos e séries cronológicas. Também pode usar um filtro para configurar uma política de alerta que monitoriza os processos em execução nos seus sistemas. Para informações sobre esses filtros, consulte Filtros de estado de funcionamento dos processos.

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 no projeto, no grupo, nas propriedades de recursos monitorizados e nas propriedades de métricas dos dados. Para mais informações e exemplos, consulte o artigo Obter dados de séries cronológicas.

Atribua recursos a um Group com base nas propriedades dos recursos e no projeto ao qual pertencem. Para mais informações e exemplos, consulte o artigo Definir a associação a grupos.
Selecione recursos num grupo com base nas propriedades dos recursos. Para mais informações e exemplos, consulte o artigo Membros do grupo de fichas.

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:

project: Corresponde quando as métricas do projeto especificado são visíveis para o projeto de âmbito de um âmbito de métricas mencionado no parâmetro name.

Use o seletor project quando um Google Cloud projeto pode ver as métricas de vários Google Cloud projetos ou contas da AWS e só quer métricas para um único projeto. Por exemplo, se o âmbito das métricas para Project-A incluir Project-B, ocorre uma correspondência quando name tem um valor de Project-A e usa o seguinte filtro:
```
project = "Project-B"
```
group: corresponde a recursos pertencentes a um Group.

O seguinte filtro corresponde ao grupo com o identificador group-id:
```
group.id = "group-id"
    
```
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"
```
- O filtro seguinte corresponde a todos os recursos cuja zona começa com europe-:
```
resource.labels.zone = starts_with("europe-")
```
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 `project`	Seletor de `group`	Seletor de `resource`	Seletor de `metric`
Defina grupos	sim		sim^*
Liste os membros do grupo	sim		sim
Indicar intervalos temporais	sim	sim	sim	sim ^†
Liste descritores de métricas	sim			sim
Liste os descritores de recursos monitorizados			sim

^* O seletor de recursos tem opções adicionais quando usado para definir a subscrição de grupos.
^† 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, group.id, 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 um grupo específico. O seletor group só funciona com dados de séries cronológicas alinhados. Consulte o seletor de grupos para mais informações:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
group.id = "2468013579"
```

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

Definir a adesão ao grupo

Método: projects.groups.create
Objetos de filtro: project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

Um grupo pode conter qualquer número de recursos, conforme especificado por um filtro. A associação ao grupo é dinâmica. Mais ou menos recursos podem corresponder ao filtro sempre que o filtro é avaliado. O parâmetro name no objeto Group especifica o grupo e o projeto de âmbito de uma métrica. Se o seletor project for usado no filtro, tem de especificar um projeto cujas métricas sejam visíveis para o projeto de âmbito.

Por exemplo, para criar um grupo que inclua apenas instâncias de máquinas virtuais (VMs) do Compute Engine na Europa, use o seguinte filtro:

resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")

Para obter informações sobre os métodos da API que pode usar para eliminar, atualizar ou listar grupos, consulte a página de referência da API projects.groups.

Membros do grupo de fichas

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

O parâmetro name especifica um projeto de âmbito de um âmbito de métricas e um grupo definido nesse projeto. Se não especificar um filtro, projects.groups.members.list devolve uma lista dos membros do grupo.

Pode usar um filtro para limitar os membros do grupo que recupera. Se o filtro incluir um seletor project, o valor do seletor tem de especificar um projeto cujas métricas sejam visíveis para o projeto de âmbito. Se for especificado um valor inválido, o seletor project é ignorado.

Por exemplo, suponha que cria um grupo que inclui todos os recursos cujo nome contém test. Para listar apenas os membros do grupo que são tópicos do Pub/Sub, use o seguinte filtro:

resource.type = "pubsub_topic"

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"

Filtragem com grupos

Os exemplos seguintes ilustram a utilização do seletor de grupos em filtros para restringir os recursos monitorizados aos de um grupo específico. Consulte o seletor de recursos para definições de grupos para ver informações sobre os seletores usados para definir a associação a grupos.

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

Numa chamada ao método projects.timeSeries.list, o filtro seguinte pede a utilização da largura de banda de leitura do disco para todas as instâncias do Compute Engine num grupo específico. O grupo tem de ser definido no projeto de âmbito de um âmbito de métricas especificado no parâmetro name do método:

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

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é quatro tipos de seletores:

    <monitoring_filter> ::=  <project_selector> AND
                             <group_selector> AND
                             <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. No entanto, o filtro que define os recursos num grupo não pode conter um seletor de métricas, porque os grupos não contêm tipos de métricas nem séries cronológicas.

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:
```
project
group.id
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
metadata.system_labels.[KEY]
metadata.user_labels.[KEYSTRING]
    
```
[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")

Apenas nas definições de grupos, pode usar o operador de negação unário, NOT, antes de uma comparação, mas não com um operador exists (:) ou antes de uma expressão entre parênteses:

NOT          # negates the following comparison

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 projetos

Um seletor de projetos limita a seleção de filtros a itens pertencentes a um único projeto ou a qualquer um de um conjunto de projetos. Cada projeto pode ser especificado pelo respetivo ID ou número:

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

Se o seletor de projetos tiver mais do que uma única comparação, inclua todo o seletor entre parênteses para melhorar a legibilidade. Por exemplo:

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

Seletor de grupos

Um seletor de grupos limita a seleção de filtros a itens pertencentes a um único grupo:

<group_selector> ::= group.id '=' <string>

Por exemplo, o filtro seguinte pode ser usado para obter uma série cronológica de cada uma das instâncias de VM num grupo:

group.id = 12345 AND
resource.type = "gce_instance" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

O seletor de grupos só é permitido em filtros transmitidos ao método projects.timeSeries.list. Além disso, a seleção de grupos requer dados alinhados, ou seja, a chamada projects.timeSeries.list tem de incluir valores para os campos perSeriesAligner e alignmentPeriod. Isto deve-se ao facto de a associação a grupos ser, em si mesma, um tipo de série cronológica que tem de ser associada aos dados das métricas, e o fornecimento de parâmetros de alinhamento dá-lhe controlo sobre a forma como essa associação ocorre. Para mais informações sobre os parâmetros de alinhamento, consulte o artigo Agregação de dados.

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. Por exemplo, o filtro seguinte pode ser usado para definir um grupo que inclua todas as instâncias de VM do Compute Engine nos EUA e na Europa.

resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))

Seletor de recursos para definições de grupos

Os seletores de recursos usados para definir a associação a grupos usam extensões à sintaxe <resource_selector>:

Inclui filtros com base no valor das etiquetas do sistema de metadados, metadata.system_labels.[KEY], e etiquetas do utilizador de metadados, metadata.user_labels.[KEYSTRING]. Recomendamos que coloque as chaves entre aspas para metadata.user_labels, uma vez que podem conter carateres especiais, como hífens.

Quando um seletor contém um filtro de metadados e um filtro de recursos, tem de combiná-los com AND. Não pode usar OR. Por exemplo, um gráfico com o seguinte seletor apresenta a utilização da CPU para todas as instâncias de VM com um tipo de máquina de e2-medium ou e2-micro:
```
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")
```
Pode usar o operador diferente de (!=) para comparar tipos de recursos, etiquetas de recursos e metadados. O operador pode ser usado quando compara strings, números, valores booleanos ou as funções de substring. Por exemplo, resource.type!=starts_with("gce") é verdadeiro se o tipo de recurso não começar com "gce".
Pode usar um único operador NOT antes de uma comparação de recursos. Por exemplo, NOT resource.labels.zone="europe" é verdadeiro se a zona do recurso não incluir "europe". Não pode usar NOT antes de um operador exists (:) ou uma expressão entre parênteses.
Pode usar o operador "exists" (:) para testar a existência de chaves. Por exemplo, a comparação resource.labels:zone é verdadeira se a chave da etiqueta zone estiver presente no recurso.

Por exemplo, uma das chaves de metadados de recursos da plataforma para instâncias de VM é spot_instance. O seletor de filtros seguinte escolhe instâncias que são instâncias de spot:

resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

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

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

Antes de começar

Usar filtros

Seletores de filtros

Obter dados de intervalos temporais

Definir a adesão ao grupo

Membros do grupo de fichas

Listar descritores de métricas

Listar descritores de recursos monitorizados

Exemplos

Exemplos de obtenção de métricas

Filtragem com grupos

Referência: sintaxe de filtros

Comparações

Seletores de filtros

Seletor de projetos

Seletor de grupos

Seletor de recursos

Seletor de recursos para definições de grupos

Seletor de métricas

Filtros de monitorização