Agrega filtros permanentes a un panel personalizado

En este documento, se describe cómo puedes agregar filtros permanentes a nivel de panel a tus paneles personalizados. Los filtros permanentes, que te permiten modificar los datos que muestra un panel sin tener que modificar cada widget, tienen un estado predeterminado y se pueden aplicar a todo el panel o solo a widgets específicos. La barra de herramientas del panel muestra cada filtro permanente, junto con un menú, que te permite cambiar de forma temporal el valor del filtro.

Cuando desees definir una presentación predeterminada de datos en un panel junto con opciones basadas en menús para modificar esa visualización, agrega filtros permanentes. Por ejemplo, si deseas ver las métricas de todas las zonas y también las de una zona específica, crea un filtro permanente basado en la etiqueta zone.

Puedes crear y aplicar filtros permanentes con la consola de Google Cloud o la API de Cloud Monitoring. En este documento, se describe cómo usar la consola de Google Cloud. Para obtener información sobre el uso de la API de Cloud Monitoring, consulta Crea y administra paneles por API: Filtros del panel.

Para obtener información sobre cómo agregar y modificar agrupaciones y filtros temporales, consulta Agrega filtros temporales a un panel personalizado.

Cómo funcionan los filtros del panel

Un filtro de panel especifica una etiqueta y un valor. Las series temporales que muestra el panel determinan las etiquetas disponibles para filtrar. La manera en que un widget admite un filtro en todo el panel depende del tipo de datos que muestra y de su configuración:

Para los widgets que muestran datos de series temporales, como gráficos de líneas, se aplican las siguientes reglas:
- Si las series temporales que muestra el widget no son compatibles con la etiqueta en un filtro, el filtro de todo el panel no cambia los datos que se muestran.
  
  Por ejemplo, si agregas un filtro en la etiqueta instance_id, pero un gráfico del panel no muestra datos con una etiqueta instance_id, el filtro no cambia los datos que se muestran.
- Si el widget especifica un valor para una etiqueta, el filtro de todo el panel no cambia los datos que se muestran.
  
  Por ejemplo, si agregas un filtro en la etiqueta instance_id, pero un gráfico del panel incluye un filtro basado en la etiqueta instance_id, el filtro de todo el panel no cambia los datos que se muestran.
- De lo contrario, el gráfico filtra los datos que muestra solo para las series temporales que satisfacen el filtro de todo el panel.
En el caso de los widgets del panel de registros, los filtros de todo el panel que se basan en una etiqueta de recurso actualizan la consulta. Por ejemplo, si agregas el filtro cluster_name: mycluster para todo el panel, la consulta se actualizará para incluir resource.labels."cluster_name"="mycluster".

Puedes agregar varios filtros para todo el panel. Estos filtros se unen con un operador lógico AND.

Antes de comenzar

