Crear y gestionar variables y filtros fijados

En este documento se describe cómo puedes fijar filtros a nivel de panel de control para que sean permanentes. Los filtros fijados, que te permiten modificar los datos que se muestran en un panel de control sin tener que modificar cada widget, tienen un estado predeterminado y se aplican a todo el panel. La barra de herramientas del panel de control muestra cada filtro fijado junto con un menú que te permite cambiar temporalmente el valor del filtro.

Las variables son similares a los filtros fijados, pero solo se aplican a widgets específicos. En este documento se describe cómo crear variables y cómo aplicarlas con un widget. Una variable puede modificar la consulta del widget o controlar su visibilidad. La barra de herramientas del panel de control muestra cada variable por su nombre, junto con un menú que te permite cambiar temporalmente el valor de la variable. Para ayudarte a diferenciar los filtros de las variables, en la barra de herramientas, el nombre de una variable va precedido del signo de dólar $.

En este documento se describe cómo usar la consola Google Cloud para crear variables y filtros fijados. Para obtener información sobre cómo usar la API Cloud Monitoring, consulta Crear y gestionar paneles de control mediante la API: filtros de panel de control.

Para obtener información sobre cómo añadir y modificar agrupaciones y filtros temporales, que solo se aplican a la sesión actual, consulta Añadir filtros temporales a un panel de control personalizado.

Esta función solo se admite en proyectos de Google Cloud . En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

Acerca de los filtros fijados

Un filtro fijado contiene una etiqueta, uno o varios valores predeterminados y una lista de todos los valores posibles. La lista de todos los valores posibles se deriva dinámicamente de los datos de serie temporal que se muestran en el panel de control. Para obtener información sobre la estructura de un filtro, consulta DashboardFilter.

No se aplica un filtro fijado a widgets concretos. En su lugar, se usan las siguientes reglas para determinar si el filtro fijado puede cambiar los datos que muestra el widget:

• Si el widget muestra datos que incluyen la clave de etiqueta especificada por un filtro fijado y no especifica ningún valor para esa clave de etiqueta, el filtro fijado puede cambiar los datos que se muestran.

  Por ejemplo, supongamos que añade el filtro fijado cluster_name: mycluster. A continuación, los gráficos mostrarán automáticamente solo las series temporales que tengan una etiqueta cluster_name con el valor mycluster. Del mismo modo, las consultas de los widgets del panel de registros se modifican a resource.labels."cluster_name"="mycluster" y los gráficos muestran automáticamente solo las series temporales que incluyen la etiqueta en el filtro fijado.

• Un widget ignora un filtro fijado cuando incluye un filtro para la misma clave de etiqueta o cuando los datos que muestra no contienen la clave de etiqueta especificada en el filtro fijado.

Acerca de las variables

Una variable tiene un nombre y un tipo. Para aplicar una variable a un widget concreto, modifica la consulta que contiene el widget. Para obtener información sobre la estructura de un filtro, consulta DashboardFilter.

En la barra de herramientas del panel de control, los nombres de las variables van precedidos del signo de dólar $. Si también ves el icono visibility Visible, significa que la variable controla la visibilidad de al menos un widget.

Las variables pueden basarse en etiquetas o solo tener un valor:

• Las variables basadas en etiquetas son como filtros fijados. Estas variables contienen una clave de etiqueta, uno o varios valores de etiqueta predeterminados y una lista de todos los valores de etiqueta posibles. La lista de todos los valores posibles se deriva dinámicamente de los datos de serie temporal que se muestran en el panel de control.

• Las variables de solo valor contienen uno o varios valores predeterminados y pueden enumerar todos los valores posibles. Si no especifica ningún valor predeterminado, se seleccionará el operador comodín (*). Para definir el conjunto de todos los valores posibles, puedes proporcionar una matriz de valores o escribir una consulta SQL.

  Hay tres tipos de variables de solo valor: Personalizada, Entrada de texto y Consulta de SQL.

  • Personalizado: úsalo cuando quieras enumerar la lista de todos los valores posibles y definir uno o varios valores predeterminados. Por ejemplo, puedes definir la lista de todos los valores posibles como prod, staging, dev y el valor predeterminado como prod.

  • Entrada de texto: úsala cuando no sepas todos los valores posibles. Por ejemplo, puede que quiera filtrar por URL, pero cuando cree la variable, no sabrá la lista exacta de URLs. Después, cuando use el menú de filtros del widget, podrá introducir nuevas URLs y guardar los cambios en la sesión actual o en la definición de la variable.

  • Consulta de SQL: úsala cuando quieras generar la lista de valores posibles mediante una consulta de SQL. Estas variables se deben aplicar a los gráficos creados con Analíticas de registros.

    En el caso de estas variables, asegúrate de que el resultado de la consulta sea una tabla con una columna, de que el tipo de datos de esa columna sea una cadena y de que cada fila de la tabla contenga un valor de cadena único:

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    La consulta SQL no puede depender de una variable.

