Esta página foi traduzida pela API Cloud Translation.

Filtros de monitoramento

Este guia descreve como configurar filtros quando você usa a API Monitoring. Você usa filtros para especificar recursos monitorados, tipos de métricas, definições de grupos, e série temporal. Também é possível usar um filtro para configurar uma política de alertas que monitora processos em execução nos sistemas. Para informações sobre esses filtros, consulte Filtros de integridade do processo.

Antes de começar

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

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 no projeto, grupo, propriedades de recursos monitorados dos dados e métricas. Para mais informações e exemplos, consulte Como recuperar dados de série temporal.

Atribua recursos a um Group com base nas propriedades dos recursos e no projeto a que pertencem. Para mais informações e exemplos, consulte Como definir a associação ao grupo.
Selecione recursos dentro de um grupo com base nas propriedades dos recursos e no projeto a que pertencem. Para mais informações e exemplos, consulte Como listar membros do grupo.

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:

project: indica quando as métricas do do projeto sejam visíveis para o projeto de um escopo de métricas mencionados no parâmetro name.

Use o seletor project quando um projeto do Google Cloud pode conferir as métricas de vários projetos do Google Cloud ou contas da AWS e você só quer métricas para um único projeto. Por exemplo, se o escopo de métricas para Project-A inclui Project-B, depois uma a correspondência ocorre quando name tem um valor de Project-A e você usa o seguinte filtro:
```
project = "Project-B"
```
group: procura os recursos que pertencem a um Group.

O filtro a seguir faz a correspondência do grupo com o identificador group-id:
```
group.id = "group-id"
    
```
resource: corresponde a recursos monitorados ou de um determinado tipo e a distribuição dos valores dos dados.
- 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"
```
- O filtro a seguir corresponde a todos os recursos com zona que começa com europe-:
```
resource.labels.zone = starts_with("europe-")
```
metric: corresponde a um específico tipo de métrica ou série temporal com 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 faz a correspondência entre série temporal com um rótulo chamado instance_name, que tem um valor que 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 `project`	Seletor de `group`	Seletor de `resource`	Seletor de `metric`
Definir grupos	sim		sim^*
Listar membros do grupo	yes		yes
Listar séries temporais	yes	sim	sim	sim ^†
Listar descritores de métrica	yes			yes
Listar descritores de recursos monitorados			sim

^* O seletor de recursos tem opções adicionais quando usado para a definição da associação ao grupo.
^† 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 (
) Filtrar objetos: project, group.id, 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 uma descritor de recurso monitorado.

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

Para retornar todas as série temporal de um tipo de métrica específico:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
Para retornar todas série temporal de um grupo específico. O seletor group só funciona com dados de série temporal alinhados. Consulte Seletor de grupo para mais informações:
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
group.id = "2468013579"
```

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"

Retorna todas as série temporal de instâncias do Compute Engine com nomes começar com frontend-, use o seguinte filtro:

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

Retorna todas as série temporal de instâncias do Compute Engine com nomes começar 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 definir a associação ao grupo

Método: projects.groups
Filtrar objetos: 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. Grupo a associação é dinâmica, mais ou menos recursos podem corresponder ao filtro a cada hora em que o filtro é avaliado. O parâmetro name na O objeto Group especifica o grupo e o projeto de escopo de um escopo de métricas metrics-scope-concept. Se o seletor project for usado no filtro, ele precisará especificar um do projeto cujas métricas sejam visíveis para o projeto do escopo.

+ Para retornar uma lista de todas as máquina virtual (VM) do Compute Engine instâncias na Europa, use o seguinte filtro:

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

Como listar membros do grupo

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

Use um filtro para limitar quais membros do grupo você recupera. O parâmetro name especifica um projeto de escopo de métricas e uma definido nesse projeto. Se o seletor project for usado no filtro, ele deve especificar um projeto com métricas visíveis para o do projeto do escopo.

Para retornar uma lista de todos os recursos de tópicos do Pub/Sub que pertencem projeto my-project, use o seguinte filtro:
```
project = "my-project" AND resource.type = "pubsub_topic"
```

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:

Para retornar somente os descritores de métrica do Compute Engine, use o seguinte filtro:
```
metric.type = starts_with("compute.googleapis.com")
```

Consulte a lista de métricas para conferir todas as opções disponíveis. tipos Para uma visão geral de como as métricas são nomeadas, consulte Nomenclatura de métricas comuns.

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:

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 os 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 de largura de banda de leitura de disco para todas as instâncias e todos os dispositivos, defina um filtro da seguinte forma. Esse filtro retorna, para cada instância, uma série temporal separadas que informam a largura de banda de leitura para cada dispositivo:

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

