Filtros de Monitoring

En esta guía se describe cómo configurar filtros al usar la API Monitoring. Los filtros se usan para especificar los recursos monitorizados, los tipos de métricas, las definiciones de grupos y las series temporales. También puedes usar un filtro para configurar una política de alertas que monitorice los procesos que se ejecutan en tus sistemas. Para obtener información sobre esos filtros, consulta Filtros de estado del proceso.

Antes de empezar

Si no conoces las métricas, las series temporales y los recursos monitorizados, consulta el artículo Métricas, series temporales y recursos.

Si no conoces las etiquetas, consulta la introducción.

Usar filtros

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

  • Selecciona los datos de serie temporal específicos que se devuelven de una solicitud de la API list. El filtro puede seleccionar series temporales en función del proyecto, el grupo, las propiedades del recurso monitorizado y las propiedades de la métrica de los datos. Para obtener más información y ejemplos, consulta Recuperar datos de series temporales.

  • Asigna recursos a un Group en función de las propiedades de los recursos y del proyecto al que pertenecen. Para obtener más información y ejemplos, consulta Definir la pertenencia a un grupo.

  • Seleccionar recursos de un grupo en función de las propiedades de los recursos. Para obtener más información y ejemplos, consulta Listar los miembros de un grupo.

Selectores de filtros

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 proyecto especificado son visibles para el proyecto de ámbito de un ámbito de métricas mencionado en el parámetro name.

    Use el selector project cuando un Google Cloud proyecto pueda ver las métricas de varios Google Cloud proyectos o cuentas de AWS y solo quiera ver las métricas de un proyecto. Por ejemplo, si el ámbito de las métricas de Project-A incluye Project-B, se produce una coincidencia cuando name tiene el valor Project-A y se usa el siguiente filtro:

    project = "Project-B"

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

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

    group.id = "group-id"

  • resource: coincide con los recursos monitorizados de un tipo concreto o que tienen valores de etiqueta concretos.

    • El siguiente filtro coincide con todos los recursos monitorizados 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 empieza por europe-:

      resource.labels.zone = starts_with("europe-")

  • metric: coincide con un tipo de métrica o una serie temporal con una etiqueta concreta 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 que tienen una etiqueta llamada instance_name, cuyo valor empieza por gke-hipster o gke-nginx:

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

En la siguiente tabla se muestran los selectores que se permiten en los filtros en función de la llamada a la API Monitoring:

Propósito del filtro Selector de project Selector de group Selector de resource Selector de metric
Definir grupos yes Sí*
Enumerar miembros del grupo yes yes
List time series yes sí yes Sí †
Enumerar descriptores de métricas yes yes
Mostrar descriptores de recursos monitorizados yes
* El selector de recursos tiene opciones adicionales cuando se usa para definir la pertenencia a grupos.
† Cuando se enumeran series temporales, debe especificar exactamente un tipo de métrica.

En las siguientes secciones se muestran ejemplos de usos habituales de los filtros de monitorización. Consulta la sintaxis de los filtros para ver una descripción completa de los objetos y operadores de filtro disponibles.

Obtener datos de series temporales

Método: projects.timeSeries.list
Objetos de filtro: project, group.id, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

Una serie temporal es una lista de puntos de datos con marca de tiempo de un tipo de métrica de un recurso monitorizado específico. Para obtener más información, consulta El modelo de métricas. El tipo de métrica se especifica mediante un descriptor de métrica y el recurso monitorizado se especifica mediante un descriptor de recurso monitorizado.

El filtro especificado en el método timeSeries.list debe incluir un selector metric, y ese selector debe especificar exactamente un tipo de métrica:

  • Para devolver todas las series temporales de un tipo de métrica concreto, sigue estos pasos: 
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"

  • Para devolver todas las series temporales de un grupo específico. El selector group solo funciona con datos de series temporales alineados. Consulta más información en la sección Selector de grupo.

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
group.id = "2468013579"

  • Para devolver todas las series temporales de una instancia de Compute Engine específica, usa el siguiente filtro: 

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

  • Para devolver todas las series temporales de las instancias de Compute Engine cuyos nombres empiecen por frontend-, usa el siguiente filtro: 

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

  • Para devolver todas las series temporales de las instancias de Compute Engine cuyos nombres empiecen por 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).*")