Para aplicar una variable a un widget, puedes actualizar la consulta emitida por el widget o la visibilidad del widget. Siempre puedes editar el widget para actualizar su consulta. Sin embargo, en el caso de las variables basadas en etiquetas y algunos tipos de widgets, puede actualizar la consulta seleccionando opciones en el menú. Para controlar la visibilidad, debes editar el widget. Para obtener más información, consulta las siguientes secciones de este documento:

• Actualizar la consulta de un widget
• Definir la visibilidad de un widget

Antes de empezar

Completa los siguientes pasos en el Google Cloud proyecto en el que quieras configurar filtros y variables:

• Para obtener los permisos que necesitas para añadir o modificar variables o filtros fijados mediante la consola Google Cloud , pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Monitoring (roles/monitoring.editor) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

  También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

  Para obtener más información sobre los roles, consulta Controlar el acceso con Gestión de Identidades y Accesos.

Crear y fijar un filtro

Para crear y fijar un filtro que se aplique a todos los widgets del panel de control que admitan filtros, siga estos pasos:

1. En la Google Cloud consola, ve a la página  Paneles de control:

   Ve a Paneles.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
3. Selecciona un panel de control, ve a la barra de herramientas del panel y haz clic en settings Configuración.
4. En la sección Filtros, haz clic en Añadir un filtro.
5. Haz clic en arrow_drop_down Etiqueta y, a continuación, selecciona una etiqueta. Por ejemplo, puedes seleccionar zone.
6. Para permitir que un usuario seleccione varios valores del menú de valores de la variable, selecciona Selección múltiple. Si Selección múltiple no está habilitada, los usuarios solo pueden seleccionar una opción del menú de valores.

7. Haga clic en arrow_drop_down Valor predeterminado y, a continuación, seleccione el valor o los valores predeterminados de la etiqueta. Para que coincidan todos los valores, selecciona *.

   Una vez creado el filtro, se añade a la barra de herramientas del panel de control. Para cambiar temporalmente el valor del filtro, selecciona el filtro y, a continuación, elige una opción en el menú.

8. Haz clic en Hecho y, a continuación, en Aplicar.

9. Para guardar el panel de control modificado, haz clic en Guardar en la barra de herramientas.

Crear una variable

Para crear una variable que se aplique a widgets de panel de control específicos, haz lo siguiente:

1. En la Google Cloud consola, ve a la página  Paneles de control:

   Ve a Paneles.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
3. Selecciona un panel de control, ve a la barra de herramientas del panel y haz clic en settings Configuración.
4. En la sección Variables, haga clic en Añadir una variable.

5. Seleccione el tipo de variable y, a continuación, complete el cuadro de diálogo.

   Para crear una variable basada en etiquetas, selecciona Etiqueta. Usa esta opción cuando quieras una variable que tenga una clave y un valor de etiqueta, y que se pueda usar como un filtro. La lista de todos los valores posibles se deriva dinámicamente de los datos de serie temporal que se muestran en el panel de control. El menú Aplicar a los gráficos te permite seleccionar los widgets cuya consulta se va a modificar con la variable. También puedes actualizar la consulta editando el widget.

   En el caso de las variables de solo valor, tienes las siguientes opciones:

   • SQL: usa esta opción cuando quieras que los resultados de una consulta de SQL generen la lista de todos los valores posibles.

     Introduce uno o varios valores predeterminados y una consulta SQL que genere la lista de todos los valores posibles. Asegúrate de que el resultado de la consulta sea una tabla con una columna, de que el tipo de datos de esa columna sea una cadena y de que cada fila de la tabla contenga un valor de cadena único.

   • Personalizado: usa esta opción cuando quieras especificar tanto la lista de valores posibles como un valor predeterminado. Por ejemplo, puedes asignar el valor prod, staging, dev al campo Valores y el valor prod al campo Valor predeterminado.

   • Entrada de texto: usa esta opción cuando quieras especificar una lista de valores que se apliquen de forma predeterminada.