Si quieres obtener los permisos que necesitas para agregar o modificar filtros permanentes con la consola de Google Cloud, pídele al administrador que te otorgue el rol de IAM de Editor de Monitoring (roles/monitoring.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Para obtener más información sobre las funciones, consulta Controla el acceso con Identity and Access Management.

Crear un filtro permanente

Cuando diseñas un panel, puedes identificar varias formas de ver los datos que muestra. Por ejemplo, cuando en un panel se muestran métricas para instancias de VM, es posible que desees ver las métricas de todas las VM y que desees ver las métricas de las VM de una zona específica. Puedes crear un filtro permanente para la etiqueta zone con el valor predeterminado establecido en todas las zonas, *. Cuando veas el panel, puedes usar el menú del filtro zone para seleccionar una zona específica.

Puedes restringir un filtro permanente a widgets específicos. Imagina una situación en la que deseas una vista en paralelo de las métricas de las VM en dos zonas diferentes. Creas dos colecciones de gráficos y un filtro para cada colección. Tu configuración predeterminada satisface tu objetivo original. Sin embargo, cuando visualizas el panel, la barra de herramientas enumera tus variables e incluye menús para que puedas seleccionar valores diferentes. Puedes usar estos menús para ver datos de diferentes zonas.

Los filtros permanentes que se aplican solo a widgets específicos a veces se denominan variables de plantilla. Después de crear un filtro de este tipo, cuando agregues un widget a tu panel, también podrás aplicar el filtro a ese widget. Para obtener más información, consulta Aplica un filtro permanente a un widget.

Para crear un filtro permanente, haz lo siguiente:

En el panel de navegación de la consola de Google Cloud, selecciona Monitoring y, luego, elige Paneles:
Ir a Paneles
En la barra de herramientas del panel, haz clic en Configuración y, luego, selecciona Administrar filtros.
Haz clic en Label y, luego, selecciónala. Por ejemplo, puedes seleccionar zone.
Haz clic en Valor predeterminado y, luego, selecciona el valor predeterminado para la etiqueta. Para que coincidan todos los valores, selecciona *.

Nota: Cuando los paneles contienen gráficos definidos por MQL, es posible que el menú de valores de un filtro no se cargue o que el menú no contenga los valores correctos. Sin embargo, puedes ingresar el valor del filtro de forma manual.

Después de crear el filtro, este se agrega a la barra de herramientas de tu panel. Para cambiar temporalmente el valor del filtro, haz clic en el filtro y selecciona una opción en el menú.
Realiza una de las acciones siguientes:
- Para aplicar el filtro a todos los widgets del panel, selecciona Aplicar a todo y, luego, Aplicar.
- Para aplicar el filtro a algunos widgets del panel, haz lo siguiente:
  1. Desmarca la opción Aplicar a todas.
  2. En el cuadro de texto Nombre de la variable, ingresa un nombre visible para la variable.
  3. Expande el menú Apply to graphics, selecciona los widgets a los que se aplica el filtro y, luego, selecciona OK.
    
    Nota: Para los paneles de registro y los gráficos configurados mediante MQL o PromQL, debes editar la configuración del widget. No puedes seleccionar estos widgets desde el menú Aplicar a los gráficos. Para obtener más información, consulta Aplica un filtro permanente a un widget.
  4. Haz clic en Aplicar.

Cómo aplicar un filtro permanente a un widget

Para aplicar un filtro permanente a un widget, debes asociar ese widget con la variable:

Para los gráficos que configuras mediante los menús, puedes realizar esta asociación cuando creas o editas el filtro.
Para el panel de registros, edita el widget y configura la consulta predeterminada. Asegúrate de seguir las instrucciones de la sección Sintaxis para aplicar un filtro permanente.
Para los gráficos y las tablas definidos en MQL o PromQL, edita el gráfico o la tabla y, luego, modifica el MQL o PromQL. Asegúrate de seguir las instrucciones de la sección Sintaxis para aplicar un filtro permanente.

Sintaxis para aplicar un filtro permanente

Por ejemplo, a continuación se muestra la representación parcial en JSON de un panel que define una variable de plantilla y un filtro para todo el panel:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

En el JSON que se muestra, la primera entrada en la estructura dashboardFilters es para una variable de plantilla con el nombre iid y un filtro para todo el panel con la clave de etiqueta zone. La variable de plantilla es un alias de la etiqueta instance_id.

La estructura de datos de una variable de plantilla no enumera los widgets a los que se aplica. En su lugar, asocias un widget con una variable de plantilla modificando la consulta del widget para incluir una referencia a la variable. Cuando el widget se muestra en el panel, el valor de la variable de la plantilla se resuelve.

Consulta las siguientes secciones para saber cómo anotar paneles y gráficos de registros:

Panel de registros
Gráficos y tablas definidos por MQL
Gráficos y tablas definidos por PromQL
Gráficos y tablas definidos con filtros de series temporales

Panel de registros

Para configurar un panel de registros a fin de filtrar la visualización según el valor de una variable de plantilla, agrega la variable al panel de consultas. En el siguiente ejemplo, se muestra una consulta que filtra por el valor de la variable de plantilla iid:

${iid}

Antes de que el panel de registros consulte los registros para mostrar, se resuelve la variable de la plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la instrucción resource.labels."instance_id"="12345".

También puedes incluir solo el valor de una variable de plantilla en una consulta. Te recomendamos que solo uses el valor como parte de un filtro definido con una expresión regular. Por ejemplo, la siguiente consulta usa una expresión regular para hacer coincidir las entradas de registro que tienen una carga útil de JSON que contiene la string descrita:

jsonPayload.message=~"Connected to instance: ${iid.value}"

Si configuraste una consulta para el panel de registros y, luego, seleccionas el botón a fin de abrir el Explorador de registros, las variables de plantilla se resuelven antes de que se abra el Explorador de registros.

En la siguiente tabla, se muestra cómo el panel de registros resuelve la variable de la plantilla:

Sintaxis	Valor seleccionado	Expresión de panel de registros resuelto
`${iid}`	`12345`	`resource.labels."instance_id"="12345"`
`${iid}`	`*`	`""`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

Gráficos y tablas definidos por MQL

Cuando uses el lenguaje de consulta de Monitoring (MQL) para configurar un gráfico, agrega una canalización y la variable a la cadena de consulta:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}