Definir la pertenencia a un grupo

Método: projects.groups.create
Objetos de filtro: project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

Un grupo puede contener cualquier número de recursos, tal como se especifica en un filtro. La pertenencia a grupos es dinámica, por lo que puede que haya más o menos recursos que coincidan con el filtro cada vez que se evalúa. El parámetro name del objeto Group especifica el grupo y el proyecto de ámbito de una métrica. Si se usa el selector project en el filtro, debe especificar un proyecto cuyas métricas sean visibles para el proyecto de ámbito.

Por ejemplo, para crear un grupo que incluya solo 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-")

Para obtener información sobre los métodos de la API que puedes usar para eliminar, actualizar o enumerar grupos, consulta la página de referencia de la API projects.groups.

Miembros del grupo de fichas

Método: projects.groups.members.list
Objetos de filtro: project, resource.type, resource.labels.[KEY]

El parámetro name especifica un proyecto de ámbito de las métricas y un grupo definido en ese proyecto. Si no especifica ningún filtro, projects.groups.members.list devuelve una lista de los miembros del grupo.

Puedes usar un filtro para limitar los miembros del grupo que quieres obtener. Si el filtro incluye un selector project, el valor del selector debe especificar un proyecto cuyas métricas sean visibles para el proyecto de ámbito. Si se especifica un valor no válido, se ignora el selector project.

Por ejemplo, supongamos que crea un grupo que incluye todos los recursos cuyo nombre contiene test. Para mostrar solo los miembros del grupo que son temas de Pub/Sub, usa el siguiente filtro:

resource.type = "pubsub_topic"

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

Por ejemplo, para devolver solo los descriptores de métricas de Compute Engine, utilice el siguiente filtro: 

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

Consulta la lista de métricas para ver una lista completa de los tipos de métricas disponibles. Para ver un resumen de cómo se nombran las métricas, consulta las convenciones de nomenclatura de métricas.

Mostrar descriptores de recursos monitorizados

Método: projects.monitoredResourceDescriptors.list
Filtrar objetos: resource.type

Usa un filtro para limitar los descriptores de recursos monitorizados que recuperas.

Por ejemplo, para obtener solo los descriptores de recursos monitorizados de Pub/Sub, use el siguiente filtro: 

resource.type = starts_with("pubsub")

Consulta la lista de recursos monitorizados para ver la lista completa de los tipos de recursos monitorizados definidos por Monitoring.

Ejemplos

En los ejemplos de filtrado, usamos el siguiente descriptor de métrica, descriptor de recurso monitorizado e instancia de máquina virtual, simplificados para ilustrar el concepto:

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

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

Para acotar la solicitud y consultar el ancho de banda de lectura solo del dispositivo de disco conocido como "log_partition" en cada instancia, define el filtro de la siguiente manera. Este filtro devuelve, para cada instancia, como máximo una serie temporal, en función de 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, especifícala:

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"

Filtrar con grupos

En los siguientes ejemplos se ilustra el uso del selector de grupo en los filtros para restringir los recursos monitorizados a los que pertenecen a 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 de disco de todas las instancias de Compute Engine de un grupo concreto. El grupo debe definirse en el proyecto de ámbito de un ámbito 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 de filtro

Para ver un resumen de los filtros con ejemplos, consulta Usar filtros.

Un filtro de monitorización es una cadena que consta de hasta cuatro tipos de selectores:

    <monitoring_filter> ::=  <project_selector> AND
                             <group_selector> AND
                             <resource_selector> AND
                             <metric_selector>

