En esta guía, se describe cómo configurar filtros cuando utilizas el menú API de Monitoring. Usa filtros para especificar recursos supervisados, tipos de métricas, definiciones de grupos, y series temporales. También puedes usar un filtro para configurar una política de alertas supervisa los procesos que se ejecutan en tus sistemas. Para obtener información sobre esos filtros, consulta Filtros del estado del proceso.
Antes de comenzar
Si desconoces las métricas, las series temporales y los recursos supervisados consulta Métricas, series temporales y recursos.
Si no conoces las etiquetas, consulta Etiquetas para obtener una introducción.
Usa filtros
Puedes usar filtros en la API de Monitoring para hacer lo siguiente:
- Selecciona los datos de la serie temporal específicos
que se muestra a partir de una solicitud a la API de
list
. El filtro puede seleccionar series temporales según el proyecto de los datos, el grupo, las propiedades de recurso supervisado y propiedades de las métricas. Para obtener más información y ejemplos, consulta Recupera datos de series temporales.
Asigna recursos a un
Group
según los recursos y las el proyecto al que pertenecen. Para obtener más información y ejemplos, consulta Cómo definir la pertenencia a un grupo.Seleccionar recursos dentro de un grupo según el estado de los recursos sus propiedades y el proyecto al que pertenecen. Para obtener más información y ejemplos, consulta Enumera los miembros del grupo.
Enumera tipos de métricas particulares. Para ver más información y ejemplos, consulta Enumera descriptores de métricas.
Enumera tipos de recurso supervisado particulares. Para obtener más información y Por ejemplo, consulta Enumera recurso supervisado supervisados.
Filtra selectores
Un filtro consta de al menos un selector, que es una palabra clave de filtro. En los siguientes ejemplos, se ilustran los diferentes selectores:
-
project
: Coincide cuando las métricas del elemento proyecto son visibles para el proyecto de permisos de un permiso de métricas que se menciona en el parámetroname
.Usa el selector
project
cuando se cree un proyecto de Google Cloud puede ver las métricas de varios proyectos de Google Cloud o cuentas de AWS y solo quieres métricas para un proyecto. Por ejemplo, el permiso de métricas paraProject-A
incluyeProject-B
, luego un la coincidencia se produce cuandoname
tiene un valor deProject-A
y usas el siguiente filtro:project = "Project-B"
-
group
: Hace coincidir los recursos que pertenecen a uno.Group
El siguiente filtro coincide con el grupo con los identificador
group-id
:group.id = "group-id"
-
resource
: Coincide con recursos supervisados de un tipo determinado o con una etiqueta determinada de salida.-
El siguiente filtro coincide con todos los recursos supervisados que son instancias de máquina virtual (VM) de Compute Engine:
resource.type = "gce_instance"
-
El siguiente filtro coincide con todos los recursos cuya zona comienza con
europe-
:resource.labels.zone = starts_with("europe-")
-
-
metric
: Coincide con un en particular tipo de métrica o serie temporal con con una etiqueta específica que coincide con un valor específico.-
El siguiente filtro coincide con un tipo de métrica específico:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
-
El siguiente filtro hace coincidir las series temporales con una etiqueta llamada
instance_name
, cuyo valor comienza congke-hipster
ogke-nginx
:metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
-
En la siguiente tabla, se muestran los selectores permitidos en los filtros según la llamada a la API de Monitoring:
Propósito del filtro | Selector de project |
Selector de group |
Selector de resource |
Selector de metric |
---|---|---|---|---|
Define grupos | sí | sí* | ||
Enumerar miembros de grupo | sí | sí | ||
Enumera series temporales | sí | sí | sí | sí † |
Enumerar descriptores de métrica | sí | sí | ||
Enumera descriptores de recursos supervisados | sí |
† Cuando se listan las series temporales, debes especificar exactamente un tipo de métrica.
En las próximas secciones, se muestran ejemplos de usos típicos de los filtros de supervisión. Consulta Sintaxis del filtro para ver un análisis completo de los objetos y los operadores de filtros disponibles.
Recupera datos de series temporales
Método:
projects.timeSeries.list
Filtra objetos:
project
, group.id
, resource.type
, resource.labels.[KEY]
y metric.type
,
metric.labels.[KEY]
Una serie temporal es una lista de datos con marcas de tiempo de un tipo de métrica de un recurso supervisado específico. Para obtener más detalles, consulta El modelo de métrica. El tipo de métrica se especifica mediante un descriptor de métrica. el recurso supervisado se especifica mediante un descriptor de recursos supervisados.
El filtro especificado para el método timeSeries.list
debe incluir un
metric
, el cual debe especificar exactamente un tipo de métrica:
- Para mostrar todas las series temporales de un tipo de métrica en particular, haz lo siguiente:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Para mostrar todas las series temporales de un grupo específico. El El selector
group
solo funciona con datos de series temporales alineadas. ver Selector de grupos para obtener más información:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND group.id = "2468013579"
Para mostrar todas las series temporales de una instancia específica de Compute Engine, sigue estos pasos: usa el siguiente filtro:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Devuelve todas las series temporales de instancias de Compute Engine cuyos nombres comienza con
frontend-
, usa el siguiente filtro:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")
Devuelve todas las series temporales de instancias de Compute Engine cuyos nombres comienza con
gke-hipster
ogke-nginx
, usa el siguiente filtro:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
Define la membresía del grupo
Método: projects.groups
Filtrar objetos: project
, resource.type
, resource.labels.key
, metadata.system_labels.[KEY]
, metadata.user_labels.[KEY]
Un grupo puede contener cualquier cantidad de recursos, como lo especifica un filtro. Grupo
la membresía es dinámica; más o menos recursos pueden coincidir con el filtro cada
cada vez que se evalúa el filtro. El parámetro name
de la
El objeto Group
especifica el grupo y la
proyecto de permisos de un permiso de métricasmetrics-scope-concept.
Si se usa el selector project
en el filtro, debe especificar un
proyecto cuyas métricas son visibles para el proyecto de permisos.
resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
Enumera miembros del grupo
Método: projects.groups.members.list
Filtrar objetos: project
, resource.type
, resource.labels.[KEY]
Usa un filtro para limitar los miembros del grupo que recuperas. El parámetro name
especifica un proyecto de permisos de un permiso de métricas y un
definido en ese proyecto. Si el selector project
se usa en el
filtro, debe especificar un proyecto cuyas métricas sean visibles para el
proyecto de permisos.
- Para mostrar una lista de todos los recursos de temas de Pub/Sub que pertenecen a
proyecto
my-project
, usa el siguiente filtro:project = "my-project" AND resource.type = "pubsub_topic"
Enumera descriptores de métricas
Método: projects.metricDescriptors.list
Filtrar objetos: project
, metric.type
Usa un filtro para limitar los descriptores de métricas que recuperas:
- Para que devuelva solo los descriptores de métricas de Compute Engine,
usa el siguiente filtro:
metric.type = starts_with("compute.googleapis.com")
Consulta la Lista de métricas para obtener una lista completa de las métricas disponibles. de tipos de datos. Para obtener una descripción general sobre cómo se nombran las métricas, consulta Asignación de nombres de métricas convenciones.
Enumera descriptores de recursos supervisados
Método: projects.monitoredResourceDescriptors.list
Filtrar objetos: resource.type
Usa un filtro para limitar los descriptores de recursos supervisados que recuperas:
- Para recuperar solo los descriptores de recurso supervisado de Pub/Sub,
usa el siguiente filtro:
resource.type = starts_with("pubsub")
Consulta la Lista de recursos supervisados para obtener una lista completa de los tipos de recurso supervisado definidos por Monitoring.
Ejemplos
En los ejemplos de filtrado, usamos el descriptor de métricas, el descriptor de recursos supervisados y la instancia de máquina virtual que se encuentran a continuación, simplificados para fines ilustrativos:
# 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" }
Ejemplos de recuperación de métricas
Para solicitar el uso del ancho de banda de lectura del disco para todas las instancias y dispositivos, definir un filtro de la siguiente manera. Este filtro devuelve, para cada instancia, un Series temporales separadas que informan el ancho de banda de lectura para cada dispositivo:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Para definir mejor la solicitud de consulta del ancho de banda de lectura solo para el dispositivo del disco conocida como “log_partition” en cada instancia, define el filtro de la siguiente manera: Este filtro muestra, para cada instancia, como máximo una serie temporal, según si existe un dispositivo con ese nombre en esa instancia:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND metric.labels.device_name = "log_partition"
Para restringir la solicitud a una sola instancia, especifica esa instancia:
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"
Filtra con grupos
Los siguientes ejemplos ilustran el uso del selector de grupos en los filtros para restringir los recursos supervisados a los de un grupo específico. Consulta Selector de recursos para definiciones de grupos para obtener información sobre los selectores que se usan para definir la pertenencia a un grupo.
{ "name": "projects/my-test-project/groups/024681012", "display_name": "My Redis Cluster", "filter": "metadata.user_labels.role=redis" }
En una llamada al método projects.timeSeries.list
,
el siguiente filtro solicita el uso del ancho de banda de lectura del disco para todas
instancias de Compute Engine en un grupo particular. El grupo debe ser
definidos en el proyecto de permisos de un permiso de métricas especificado en
parámetro name
del método:
resource.type = "gce_instance" AND group.id = "024681012" AND metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Referencia: sintaxis del filtro
Para obtener una descripción general de los filtros con ejemplos, consulta Usa filtros.
Un filtro de supervisión es una string que consta de hasta cuatro tipos de selectores:
<monitoring_filter> ::= <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>
El filtro hace coincidir un elemento si todos los selectores incluidos coinciden con este.
Como se describe en las siguientes secciones, algunos selectores pueden tener varios
comparaciones unidas por AND
o OR
. El orden de los selectores en la
el filtro no importa, pero las comparaciones de diferentes selectores no deben
entremezclados.
Según el propósito del filtro, algunos selectores pueden ser obligatorios, opcionales o prohibidos. Por ejemplo, el filtro que se usa para enumerar las series temporales debe contener un selector de métricas. Sin embargo, el filtro que define los recursos de un grupo no puede contienen un selector de métricas, porque los grupos no contienen tipos de métricas o series temporales.
Comparaciones
Los filtros y sus selectores se compilan a partir de las comparaciones. Cada comparación tiene la forma siguiente:
-
[OBJECT]: selecciona un valor para probar. una de las siguientes opciones:
project group.id metric.type metric.labels.[KEY] resource.type resource.labels.[KEY] metadata.system_labels.[KEY] metadata.user_labels.[KEYSTRING]
[KEY] es un nombre, como
zone
oinstance_id
[KEYSTRING] puede ser un nombre, pero si contiene caracteres especiales, entonces debe estar entre comillas (
"
). -
[OPERATOR]: un operador de comparación. una de las siguientes opciones:
= # equality (case-sensitive) > < >= <= # numeric ordering != # not equal : # "has" substring match and test for key (case-sensitive)
-
[VALUE]: un valor literal o una llamada a función integrada; uno de lo siguiente:
<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>)
Excepto cuando se usa en el método
timeSeries.list
, el El filtrohas_substring
toma un segundo argumento opcional, que especifica si la coincidencia ignora las mayúsculas y minúsculas o no. Predeterminado el valor esfalse
, por lo que la coincidencia predeterminada distingue entre mayúsculas y minúsculas:- Distingue mayúsculas de minúsculas:
display_name=has_substring("Demo")
- Distingue mayúsculas de minúsculas:
display_name=has_substring("Demo", false)
- No distingue mayúsculas de minúsculas:
display_name=has_substring("Demo", true)
Cuando se usa en el método
timeSeries.list
, Solo se admite el formulariohas_substring(<string>)
.El filtro
monitoring.regex.full_match
toma un string de expresión regular en Sintaxis de RE2. - Distingue mayúsculas de minúsculas:
Puedes usar los siguientes operadores para agrupar o modificar las comparaciones. OR
tiene mayor prioridad que AND
. Los operadores se deben escribir en mayúsculas:
(...) # grouping comparisons AND # conjunction (optional but recommended) OR # disjunction
El operador AND
se puede omitir entre los operadores, pero incluirlo proporciona más claridad y una propensión menor a errores.
La comparación x = one_of("a", "b", "c")
es equivalente a lo siguiente:
(x = "a" OR x = "b" OR x = "c")Solo en las definiciones de grupo, puedes usar el operador de negación unario,
NOT
,
antes de una comparación, pero no con un operador existente (:
) o antes de una
expresión entre paréntesis:
NOT # negates the following comparison
Filtra selectores
Usa selectores para limitar las selecciones de filtros a ciertos elementos.
En las siguientes secciones, se usan llaves para mostrar la repetición. Por ejemplo:
la notación <x> {OR <y>}
significa que puedes escribir cualquiera de los
lo siguiente:
<x> <x> OR <y> <x> OR <y> OR <y> <x> OR <y> OR <y> OR <y> ...
Selector de proyectos
Un selector de proyectos limita la selección de filtros a los elementos que pertenecen a un solo proyecto o a cualquiera de un conjunto de proyectos. Cada proyecto puede especificarse su ID o número:
<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}
Si el selector de proyectos tiene más de una comparación, encierra el selector completo entre paréntesis para mejorar la legibilidad. Por ejemplo:
(project=12345 OR project="my-project-id") AND resource.type="gce_instance"
Selector de grupos
Un selector de grupos limita la selección de filtros a los elementos que pertenecen a un solo grupo:
<group_selector> ::= group.id '=' <string>
Por ejemplo, el siguiente filtro puede usarse para recuperar una serie temporal de cada una de las instancias de VM en un grupo:
group.id = 12345 AND resource.type = "gce_instance" AND metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
El selector de grupos solo se permite en los filtros que se pasan al
projects.timeSeries.list
. Además,
la selección de grupos requiere datos alineados; es decir,
La llamada projects.timeSeries.list
debe incluir valores para los campos
perSeriesAligner
y alignmentPeriod
. Esto se debe a que la membresía del grupo es en sí misma un tipo de serie temporal que se debe unir con los datos de métricas, y el suministro de parámetros de alineación te permite controlar cómo se realiza esa unión.
Para obtener más información sobre los parámetros de alineación, consulta
Agregación de datos.
Selector de recursos
Un selector de recursos limita la selección de filtros a los recursos (o elementos asociados con los recursos) que tienen un tipo de recurso o valores de etiqueta en específico:
<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>}
Si usas más de un <r_label_comparison>
en el selector, entonces
enciérralos todos entre paréntesis para mejorar la legibilidad.
Por ejemplo, el siguiente filtro podría usarse para definir un grupo que incluya
todas las instancias de VM de Compute Engine
en EE.UU. y Europa.
resource.type = "gce_instance" AND (resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
Selector de recursos para las definiciones de grupos
Los selectores de recursos que se usan a fin de definir la membresía del grupo usan extensiones para la sintaxis <resource_selector>
:
Incluye filtros basados en el valor de las etiquetas del sistema de metadatos
metadata.system_labels.[KEY]
y etiquetas de metadatos de usuario,metadata.user_labels.[KEYSTRING]
Te recomendamos que cites claves parametadata.user_labels
porque pueden contener etiquetas caracteres, como guiones.Cuando un selector contiene un filtro de metadatos y un filtro de recursos, debes combinarlos con
AND
; No puedes usarOR
. Por ejemplo, un gráfico Con el siguiente selector, se muestra el uso de CPU de todas las VM Instancias con un tipo de máquina dee2-medium
oe2-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")
Puedes usar el operador de desigualdad (
!=
) para comparar los tipos de recursos, las etiquetas de recursos y los metadatos. El operador se puede usar cuando se comparan strings, números, valores booleanos o funciones de la substring. Por ejemplo,resource.type!=starts_with("gce")
es verdadero si el tipo de recurso no comienza con"gce"
.Puedes usar un solo operador
NOT
antes de una comparación de recursos. Para ejemplo,NOT resource.labels.zone="europe"
es verdadero si la zona del recurso no incluye"europe"
. No puedes usarNOT
antes un operador existe (:
) o una expresión entre paréntesis.Puedes usar “existe” (
:
) para comprobar la existencia de claves. Por ejemplo, la comparaciónresource.labels:zone
es verdadera si la etiqueta la clavezone
está presente en el recurso.
Por ejemplo, una de las claves de metadatos del recurso de la plataforma para las instancias de VM es spot_instance
. En el siguiente selector de filtros, se eligen instancias que son puntuales:
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
Selector de métricas
Un selector de métricas especifica ciertas métricas o descriptores de métricas mediante la limitación del tipo de métrica y las etiquetas de métricas. Cuando se usan con el
método projects.timeSeries.list
,
el selector de métricas debe especificar un solo 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 ejemplo, el siguiente filtro se podría usar para recuperar una hora para una instancia específica de base de datos:
metric.type = "cloudsql.googleapis.com/database/state" AND (metric.labels.resource_type = "instance" AND metric.labels.resource_id = "abc-123456")