Filtros de supervisión

En esta guía, se describe el uso de filtros de supervisión para especificar recursos supervisados, tipos de métricas, definiciones de grupos y series temporales.

Para obtener una introducción a las métricas, las series temporales y los recursos supervisados, consulta Métricas, series temporales y recursos.

Los filtros usan mucho las etiquetas. Consulta Etiquetas para obtener información adicional.

Usa filtros

Puedes usar filtros en la API de Monitoring v3 para hacer lo siguiente:

  • Recuperar series temporales: Usa un filtro para seleccionar datos de series temporales según el proyecto de los datos, el grupo, las propiedades de los recursos supervisados y las propiedades de las métricas. Para obtener más información y ejemplos, consulta Recupera datos de series temporales.

  • Definir los recursos en un grupo: Usa un filtro para asignar recursos a un Group según las propiedades de los recursos y el proyecto al que pertenecen. Para obtener más información y ejemplos, consulta Define la membresía de un grupo.

  • Enumerar miembros del grupo: Usa un filtro para seleccionar recursos dentro de un grupo según las propiedades de los recursos y el proyecto al que pertenecen. Para obtener más información y ejemplos, consulta Enumera miembros del grupo.

  • Enumerar descriptores de métrica: Usa un filtro para inspeccionar tipos de métricas particulares de los cientos de tipos definidos en Monitoring. Para obtener más información y ejemplos, consulta Enumera descriptores de métrica.

  • Enumerar descriptores de recursos supervisados: Usa un filtro para inspeccionar los tipos de recursos supervisados específicos de las decenas de tipos definidos en Monitoring. Para obtener más información y ejemplos, consulta Enumera descriptores de recursos supervisados.

Según cuál sea la operación anterior que restringes, tu filtro puede constar del AND lógico de los selectores de la siguiente lista. Estos son ejemplos simples. Por ejemplo, hay varios tipos de operadores de comparación.

  • Selector de proyectos: Restringe la coincidencia de filtros a los objetos que pertenezcan a uno o más proyectos dentro del lugar de trabajo mencionado en el parámetro name del método.

    project = "project-id-or-number" OR project = "another-id-or-number"
    
  • Selector de grupo: Coincide con los recursos que pertenecen a un (solo) Group. Por ejemplo:

    group.id = "group-id"
    
  • Selector de recursos: Compara los recursos supervisados de un tipo en particular o los que tengan valores de etiqueta particulares. Por ejemplo, a continuación se muestran varias maneras de especificar información del recurso:

    resource.type = "the_resource_type"
    resource.labels.a_label_for_the_resource_type = "label_value"
    
  • Selector de métricas: Restringe el filtro a las métricas o las series temporales de un tipo de métrica en particular o las que tengan valores de etiqueta particulares. Por ejemplo, a continuación se muestran diferentes formas de especificar tipos de métricas:

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

En la siguiente tabla, se muestran los selectores que se permiten en los filtros según su uso:

Propósito del filtro Selector de proyectos Selector de grupos Selector de recursos Selector de métricas
Define grupos 1
Enumerar miembros de grupo
Enumera series temporales 2
Enumerar descriptores de métrica
Enumera descriptores de recursos supervisados
1 El selector de recursos tiene opciones adicionales cuando se usa para definir la membresía del grupo.
2 Cuando enumeras 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
Filtrar objetos: project, group.id, resource.type , resource.labels.[KEY], 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, y un descriptor de recursos supervisados especifica el recurso supervisado. Los filtros deben incluir un selector de métricas, y ese selector debe especificar exactamente un tipo de métrica.

  • Todas las series temporales para un tipo de métrica en particular.

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Las series temporales que se relacionan con recursos de un grupo específico. El selector group solo funciona con datos de series temporales alineados. Consulta Selector de grupos para obtener más información:

    group.id = "2468013579" AND
        metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Series temporales de una instancia específica de Compute Engine:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = "my-instance-name"
    
  • Series temporales de instancias de Compute Engine con nombres similares:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = starts_with("frontend-")
    
  • Series temporales de instancias de Compute Engine que comienzan con gke-hipster o gke-nginx:

    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. La membresía del grupo es dinámica. Puede que coincidan más o menos recursos con el filtro cada vez que este se evalúa. El parámetro name del objeto Group especifica el grupo y el lugar de trabajo propietario. Si el objeto project se usa en el filtro, debe especificar un proyecto que sea miembro del lugar de trabajo.

  • Todas las instancias de VM de Compute Engine en Europa:

    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 del método especifica un lugar de trabajo y un grupo definido en este. Si el objeto project se usa en el filtro, debe especificar un proyecto que sea miembro del lugar de trabajo.

  • Todos los recursos de temas de Cloud Pub/Sub que pertenecen al proyecto my-project:

    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:

  • Todas las métricas de Compute Engine:

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