El filtro coincide con un elemento si todos los selectores incluidos coinciden con él. Como se describe en las secciones siguientes, algunos selectores pueden tener varias comparaciones unidas por AND o OR. El orden de los selectores en el filtro no importa, pero las comparaciones de diferentes selectores no deben mezclarse.

En función del propósito del filtro, es posible que se requieran, se puedan usar o no se puedan usar determinados selectores. Por ejemplo, el filtro usado 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.

Comparación

Los filtros y sus selectores se crean a partir de comparaciones. Cada comparación tiene el siguiente formato:

  • [OBJECT]: selecciona un valor que se va a probar. Puede ser 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 incluirse entre comillas (").

  • [OPERATOR]: un operador de comparación. Puede ser 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 una función integrada. Puede ser 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 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:

    • Distinción entre mayúsculas y minúsculas: display_name=has_substring("Demo")
    • Distinción 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)

    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 cadena de expresión regular con la sintaxis RE2.

Puede usar los siguientes operadores para agrupar o modificar comparaciones. OR tiene mayor prioridad que AND. Los operadores deben estar escritos en mayúsculas:

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

El operador AND se puede omitir entre operadores, pero es más claro y menos propenso a errores si se incluye.

La comparación x = one_of("a", "b", "c") equivale 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 de existencia (:) ni antes de una expresión entre paréntesis:

NOT          # negates the following comparison

Selectores de filtros

Usa selectores para limitar las selecciones de filtros a determinados 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 por 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 todo el selector entre paréntesis para que sea más legible. Por ejemplo:

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

Selector de grupos

Un selector de grupo 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 obtener 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 grupo solo se permite en los filtros que se transfieren al método projects.timeSeries.list. Además, para seleccionar un grupo, los datos deben estar alineados. Es decir, la llamada projects.timeSeries.list debe incluir valores para los campos perSeriesAligner y alignmentPeriod. Esto se debe a que la pertenencia a un grupo es en sí misma un tipo de serie temporal que debe combinarse con los datos de métricas. Al proporcionar parámetros de alineación, puede controlar cómo se produce esa combinación. Para obtener más información sobre los parámetros de alineación, consulte Agregar datos.

Selector de recursos

Un selector de recursos limita la selección de filtros a los recursos (u elementos asociados a recursos) que tienen un tipo de recurso o valores de etiqueta 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>}

Si usas más de un <r_label_comparison> en tu selector, inclúyelos todos entre paréntesis para que sea más fácil de leer. Por ejemplo, se podría usar el siguiente filtro para definir un grupo que incluya todas las instancias de VM de Compute Engine de 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 definiciones de grupos

Los selectores de recursos que se usan para definir la pertenencia a un grupo usan extensiones de la sintaxis <resource_selector>:

  • Puede incluir filtros basados en el valor de las etiquetas de sistema de metadatos, metadata.system_labels.[KEY], y las etiquetas de usuario de metadatos, metadata.user_labels.[KEYSTRING]. Recomendamos poner entre comillas las claves de metadata.user_labels porque 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 la utilización de la CPU de todas las instancias de máquina virtual con el tipo de máquina 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 "no es igual a" (!=) para comparar tipos de recursos, etiquetas de recursos y metadatos. El operador se puede usar al comparar cadenas, números, valores booleanos o las funciones de subcadena. Por ejemplo, resource.type!=starts_with("gce") es true si el tipo de recurso no empieza por "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 un operador exists (:) o una expresión entre paréntesis.

  • Puedes usar el operador "exists" (:) para comprobar si existen 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 de recursos de plataforma de las instancias de VM es spot_instance. El siguiente selector de filtros elige las instancias que son instancias esporádicas:

resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

Selector de métricas

Un selector de métricas especifica determinadas métricas o descriptores de métricas limitando el tipo de métrica y las etiquetas de métrica. 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, se podría usar el siguiente filtro para obtener una serie temporal de 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")