Refinar a solicitação para consultar a 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"

Como filtrar com grupos

Os exemplos a seguir ilustram o uso da seletor de grupo em filtros para restringir recursos monitorados aos de um grupo específico. Consulte Seletor de recursos para definições de grupo para mais informações sobre os seletores usados para definir a associação ao grupo.

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

Em uma chamada para o método projects.timeSeries.list, o filtro a seguir solicita o uso de largura de banda de leitura de disco para todos instâncias do Compute Engine em um grupo específico. O grupo precisa ser definido no projeto de escopo de um escopo 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 do filtro

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

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

    <monitoring_filter> ::=  <project_selector> AND
                             <group_selector> AND 
                             <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ários comparações unidas por AND ou OR. A ordem dos seletores no filtro não importa, mas as comparações entre seletores diferentes não devem ser se misturavam.

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étrica. No entanto, o filtro que define os recursos em um grupo não pode contêm um seletor de métrica, porque os grupos não contêm tipos de métrica ou série temporal.

Comparações

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

[OBJETO]: seleciona um valor a ser testado. 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 um nome, mas se contiver caracteres especiais, ela precisa estar entre aspas (").

[OPERATOR]: é um operador de comparação. uma das seguintes opções:

=            # 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 de o seguinte:
```
<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 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 padrão o valor é false. Portanto, a correspondência padrão diferencia maiúsculas de minúsculas:
- Diferenciar maiúsculas de minúsculas: display_name=has_substring("Demo")
- Diferenciar 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 formulário has_substring(<string>) é aceito.

O filtro monitoring.regex.full_match usa uma string de expressão regular em 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")

Somente nas definições de grupo, é possível usar o operador de negação unário, NOT, antes de uma comparação, mas não com um operador existente (:) ou antes de um expressão entre parênteses:

NOT          # negates the following comparison

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 um dos seguinte:

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

Seletor de projetos

Um seletor de projeto limita a seleção de filtro a itens que pertencem a um único projeto ou a qualquer um dos projetos de um conjunto. Cada projeto pode ser especificado por seu ID ou número:

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

Se o seletor do projeto tiver mais de uma comparação, coloque-o entre parênteses para facilitar a leitura. 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 filtro a itens que pertencem a um único grupo:

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

Por exemplo, o filtro a seguir pode ser usado para recuperar uma série temporal de cada uma das instâncias de VM em um grupo:

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

O seletor de grupo é permitido somente em filtros passados para o método projects.timeSeries.list. Além disso, a seleção de grupo requer dados alinhados; ou seja, A chamada projects.timeSeries.list precisa incluir valores para os campos perSeriesAligner e alignmentPeriod. Isso ocorre porque a associação ao grupo é, por si só, um tipo de série temporal que precisa ser agregada aos dados da métrica. Fornecer parâmetros de alinhamento permite controlar como essa junção acontece. Para mais informações sobre os parâmetros de alinhamento, consulte Agregação de dados.

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-as entre parênteses para facilitar a leitura. Por exemplo, o filtro a seguir poderia ser usado para definir um grupo que inclui 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 grupo

Seletores de recursos usados para definir extensões de uso de associação de grupo para a sintaxe <resource_selector>:

Você inclui filtros com base no valor dos rótulos do sistema de metadados, metadata.system_labels.[KEY], além de marcadores de usuário de metadados, metadata.user_labels.[KEYSTRING]. Recomendamos citar o valor chaves para metadata.user_labels porque podem conter caracteres caracteres como hifens.

Quando um seletor contém um filtro de metadados e um de recurso, precisa combiná-las com AND; não será possível usar OR. Por exemplo, um gráfico com o seletor a seguir exibe o uso de CPU para todas instâncias 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")
```
Use o operador de "não iguais" (!=) para comparar tipos de recursos, rótulos de recursos e metadados. O operador pode ser usado para comparar strings, números, booleanos ou as funções de substring. Por exemplo, resource.type!=starts_with("gce") será verdadeiro se o tipo de recurso não começar com "gce".
É possível usar um único operador NOT antes de qualquer comparação de recursos. Por exemplo, NOT resource.labels.zone="europe" será verdadeiro se a zona do recurso não incluir "europe". Não é possível usar NOT antes um operador existe (:) ou uma expressão entre parênteses.
É possível usar o atributo "existe" (:) para testar a existência de chaves. Por exemplo, a comparação resource.labels:zone será verdadeira se o rótulo a chave zone está presente no recurso.

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

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

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étrica 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 um horário 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")