Filtros de supervisión

En esta guía, se describe cómo configurar filtros cuando usas la API de Monitoring. Usa filtros para especificar los recursos supervisados, los tipos de métricas, las definiciones de grupo , y las series temporales.

También puedes usar un filtro para configurar una política de alertas que supervise 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 no estás familiarizado con las métricas, las series temporales y los recursos supervisados, consulta Métricas, series temporales y recursos.

Si no estás familiarizado con las etiquetas, consulta Etiquetas para obtener una introducción.

Usa filtros

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

Filtra selectores

Un filtro consta de al menos un selector, que es una palabra clave del filtro. En los siguientes ejemplos, se muestran los diferentes selectores:

  • project: Coincide cuando las métricas del proyecto especificado son visibles para el proyecto de permisos de un permiso de métricas mencionado en el parámetro name.

    Usa el selector project cuando un proyecto de Google Cloud pueda ver las métricas de varios proyectos de Google Cloud o cuentas de AWS y solo quieras métricas para un solo proyecto. Por ejemplo, si el permiso de métricas de Project-A incluye Project-B, se producirá una coincidencia cuando name tenga un valor de Project-A y uses el siguiente filtro:

    project = "Project-B"

  • group: Coincide con los recursos que pertenecen a un Group.

    El siguiente filtro coincide con el grupo con el identificador group-id:

    group.id = "group-id"

  • resource: Coincide con los recursos supervisados de un tipo en particular o que tienen valores de etiqueta particulares.

    • 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 tipo de métrica o una serie temporal en particular 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 coincide con series temporales con una etiqueta llamada instance_name, cuyo valor comienza con gke-hipster o gke-nginx:

      metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

En la siguiente tabla, se muestra qué selectores están 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í
* El selector de recursos tiene opciones adicionales cuando se usa para definir la membresía de un grupo.
† Cuando enumeres 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 con un descriptor de métrica, y el recurso supervisado se especifica mediante un descriptor de recursos supervisados.

El filtro especificado en el método timeSeries.list debe incluir un selector metric, que 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 selector group solo funciona con datos de series temporales alineados. Consulta 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, usa el siguiente filtro: 

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = "my-instance-name"

  • Muestra todas las series temporales de instancias de Compute Engine cuyos nombres comiencen con frontend-. Usa el siguiente filtro: 

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

  • Muestra todas las series temporales de instancias de Compute Engine cuyos nombres comiencen con gke-hipster o gke-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. La membresía del grupo es dinámica; es posible que más o menos recursos coincidan con el filtro cada vez que se evalúe. El parámetro name en el objeto Group especifica el grupo y el proyecto de permisos de un permiso de métricas]metrics-scope-concept. Si se usa el selector project en el filtro, debe especificar un proyecto cuyas métricas sean visibles para el proyecto de permisos.

  • Para mostrar una lista de todas las instancias de máquina virtual (VM) de Compute Engine en Europa, usa el siguiente filtro: 
    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 alcance de un permiso de métricas y un grupo definido en ese proyecto. Si se usa el selector project 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 del tema de Pub/Sub que pertenecen al 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 mostrar 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 los tipos de métricas disponibles. Para obtener una descripción general de cómo se nombran las métricas, consulta Convenciones de nomenclatura de las métricas.

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 de ancho de banda de lectura de disco para todas las instancias y todos los dispositivos, define un filtro de la siguiente manera. Este filtro muestra, para cada instancia, una serie temporal independiente que informa el ancho de banda de lectura de cada dispositivo:

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

A fin de definir mejor la solicitud para consultar el ancho de banda de lectura solo para el dispositivo de disco conocido 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

En los siguientes ejemplos, se ilustra el uso del selector de grupos en filtros para restringir los recursos supervisados a aquellos en un grupo específico. Consulta Selector de recursos para definiciones de grupos a fin de obtener información sobre los selectores usados para definir la membresía de 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 de ancho de banda de lectura del disco para todas las instancias de Compute Engine en un grupo en particular. El grupo debe definirse en el proyecto de permisos de un permiso de métricas 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"

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. El orden de los selectores en el filtro no importa, pero las comparaciones para selectores diferentes no se deben intercalar.

Según el propósito del filtro, algunos selectores pueden ser obligatorios, opcionales o prohibidos. Por ejemplo, el filtro que se usa para enumerar series temporales debe contener un selector de métricas. Sin embargo, el filtro que define los recursos de un grupo no puede contener un selector de métricas, ya que los grupos no contienen tipos de métricas ni series temporales.

Comparaciones

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

  • [OBJETO]: selecciona un valor que se probará; uno de los siguientes:

    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]: Un valor literal o una llamada a función integrada; uno de los siguientes:

    <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 filtro has_substring toma un segundo argumento opcional, que especifica si la coincidencia ignora mayúsculas de minúsculas o no. El valor predeterminado es false, de manera que la coincidencia predeterminada distingue mayúsculas de 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 formulario has_substring(<string>).

    El filtro monitoring.regex.full_match toma una string de expresión regular en la 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.

El x = one_of("a", "b", "c") de comparación 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 que exista (:) 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 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 se puede especificar por 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 se puede usar 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 método 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 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 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> ')'

<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 tu selector, enciérralos todos entre paréntesis para mejorar la legibilidad. Por ejemplo, el siguiente filtro se podría usar 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>:

  • Puedes incluir filtros basados en el valor de las etiquetas del sistema de metadatos, metadata.system_labels.[KEY], y las etiquetas de usuario de metadatos, metadata.user_labels.[KEYSTRING]. Recomendamos citar las claves para metadata.user_labels, ya que pueden contener caracteres especiales, como guiones.

    Cuando un selector contiene un filtro de metadatos y un filtro de recursos, debes combinarlos con AND; no puedes usar OR. Por ejemplo, un gráfico con el siguiente selector muestra el uso de CPU de todas las instancias de VM con un tipo de máquina de e2-medium o 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")

  • 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. Por ejemplo, NOT resource.labels.zone="europe" es verdadero si la zona del recurso no incluye "europe". No puedes usar NOT antes de que exista un operador (:) ni una expresión entre paréntesis.

  • Puedes usar el operador "exists" (:) para comprobar la existencia de las claves. Por ejemplo, la comparación resource.labels:zone es verdadera si la clave de 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 usa 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 podría usarse para recuperar una serie temporal para una instancia de base de datos específica:

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