6. Haz clic en Hecho y, a continuación, en Aplicar.

7. Para guardar el panel de control modificado, haz clic en Guardar en la barra de herramientas.

8. Aplica la variable a los widgets. Si actualiza la consulta de un widget, cuando cambie el valor de la variable, la consulta se modificará y los datos que muestre el widget también. También puedes usar una variable para controlar si un widget está visible. Para obtener más información, consulta las siguientes secciones de este documento:

   • Definir la visibilidad de un widget
   • Actualizar la consulta de un widget

Definir la visibilidad de un widget

Cuando un widget consulta datos, puedes usar una variable para controlar si el widget se muestra en un panel de control. Por ejemplo, supongamos que un panel de control contiene widgets que muestran datos de tus sistemas de producción y otro conjunto de widgets que muestran datos de tus sistemas de pruebas. Cuando depures durante el desarrollo, puede que solo quieras ver los datos de la fase de pruebas. Si configuras la visibilidad de los widgets del panel de control con una variable, puedes alternar entre los datos de producción, los datos de la fase de pruebas y todos los datos.

Cualquier tipo de variable puede controlar si un widget está visible u oculto.

Para configurar la visibilidad de un widget, haz lo siguiente:

1. En la Google Cloud consola, ve a la página  Paneles de control:

   Ve a Paneles.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. Selecciona un panel de control.
3. Ve a la barra de herramientas del widget cuya visibilidad quieras configurar y haz clic en edit Editar.
4. En el panel Pantalla, despliega Visibilidad del widget.

5. Selecciona una variable y completa el cuadro de diálogo.

6. Haz clic en Hecho y, a continuación, en Aplicar.

7. Para guardar el panel de control modificado, haz clic en Guardar en la barra de herramientas.

   El panel de control se actualiza. Cuando se oculta al menos un widget del panel de control debido a los controles de visibilidad, el panel de control muestra un banner. Para ver todos los widgets, haz clic en Mostrar todos los widgets.

Cuando usas una variable para controlar la visibilidad de al menos un widget en tu panel de control, en la barra de herramientas, el nombre de la variable se anota con el icono visibility Visible.

Limitaciones

Se aplican las siguientes limitaciones al configurar la visibilidad de un widget:

• Los widgets organizativos, como los de grupo contraíble, encabezado de sección y vista única, siempre están visibles.

• Puede eliminar una variable a la que hagan referencia los controles de visibilidad de un widget. La acción de eliminación de variables también quita cualquier referencia a la variable.

• No todos los paneles de control admiten la creación de variables. Sin embargo, si un panel de control contiene variables, puedes usar esas variables para gestionar la visibilidad de los widgets del panel.

Actualizar la consulta de un widget

En esta sección se describe cómo incluir variables en la consulta que emite el widget. Por lo tanto, cuando cambias el valor de la variable, la consulta se modifica y los datos que muestra el widget también:

• En el caso de los gráficos que usan consultas SQL o PromQL, y de los widgets del panel de registros, debe editar el widget y modificar la consulta. En esta sección se describe cómo hacer esos cambios.

• En los gráficos que hayas configurado mediante menús o el modo de filtro directo, Monitoring edita la consulta cuando seleccionas el widget con el menú Aplicar a gráficos. También puedes editar el widget, ir al campo Filtro y seleccionar la variable.

Para saber cómo actualizar la consulta de un widget con una variable basada en etiquetas o una variable de solo valor, consulta las siguientes secciones:

• Sintaxis general para desreferenciar una variable
• Widgets del panel de registros
• Gráficos con consultas de PromQL
• Gráficos con consultas de SQL

• Gráficos con consultas de filtros de Monitoring

  Cuando usas la interfaz basada en menús para crear un gráfico que muestra datos de serie temporal, tus selecciones se convierten en un filtro de monitorización.

Crear filtros y variables

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

Sintaxis general para desreferenciar una variable

En todos los widgets, excepto en los que se definen mediante SQL, usa la siguiente sintaxis para aplicar una variable a una consulta:

• Para aplicar una variable basada en etiquetas y que la clave y el valor de la etiqueta se resuelvan en una expresión de filtro válida para el lenguaje de consulta, usa ${my_label_based_variable}.

• Para aplicar solo el valor de una variable basada en etiquetas, usa ${my_label_based_variable.value}. La comparación debe usar una expresión regular.

