Filtros de monitoramento

Este guia descreve o uso de filtros de monitoramento para especificar recursos monitorados, tipos de métricas, definições de grupos e séries temporais.

Para uma introdução a métricas, séries temporais e recursos monitorados, consulte Métricas, séries temporais e recursos.

Os filtros fazem amplo uso de rótulos. Consulte Rótulos para saber mais.

Como usar filtros

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

  • Recuperar série temporal. Use um filtro para selecionar dados de série temporal com base no projeto, no grupo, nas propriedades de recursos monitorados e nas propriedades da métrica. Para mais informações e exemplos, consulte Como recuperar dados de série temporal.

  • Definir os recursos em um grupo. Use um filtro para atribuir recursos a um Group com base nas propriedades dos recursos e no projeto em que eles pertencem. Para mais informações e exemplos, consulte Como definir a associação ao grupo.

  • Listar membros do grupo. Use um filtro para selecionar recursos em um grupo com base nas propriedades dos recursos e no projeto a que eles pertencem. Para mais informações e exemplos, consulte Como listar membros do grupo.

  • Listar descritores de métrica. Use um filtro para inspecionar tipos de métricas específicos das centenas de tipos definidos no Monitoring. Para mais informações e exemplos, consulte Como listar descritores de métrica.

  • Listar descritores de recursos monitorados. Use um filtro para inspecionar determinados tipos de recursos monitorados das dezenas de tipos definidos no Monitoring. Para mais informações e exemplos, consulte Como listar descritores de recursos monitorados.

Dependendo de qual das operações anteriores você está restringindo, seu filtro pode consistir no AND lógico dos seletores na lista a seguir. Estes exemplos são simples: há vários tipos de operadores de comparação, por exemplo.

  • Seletor de projeto: restringe a correspondência de filtro a objetos que pertencem a um ou mais projetos no espaço de trabalho mencionado no parâmetro name do método.

    project = "project-id-or-number" OR project = "another-id-or-number"
    
  • Seletor de grupo: corresponde a recursos que pertencem a um (único) Group. Exemplo:

    group.id = "group-id"
    
  • Seletor de recursos: corresponde aos recursos monitorados de um tipo específico ou com valores de rótulo específicos. Por exemplo, veja a seguir maneiras diferentes de especificar informações de recursos:

    resource.type = "the_resource_type"
    resource.labels.a_label_for_the_resource_type = "label_value"
    
  • Seletor de métricas: restrinja o filtro a métricas ou séries temporais de um tipo de métrica específico ou tenha valores de rótulo específicos. Por exemplo, veja a seguir maneiras diferentes de especificar tipos de métricas:

    metric.type = "the_metric_type"
    metric.labels.a_label_for_the_metric_type = "label_value"
    

A tabela a seguir mostra quais seletores são permitidos nos filtros, de acordo com o que o filtro faz:

Finalidade do filtro Seletor de projetos Seletor de grupos Seletor de recursos Seletor de métricas
Definir grupos yes sim1
Listar membros do grupo yes yes
Listar séries temporais yes sim yes sim2
Listar descritores de métrica yes yes
Listar descritores de recursos monitorados yes
1 O seletor de recursos tem outras opções quando usado para definir a associação ao grupo.
2 Ao listar séries temporais, 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, 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 um descritor de recurso monitorado. Os filtros precisam incluir um seletor de métricas, que precisa especificar exatamente um tipo de métrica.

  • Todas as séries temporais para um determinado tipo de métrica:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Série temporal relacionada a recursos em um grupo específico. O seletor group só funciona com dados de série temporal alinhados. Consulte Seletor de grupo para mais informações:

    group.id = "2468013579" AND
        metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Série temporal de uma instância específica do Compute Engine:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = "my-instance-name"
    
  • Série temporal de instâncias do Compute Engine com nome semelhante:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = starts_with("frontend-")
    
  • Séries temporais de instâncias do Compute Engine que começam com gke-hipster ou gke-nginx:

    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. A associação ao grupo é dinâmica e mais ou menos recursos podem corresponder ao filtro sempre que ele for avaliado. O parâmetro name no objeto Group especifica o grupo e o espaço de trabalho proprietário. Se o objeto project for usado no filtro, ele precisará especificar um projeto que seja membro do espaço de trabalho.

  • Todas as instâncias de VM do Compute Engine na Europa:

    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 para o método especifica um espaço de trabalho e um grupo definidos no espaço de trabalho. Se o objeto project for usado no filtro, ele precisará especificar um projeto que seja membro do espaço de trabalho.

  • Todos os recursos de tópico do Cloud Pub/Sub que pertencem ao projeto my-project:

    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:

  • Todas as métricas do Compute Engine:

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

Consulte Lista de métricas para ver uma lista completa dos tipos de métricas definidos pelo Monitoring. Para uma visão geral de como as métricas são nomeadas, consulte Convenções e requisitos de nomenclatura.

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:

  • Todos os descritores de recursos monitorados do Cloud Pub/Sub.

    resource.type = starts_with("pubsub")
    

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

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árias comparações unidas por AND ou OR.

Dependendo da finalidade do filtro, alguns seletores podem ser obrigatórios, opcionais ou proibidos. Por exemplo, o filtro que define os recursos em um grupo não pode conter um seletor de métricas, porque os grupos não têm tipos de métricas ou séries temporais. Por outro lado, o filtro usado para listar séries temporais precisar ter um seletor de métricas. A ordem dos seletores no filtro não importa, mas as comparações de diferentes seletores não podem ser mescladas.

Comparações

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

[OBJECT] [OPERATOR] [VALUE]

Esses elementos são descritos abaixo:

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

    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 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 no caso de 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)

    Apenas o formulário has_substring(<string>) é compatível com timeSeries.list.

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

Somente em definições de grupo, é possível usar o operador de negação unário antes de uma comparação, mas não antes de uma 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 uma das opções a seguir:

<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 pelo 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 só é permitido em filtros passados para projects.timeSeries.list. Além disso, a seleção de grupo requer dados alinhados. Ou seja, a chamada para projects.timeSeries.list precisa incluir valores para 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 parâmetros de alinhamento, consulte Como agregar 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> ')'

<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
                              | <r_label_comparison> {OR <r_label_comparison>}

<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
                       | resource.labels.[KEY] ':' <string>
                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

Se você usar mais de um <r_label_comparison> no seletor, coloque-os entre parênteses para facilitar a leitura. Por exemplo, o filtro a seguir pode ser usado para definir um grupo que inclua todas as instâncias de VM 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>:

  1. É possível usar os nomes metadata.system_labels.[KEY] e metadata.user_labels.[KEYSTRING] nas comparações, assim como resource.labels.[KEY]. As chaves de metadata.user_labels devem ser colocadas entre aspas, porque podem ter caracteres especiais, como hifens.

  2. 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".

  3. É 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 de uma expressão entre parênteses.

  4. Use o operador "existe" (:) para testar a existência de chaves. Por exemplo, a comparação resource.labels.zone será verdadeira se a chave de rótulo zone estiver 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. Ao listar dados de série temporal, 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_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

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

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

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 conforme mostrado abaixo. Isso 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 conforme mostrado abaixo. 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 do seletor de grupo nos filtros para restringir os recursos monitorados aos de um grupo específico. Consulte Definições de grupo para 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 da largura de banda de leitura do disco para todas as instâncias do Compute Engine em um determinado grupo. O grupo precisa ser definido no espaço de trabalho 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"