Consulta Lista de métricas para obtener una lista completa de los tipos de métricas definidos por Monitoring. Para obtener una descripción general de cómo se nombran las métricas, consulta Las convenciones de asignación de nombres y los requisitos.

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:

  • Todos los descriptores de recursos supervisados de Cloud Pub/Sub.

    resource.type = starts_with("pubsub")
    

Consulta la Lista de recursos supervisados para ver una lista completa de los tipos de recursos supervisados definidos por Monitoring.

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 varias comparaciones unidas por AND o OR.

Según el propósito del filtro, algunos selectores pueden ser obligatorios, opcionales o prohibidos. Por ejemplo, el filtro que define los recursos en un grupo no puede contener un selector de métricas, ya que los grupos no contienen tipos de métricas o series temporales. Por otro lado, el filtro que se usa para enumerar las series temporales debe contener un selector de métricas. El orden de los selectores en el filtro no es importante, pero las comparaciones de los diferentes selectores no deben entremezclarse.

Comparaciones

Los filtros y sus selectores se compilan a partir de las comparaciones. Cada comparación tiene la forma siguiente:

[OBJECT] [OPERATOR] [VALUE]

Estos elementos se describen a continuación:

  • [OBJECT]: selecciona un valor que se probará y puede ser 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 o instance_id. [KEYSTRING] puede ser un nombre, pero si contiene caracteres especiales, debe estar entre comillas (").

  • [OPERATOR]: un operador de comparación, uno de los siguientes:

    =            # equality (case-sensitive)
    > < >= <=    # numeric ordering
    !=           # not equal
    :            # "has" substring match and test for key (case-sensitive)
    
  • [VALUE]: es un valor literal o una llamada a una función incorporada y puede ser una de las siguientes opciones:

    <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 en el caso de timeSeries.list, el filtro has_substring toma un segundo argumento opcional, que especifica si la coincidencia distingue entre mayúsculas y minúsculas o no. El valor predeterminado es false, por lo que la coincidencia predeterminada distingue entre mayúsculas y minúsculas:

    • Distingue entre mayúsculas y minúsculas: display_name=has_substring("Demo")
    • Distingue entre mayúsculas y minúsculas: display_name=has_substring("Demo", false)
    • No distingue entre mayúsculas y minúsculas: display_name=has_substring("Demo", true)

    Solo se admite el formato has_substring(<string>) para timeSeries.list.

    El filtro monitoring.regex.full_match toma una string de expresión regular en sintaxis RE2.

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

(x = "a" OR x = "b" OR x = "c")

Solo en las definiciones de grupos, puedes usar el operador de negación unario antes de una comparación, pero no 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 las siguientes opciones:

<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 se puede especificar por su ID o su 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 podría usarse para recuperar una serie temporal de cada una de las instancias de VM de 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 a projects.timeSeries.list. Además, la selección de grupos requiere datos alineados. Es decir, la llamada a projects.timeSeries.list debe incluir valores para 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. Si deseas obtener más información sobre los parámetros de alineación, consulta Agrega 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> ')'

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

Si usas más de una <r_label_comparison> en tu selector, escríbelas 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 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>:

  1. Puedes usar los nombres metadata.system_labels.[KEY] y metadata.user_labels.[KEYSTRING] en las comparaciones al igual que en resource.labels.[KEY]. Las claves para metadata.user_labels deben estar entre comillas porque pueden contener caracteres especiales como guiones.

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

  3. Puedes usar un único operador NOT antes de cualquier comparación de recursos. Por ejemplo, NOT resource.labels.zone:"europe" es verdadero si no se incluye "europe" en la zona del recurso. No puedes usar NOT antes de una expresión entre paréntesis.

  4. Puedes usar el operador existente (:) para probar la existencia de las claves. Por ejemplo, la comparación resource.labels.zone es verdadera si la clave de la etiqueta zone 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 enumeran los datos de series temporales, 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_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 ejemplo, el siguiente filtro podría usarse para recuperar una serie temporal en una instancia específica de la base de datos:

metric.type = "cloudsql.googleapis.com/database/state" AND
  (metric.labels.resource_type = "instance" AND
   metric.labels.resource_id = "abc-123456")

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 de todas las instancias y los dispositivos, define un filtro como se muestra a continuación. Esto muestra, para cada instancia, una serie temporal separada que informa el ancho de banda de lectura de cada dispositivo:

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

Si quieres definir mejor la solicitud para consultar el ancho de banda de lectura solo del dispositivo del disco conocido como “log_partition”, define el filtro en cada instancia como se muestra a continuación. 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

En los siguientes ejemplos, se ilustra el uso del selector de grupos en los filtros para restringir los recursos supervisados a los de un grupo específico. Consulta Definiciones de grupos para obtener información sobre los selectores que se usan para definir la membresía del 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 de todas las instancias de Compute Engine en un grupo en particular. El grupo debe definirse en el lugar de trabajo especificado en el 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"