• Para aplicar solo el valor de una variable de solo valor, use ${my_value_only_variable}. En el caso de las variables que solo tienen valor, no incluyas una cláusula .value. La comparación debe usar una expresión regular.

Widgets del panel de registros

Para aplicar una variable a un widget de panel de registros, actualiza el panel de consultas. La sintaxis de estos widgets sigue la que se especifica en Sintaxis general.

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

severity =~ "${value_only_severity_variable}"

severity =~ "^(ERROR|INFO|NOTICE)$"

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

severity =~ "^(ERROR|INFO|NOTICE)$"

Si has configurado una consulta para el panel de registros y, a continuación, seleccionas el botón para abrir el Explorador de registros, las variables se resuelven antes de que se abra el Explorador de registros.

En la siguiente tabla se muestra cómo resuelve el panel de registros las variables de ejemplo. Como se ha mencionado anteriormente, cuando solo se usa el valor de una variable, debe usar una expresión regular como operador de comparación:

Gráficos con consultas de PromQL

Para actualizar un gráfico que tenga una consulta de PromQL para que dependa de una variable basada en etiquetas, sigue las directrices que se indican en Sintaxis general.

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

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

zone=~"${my_value_only_variable}"

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

zone=~\"${my_value_only_variable}\"

En la siguiente tabla se muestra cómo resuelve PromQL las variables de ejemplo. Como se ha mencionado anteriormente, cuando solo se usa el valor de una variable, debe usar una expresión regular como operador de comparación:

Gráficos con consultas de SQL

Si quieres actualizar un widget definido por SQL para que dependa de una variable, actualiza la cláusula WHERE para que haga referencia al valor de la variable. En todas las variables, añade el signo "arroba" al principio del nombre de la variable. Por ejemplo: @variable_name. En el caso de las variables basadas en etiquetas, añade .value al nombre de la variable, @my_label_based_variabe.value.

En el caso de las consultas SQL, la sustitución de variables se basa en BigQuery y es segura frente a inyecciones de SQL. Para obtener más información, consulta Ejecutar consultas parametrizadas.

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Gráficos con consultas de filtros de Monitoring

Para actualizar un gráfico que tenga una consulta en forma de filtro de monitorización para que dependa de una variable basada en etiquetas, sigue las directrices que se indican en Sintaxis general.

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

En la siguiente tabla se muestra cómo resuelve el filtro de Monitoring las variables de ejemplo. Como se ha mencionado anteriormente, cuando solo se usa el valor de una variable, debe usar una expresión regular como operador de comparación:

Modificar un filtro o una variable fijados

Para cambiar temporalmente el valor de cualquier filtro que se muestre en la barra de herramientas del panel de control, haga clic en el nombre del filtro e introduzca un valor o seleccione una opción en el menú.

Si tu panel de control contiene una tabla que muestra datos de serie temporal, puedes añadir filtros temporales o modificar filtros y variables permanentes usando el botón filter_list Filtrar panel de control por este valor de una celda. Cuando se selecciona este botón, se aplica un nuevo filtro temporal o se actualiza el valor de un filtro o una variable. Los filtros y las variables se actualizan cuando la clave de etiqueta de la columna de la tabla coincide con la clave de etiqueta de un filtro o una variable.

Para cambiar la configuración de un filtro fijado o de una variable, siga estos pasos:

1. En la Google Cloud consola, ve a la página  Paneles de control:

   Ve a Paneles.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
3. En la barra de herramientas del panel de control, haz clic en settings Configuración.
4. Busca el filtro o la variable que quieras modificar y despliega su definición.
5. Cuando hayas terminado de hacer los cambios, haz clic en Aplicar.
6. Para guardar el panel de control modificado, haz clic en Guardar en la barra de herramientas.

Eliminar un filtro o una variable fijados

Para eliminar un filtro o una variable fijados, sigue estos pasos:

1. En la Google Cloud consola, ve a la página  Paneles de control:

   Ve a Paneles.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
3. En la barra de herramientas del panel de control, haz clic en settings Configuración.
4. Busca el filtro o la variable que quieras quitar y, a continuación, haz clic en delete Eliminar.
5. Haz clic en Aplicar.
6. Para guardar el panel de control modificado, haz clic en Guardar en la barra de herramientas.

Siguientes pasos

• Examinar los datos de gráficos
• Acceder a paneles de control específicos de recursos