Este guia descreve como configurar filtros quando você usa a API Monitoring. Use filtros para especificar recursos monitorados, tipos de métricas, definições de grupo , e série temporal.
Também é possível usar um filtro para configurar uma política de alertas que monitore processos em execução nos sistemas. Para mais informações sobre esses filtros, consulte Process-health filters.Antes de começar
Se você não conhecer 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 dos dados, grupo , propriedades de recursos monitorados e propriedades de métrica. Para mais informações e exemplos, consulte Como série temporal temporais. 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 projeto especificado estão visíveis para o projeto de um escopo de métricas mencionado no parâmetroname
.Use o seletor
project
quando um projeto do Google Cloud puder visualizar as métricas de vários projetos do Google Cloud ou contas da AWS e você quiser apenas métricas de um único projeto. Por exemplo, se o escopo de métricas paraProject-A
incluirProject-B
, uma correspondência ocorrerá quandoname
tiver o valorProject-A
e você usar o seguinte filtro:project = "Project-B"
-
group
: faz a correspondência de recursos pertencentes a umGroup
.O filtro a seguir corresponde o grupo com o identificador
group-id
:group.id = "group-id"
-
resource
: corresponde a recursos monitorados de um tipo específico ou a 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"
-
O filtro a seguir corresponde a todos os recursos com zona que começa com
europe-
:resource.labels.zone = starts_with("europe-")
-
-
metric
: faz a correspondência de um determinado tipo de métrica ou série temporal 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 comgke-hipster
ougke-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 | sim | ||
Listar séries temporais | sim | sim | sim | sim † |
Listar descritores de métrica | yes | yes | ||
Listar descritores de recursos monitorados | sim |
† Ao listar série temporal, é necessário 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.
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 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"
Para retornar todas série temporal das 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 série temporal das instâncias do Compute Engine com nomes que começam com
gke-hipster
ougke-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. A associação ao grupo é dinâmica, ou seja, mais ou menos recursos podem corresponder ao filtro sempre que ele é avaliado. O parâmetro name
no objeto Group
especifica o grupo e o projeto do escopo de um escopo de métricas]metrics-scope-concept.
Se o seletor project
for usado no filtro, ele precisará especificar um projeto com métricas visíveis para o projeto do escopo.
- Para retornar uma lista de todas as instâncias de máquina virtual (VM) do Compute Engine 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 um grupo definido nesse projeto. Se o seletor project
for usado no filtro, ele precisará especificar um projeto com métricas visíveis para o projeto do escopo.
- Para retornar uma lista de todos os recursos de tópicos do Pub/Sub que pertencem ao
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 apenas 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 ver todos os tipos de métricas disponíveis. Para ter uma visão geral de como as métricas são nomeadas, consulte as 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:
- Para recuperar apenas os descritores de recursos monitorados do Pub/Sub,
use o seguinte filtro:
resource.type = starts_with("pubsub")
Consulte Lista de recursos monitorados para ver uma lista completa dos tipos de recursos monitorados definidos pelo Monitoring.
Examples
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 de disco para todas as instâncias e todos os dispositivos, defina um filtro da seguinte maneira. Esse filtro retorna, em 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"
Como filtrar com grupos
Os exemplos a seguir ilustram o uso do seletor de grupo em filtros para restringir os recursos monitorados aos de um grupo específico. Consulte Seletor de recursos para 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 de disco de todas
as instâncias do Compute Engine em um determinado grupo. 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árias
comparações unidas por AND
ou OR
. A ordem dos seletores no filtro não importa, mas as comparações deles não podem se misturar.
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. No entanto, o filtro que define os recursos em um grupo não pode conter um seletor de métrica, porque os grupos não contêm tipos de métricas 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:
-
[OBJETIVO]: seleciona um valor a ser testado, que pode ser 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
ouinstance_id
.[KEYSTRING] pode ser um nome, mas se ele contiver caracteres especiais, precisará 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 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 filtrohas_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
. 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
, apenas o formuláriohas_substring(<string>)
é compatível.O filtro
monitoring.regex.full_match
usa uma string de expressão regular na sintaxe RE2. - Diferenciar maiúsculas de minúsculas:
É 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")Apenas em 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 existe (:
) 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 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 seguintes itens:
<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 séries temporais 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 apenas em filtros transmitidos 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 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> ')' <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.
Por exemplo, o
filtro a seguir 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 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]
e rótulos do usuário de metadados,metadata.user_labels.[KEYSTRING]
. Recomendamos citar as chaves demetadata.user_labels
porque elas podem conter caracteres especiais, como hifens.Quando um seletor contém um filtro de metadados e um filtro de recurso, você precisa combiná-los com
AND
. Não é possível usarOR
. Por exemplo, um gráfico com o seletor a seguir exibe a utilização da CPU para todas as instâncias de VM com um tipo de máquinae2-medium
oue2-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 usarNOT
antes de um operador (:
) ou de uma expressão entre parênteses.Use o operador "exists" (
:
) para testar a existência de chaves. Por exemplo, a comparaçãoresource.labels:zone
será verdadeira se a chave de rótulozone
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 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étricas precisa especificar um único tipo:
<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")