Filtros de supervisión

Los filtros de la API de Cloud Monitoring te permiten seleccionar series temporales, tipos de métricas y recursos supervisados específicos en las solicitudes a la API.

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:

  • Selecciona los datos de series temporales específicos que se devuelven de una solicitud a la API de list. El filtro puede seleccionar series temporales en función de las propiedades de las métricas y de recurso supervisado de los datos. Para obtener más información y ejemplos, consulta Recupera datos de series temporales.

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:

  • resource: Coincide con los recursos supervisados de un tipo específico o que tienen valores de etiqueta específicos.

    • El siguiente filtro coincide con todos los recursos supervisados que son instancias de máquina virtual (VM) de Compute Engine:

      resource.type = "gce_instance"
  • metric: Coincide con un tipo de métrica o una serie temporal en particular con una etiqueta específica que coincide con un valor determinado.

    • 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 las series temporales que tienen 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 muestran los selectores que se permiten en los filtros según la llamada a la API de Monitoring:

Propósito del filtro Selector de resource Selector de metric
Enumera series temporales sí sí *
Enumerar descriptores de métrica sí
Enumera descriptores de recursos supervisados sí
* 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
Objetos de filtro: project, 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 el recurso supervisado se especifica mediante un descriptor de recurso supervisado.

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

  • Para mostrar todas las series temporales de un tipo de métrica en particular, usa el siguiente filtro:
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Para mostrar 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 mostrar todas las series temporales de las 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-")
    

  • Para mostrar todas las series temporales de las 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).*")
    

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.

Por ejemplo, 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 nombres de métricas.

Enumera descriptores de recursos supervisados

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

Usa un filtro para limitar los descriptores de recurso supervisado que recuperas.

Por ejemplo, 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 que define 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 provided 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, 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"

Para definir mejor la solicitud de consulta del 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"

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 cadena que consta de hasta dos tipos de selectores:

    <monitoring_filter> ::= <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 de diferentes selectores no deben mezclarse.

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.

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 probarlo, que puede ser uno de los siguientes:

    metric.type
    metric.labels.[KEY]
    resource.type
    resource.labels.[KEY]
        

    [KEY] es un nombre, como zone o instance_id.

    [KEYSTRING] puede ser un nombre, pero si contiene caracteres especiales, debe estar entre comillas (").

  • [OPERATOR]: Es un operador de comparación, que puede ser 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 función integrada, que puede ser una de las 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 y minúsculas o no. El valor predeterminado es false, por lo 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 formato has_substring(<string>).

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

Puedes usar los siguientes operadores para agrupar o modificar las comparaciones. OR tiene mayor prioridad que AND. Los operadores deben escribirse 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") equivale a lo siguiente:

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

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 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 entre paréntesis para mejorar la legibilidad.

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 se podría usar para recuperar 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")