Es posible que parte o toda la información de esta página no se aplique a Cloud de Confiance de S3NS. Para obtener más información, consulta Diferencias con respecto a Google Cloud.

Esta página se ha traducido con Cloud Translation API.

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 y las series temporales.

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 de las propiedades de los recursos monitorizados y de las propiedades de las métricas. Para obtener más información y ejemplos, consulta Recuperar datos de series temporales.

Lista de tipos de métricas concretos. Para obtener más información y ejemplos, consulta Listar descriptores de métricas.
Lista tipos de recursos monitorizados concretos. Para obtener más información y ejemplos, consulta Listar descriptores de recursos monitorizados.

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:

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"
```
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 `resource`	Selector de `metric`
List time series	yes	Sí ^*
Enumerar descriptores de métricas		yes
Mostrar descriptores de recursos monitorizados	yes

^* 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, 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 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).*")

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"

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 dos tipos de selectores:

    <monitoring_filter> ::= <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.

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:
```
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 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")

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

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