Antes de que se realicen las consultas de gráfico para las series temporales que se mostrarán, se resolverá la variable de la plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la instrucción filter (resource.instance_id == '12345'). Este filtro coincide con series temporales que tienen una etiqueta llamada resource.instance_id y solo cuando el valor de esa etiqueta es exactamente 12345.

Cuando desees filtrar series temporales mediante una expresión regular, configura la consulta para que incluya solo el valor de la variable de plantilla. Para ilustrar la sintaxis, a continuación se muestra cómo usar una expresión regular a fin de determinar si el valor de la etiqueta resource.instance_id contiene el valor de la variable de plantilla iid:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla para las consultas de MQL:

Sintaxis	Valor seleccionado	Expresión de MQL resuelta
`${iid}`	`12345`	`filter (resource.instance_id == '12345')`
`${iid}`	`*`	`filter (true)`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

Gráficos y tablas definidos en PromQL

Cuando definas un gráfico con PromQL, agrega a la cadena de consulta la variable unida por llaves:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Al igual que en MQL, cuando defines un widget con PromQL, la consulta puede extraer solo el valor de la variable de plantilla. Te recomendamos que solo uses el valor como parte de un filtro definido con una expresión regular. Para ilustrar la sintaxis, a continuación se muestra cómo usar una expresión regular para determinar si el valor de la etiqueta instance_id contiene el valor de la variable de plantilla iid:

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${iid.value}"
}

En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla para las consultas de PromQL:

Sintaxis	Valor seleccionado	Expresión de PromQL resuelta
`${iid}`	`12345`	`instance_id == '12345'`
`${iid}`	`*`	`noop_filter=~".*"`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.+`

Gráficos y tablas definidos con filtros de series temporales

Cuando definas un gráfico con filtros de series temporales, agrega la variable a la string de filtro:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

A diferencia de los gráficos definidos por MQL y PromQL, no puedes usar el valor de una variable de plantilla en un filtro de series temporales.

En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla:

Sintaxis	Valor seleccionado	Expresión de filtro resuelta
`${iid}`	`12345`	`resource.instance_id == "12345"`
`${iid}`	`*`	Omitido
`${iid.value}`	`12345`	No compatible
`${iid.value}`	`*`	No compatible

Cómo modificar un filtro permanente

Para cambiar de forma temporal el valor de cualquier filtro que se muestra en la barra de herramientas del panel, haz clic en el nombre del filtro y, luego, ingresa un valor o realiza una selección en el menú.

Para cambiar la configuración de un filtro permanente, haz lo siguiente:

En el panel de navegación de la consola de Google Cloud, selecciona Monitoring y, luego, elige Paneles:
Ir a Paneles
En la barra de herramientas del panel, haz clic en Configuración y, luego, selecciona Administrar filtros.
Busca el filtro que deseas modificar y, luego, usa los menús para hacer las modificaciones.
Haz clic en Aplicar.

Cómo borrar un filtro permanente

En el panel de navegación de la consola de Google Cloud, selecciona Monitoring y, luego, elige Paneles:
Ir a Paneles
En la barra de herramientas del panel, haz clic en Configuración y, luego, selecciona Administrar filtros.
Busca el filtro que deseas quitar y, luego, haz clic en Borrar.
Haz clic en Aplicar.