Crea y administra variables y filtros fijados

Los filtros y las variables fijados en un panel personalizado de Cloud Monitoring te permiten cambiar de forma dinámica los datos que se muestran en el panel desde la barra de herramientas sin editar widgets individuales. Los filtros fijados se aplican a todos los widgets que admiten la etiqueta del filtro, mientras que las variables se aplican a widgets específicos para modificar sus consultas o controlar su visibilidad.

En este documento, se describe cómo configurar filtros y variables fijados en la consola deGoogle Cloud . Para configurarlos con la API de Cloud Monitoring, consulta Crea y administra paneles con la API: Filtros de paneles. Para aplicar filtros o agrupaciones solo a tu sesión actual, consulta Agrega filtros temporales a un panel personalizado.

Acerca de los filtros fijados

Un filtro fijado contiene una etiqueta, uno o más valores predeterminados y una lista de todos los valores posibles. La lista de todos los valores posibles se deriva de forma dinámica de los datos de series temporales que se muestran en tu panel.

No aplicas un filtro fijado a widgets individuales. En cambio, 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 si el widget no especifica un valor para esa clave de etiqueta, el filtro fijado puede cambiar los datos que se muestran.

    Por ejemplo, supongamos que agregas el filtro fijado cluster_name: mycluster. Luego, los gráficos muestran automáticamente solo las series temporales que tienen una etiqueta cluster_name con un valor de mycluster. Del mismo modo, las consultas en 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 el widget incluye un filtro para la misma clave de etiqueta o cuando los datos que muestra el widget no contienen la clave de etiqueta especificada en el filtro fijado.

En la API, los filtros fijados se definen con la estructura DashboardFilter. Por ejemplo, la siguiente estructura define un filtro fijado. Las series temporales que tienen una etiqueta zone cuyo valor es us-central1-c coinciden con el filtro fijado.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

Acerca de las variables

Al igual que los filtros fijados, una variable tiene un nombre y un tipo, y uno o más valores predeterminados. Sin embargo, a diferencia de los filtros fijados, que siempre se basan en etiquetas, las variables no tienen que depender de las etiquetas.

Para aplicar una variable a un widget en particular, se modifica la consulta que contiene el widget.

En la barra de herramientas del panel, los nombres de las variables se anteponen con un signo de dólar $. Si también ves un ícono Visible, la variable controla la visibilidad de, al menos, un widget.

Las variables definidas por el usuario 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 más valores de etiqueta predeterminados y una lista de todos los valores de etiqueta posibles. La lista de todos los valores posibles se deriva de forma dinámica de los datos de series temporales que se muestran en tu panel.

  • Las variables de solo valor contienen uno o más valores predeterminados y pueden enumerar todos los valores posibles. Si no especificas un valor predeterminado, se selecciona el operador comodín, (*), para el valor predeterminado. Para definir el conjunto de todos los valores posibles, proporciona un array de valores o escribe una consulta en SQL.

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

    • Personalizado: Se usa cuando quieres enumerar la lista de todos los valores posibles y, además, establecer uno o más valores predeterminados. Por ejemplo, puedes establecer la lista de todos los valores posibles en prod, staging, dev y establecer el valor predeterminado en prod.

    • Entrada de texto: Se usa cuando no conoces todos los valores posibles. Cuando creas esta variable, puedes especificar uno o más valores. Sin embargo, la opción de menú te permite agregar valores nuevos que se aplican a tu sesión actual.

    • Consulta en SQL: Se usa cuando quieres generar la lista de valores posibles con una consulta en SQL. Estas variables se aplican a los gráficos creados con las Estadísticas de observabilidad.

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

      SELECT log_name
FROM `VIEW`
GROUP BY log_name

      La consulta en SQL no puede depender de una variable.

Existe una variable definida por el sistema, @__project_id. Puedes usar esta variable solo en la cláusula FROM para las consultas en SQL. Para aprender a aplicar esta variable a una consulta, consulta Gráficos con consultas en SQL.

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

En la API, las variables se definen con la estructura DashboardFilter. Por ejemplo, la siguiente estructura define la variable my_zone_variable que opera en la etiqueta de recurso zone. Las series temporales que tienen una etiqueta zone cuyo valor es us-central1-c coinciden con la variable.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

Antes de comenzar

Completa lo siguiente para el proyecto de Google Cloud en el que deseas configurar filtros y variables fijados:

Cómo crear y fijar un filtro

Para crear y fijar un filtro que se aplique a todos los widgets del panel que admiten filtros, haz lo siguiente:

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
  3. Selecciona un panel, ve a la barra de herramientas del panel y, luego, haz clic en Configuración.
  4. En la sección Filtros, haz clic en Agregar un filtro.
  5. Haz clic en Etiqueta y, luego, selecciona una etiqueta. Por ejemplo, puedes seleccionar zone.
  6. Para permitir que los usuarios seleccionen varios valores del menú de valores del filtro, elige Selección múltiple. Cuando la opción Selección múltiple no está habilitada, los usuarios solo pueden seleccionar una opción del menú de valores.

  7. Haz clic en Valor predeterminado y, luego, selecciona el valor o los valores predeterminados para la etiqueta. Para que coincida con todos los valores, selecciona *.

    Después de crear el filtro, se agrega a la barra de herramientas del panel. Para cambiar temporalmente el valor del filtro, selecciona el filtro y, luego, elige una opción en el menú.

  8. Haz clic en Listo y, luego, en Aplicar.

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

Crea una variable

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

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
  3. Selecciona un panel, ve a la barra de herramientas del panel y, luego, haz clic en Configuración.
  4. En la sección Variables, haz clic en Agregar una variable.

  5. Selecciona el tipo de variable y, luego, completa el 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 fijado. La lista de todos los valores posibles se deriva de forma dinámica de los datos de series temporales que se muestran en tu panel. El menú Aplicar a gráficos te permite seleccionar widgets cuya consulta se modificará con la variable. También puedes actualizar la consulta editando el widget.

    Para las variables de solo valor, tienes las siguientes opciones:

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

      Ingresa uno o más valores predeterminados y una consulta en 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, que el tipo de datos de esa columna sea una cadena y que cada fila de la tabla contenga un valor de cadena único.

    • Personalizado: Usa esta opción cuando quieras especificar la lista de valores posibles y un valor predeterminado. Por ejemplo, puedes establecer el campo Valores en prod, staging, dev y el Valor predeterminado en prod.

    • Entrada de texto: Usa esta opción cuando quieras especificar una lista de valores que se aplican como predeterminados.

  6. Haz clic en Listo y, luego, en Aplicar.

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

    Monitoring agrega la variable a la barra de herramientas del panel. El nombre en la barra de herramientas es un signo de dólar $ seguido del nombre de la variable. La barra de herramientas contiene un menú que te permite cambiar el valor de la variable.

  8. Opcional: Mueve tu variable de la barra de herramientas del panel a un widget del panel.

    Puedes agregar un widget a tu panel que te permita modificar el valor de tu variable. Si realizas este cambio, se quitará la variable de la barra de herramientas. Sin embargo, puedes colocar el widget que controla la variable junto a los widgets que afecta. Para aprender a realizar este cambio, consulta Agrega un widget para administrar el valor de una variable.

  9. Aplica la variable a los widgets. Si actualizas la consulta de un widget, cuando cambias el valor de la variable, se modifica la consulta y se modifican los datos que muestra el widget. También puedes usar una variable para controlar si un widget es visible. Para obtener más información, consulta las siguientes secciones de este documento:

Agrega un widget para administrar el valor de una variable

Debido a que las variables se aplican a un subconjunto de widgets del panel, es posible que desees agrupar el control de la variable y los widgets a los que se aplica. Por ejemplo, puedes crear un grupo contraíble o una sección en el panel para el menú de variables y los widgets asociados. Esta estrategia también simplifica la barra de herramientas, ya que quita las variables que no se aplican a todos los widgets.

Para administrar el valor de una variable con un widget de panel, haz lo siguiente:

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
  3. En el cuadro de diálogo Agregar widget, ve a la sección Diseño y, luego, selecciona Variable.

  4. Completa el diálogo y, luego, selecciona Guardar.

    En el panel, se muestra un widget que te permite seleccionar el valor de tu variable. Puedes mover este widget a un grupo contraíble o cambiar su posición.

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

Cómo configurar la visibilidad de un widget

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

Cualquier tipo de variable puede controlar si un widget está visible o no.

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

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

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

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

  6. Haz clic en Listo y, luego, en Aplicar.

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

    Se actualizará el panel. Cuando se oculta al menos un widget del panel debido a los controles de visibilidad, el panel 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, en la barra de herramientas, el nombre de la variable se anota con un ícono de Visible.

Limitaciones

Se aplican las siguientes limitaciones cuando configuras 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.

  • Puedes borrar una variable a la que hacen referencia los controles de visibilidad de un widget. La acción variable-delete también quita cualquier referencia a la variable.

  • No todos los paneles admiten la creación de variables. Sin embargo, si un panel contiene variables, puedes usarlas para administrar la visibilidad de los widgets en el panel.

Actualiza la consulta de un widget

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

  • En el caso de los gráficos que usan consultas en SQL o PromQL, y para los widgets del panel de registros, debes editar el widget y modificar la consulta. En esta sección, se describe cómo realizar esas modificaciones.

  • Para los gráficos que configuraste con menús o con el modo de filtro directo, Monitoring edita la consulta cuando seleccionas el widget con el menú Aplicar a los gráficos. Como alternativa, puedes editar el widget, ir al campo Filtro y, luego, seleccionar la variable.

Para aprender a actualizar la consulta de un widget con una variable basada en etiquetas o una variable de solo valor, consulta las siguientes secciones:

Crea filtros y variables

Console

Para obtener información sobre cómo usar la consola de Google Cloud para crear filtros y variables fijados, consulta los siguientes documentos:

REST

Para definir filtros y variables fijados, usa la estructura de datos dashboardFilters.

  • Para crear una variable, establece el valor del campo templateVariable en el nombre de la variable. Omite este campo o establece el valor en una cadena vacía cuando quieras crear un filtro fijado.
  • Para crear un filtro fijado o una variable basada en etiquetas, debes especificar el campo labelKey. Omite este campo cuando quieras una variable de solo valor.

  • Establece el valor predeterminado para el filtro o la variable. La configuración de este campo determina si un usuario puede seleccionar exactamente una opción del menú de valores o si puede seleccionar varios valores.

  • Para establecer un solo valor predeterminado y restringir a los usuarios para que seleccionen exactamente una opción en el menú de valores, establece el campo valueType como STRING y también establece el campo stringValue:

    "valueType": "STRING",
"stringValue": "my-default-value",

  • Para establecer al menos un valor predeterminado y permitir que los usuarios seleccionen varias opciones en el menú de valores, establece el campo valueType como STRING_ARRAY y también establece el campo stringArrayValue. En el siguiente ejemplo, hay tres valores predeterminados.

    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Opcional: Para especificar la lista de todos los valores posibles de una variable de solo valor, configura el campo stringArray o el campo timeSeriesQuery. Si especificas una consulta, debe ser una consulta de estadísticas.

Por ejemplo, considera el siguiente objeto dashboardFilters:

{
  "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",
  ...
}

El JSON anterior define un filtro fijado y dos variables:

  • El filtro fijado tiene la clave de etiqueta de zone, que se muestra en la barra de herramientas. Los campos valueType y stringValue especifican el valor predeterminado único. Para obtener más información, consulta la página de referencia de la API para la estructura de datos dashboardFilters.

  • La variable basada en etiquetas tiene el nombre my_label_based_variable y su clave de etiqueta es instance_id. El valor predeterminado de esta variable se establece en un ID de instancia específico. También puedes configurar el valor predeterminado con un array. En la barra de herramientas, el filtro se muestra con el nombre my_label_based_variable.

  • La variable de solo valor se llama my_value_only_variable. Esta entrada no especifica un valor predeterminado, por lo que el operador comodín, (*), se aplica automáticamente. Además, esta variable usa una consulta en SQL para generar la lista de valores posibles para la variable.

Ten en cuenta que el objeto dashboardFilters no enumera los widgets a los que se aplica la variable. En su lugar, actualizas la consulta de un widget para que dependa de una variable.

Sintaxis general para desreferenciar una variable

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

  • Para aplicar una variable basada en etiquetas y hacer 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, usa ${my_value_only_variable}. Para las variables de solo 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 del panel de registros, actualiza el panel de consultas. La sintaxis de estos widgets sigue la que se especifica en Sintaxis general.

Console

Por ejemplo, en la siguiente consulta, se usa una expresión regular para comparar el valor del campo jsonPayload.message con un valor de cadena que incluye el valor de una variable basada en etiquetas:

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

Como otro ejemplo, considera una variable de solo valor, value_only_severity_variable, y supón que, en el menú de valores, se seleccionan tres valores: ERROR, INFO y NOTICE. A continuación, agrega lo siguiente al panel de consultas del widget del panel de registros:

severity =~ "${value_only_severity_variable}"

A continuación, se muestra el formulario renderizado:

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

REST

Por ejemplo, en el siguiente JSON, se ilustra cómo actualizar la consulta de un widget de panel de registros con una variable basada en etiquetas:

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

Por ejemplo, en la siguiente consulta, se usa una expresión regular para comparar el valor del campo jsonPayload.message con un valor de cadena que incluye el valor de una variable basada en etiquetas:

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

Como otro ejemplo, considera una variable de solo valor, value_only_severity_variable, y supón que se seleccionan tres valores en el menú: ERROR, INFO y NOTICE. A continuación, agrega lo siguiente al panel de consultas del widget del panel de registros:

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

A continuación, se ilustra la consulta tal como la ejecuta el widget del panel de registros:

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

Si configuraste una consulta para el panel de registros y, luego, 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 ilustra cómo el panel de registros resuelve las variables de ejemplo. Como se mencionó antes, cuando solo se usa el valor de una variable, debes usar una expresión regular como operador de comparación:

Sintaxis Valor
seleccionado		 Expresión del panel de registros resueltos
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

La variable de ejemplo se basa en la etiqueta de recurso instance_id.
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Gráficos con consultas de PromQL

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

Console

Por ejemplo, la siguiente consulta se basa en la variable basada en etiquetas, my_label_based_variable, que se resuelve en una expresión de filtro:

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

También puedes modificar la consulta para resolver solo el valor de una variable. En el siguiente ejemplo, se usa una expresión regular para comparar el valor de una consulta basada en etiquetas con instance_id:

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

Si tienes una variable de solo valor, omite la cláusula .value. Por ejemplo, para filtrar por zona con una variable de solo valor, la consulta incluiría algo como lo siguiente:

zone=~"${my_value_only_variable}"

REST

Por ejemplo, el siguiente JSON ilustra una consulta que se basa en la variable basada en etiquetas, my_label_based_variable, que se resuelve en una expresión de filtro:

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

También puedes modificar la consulta para resolver solo el valor de una variable. En el siguiente ejemplo, se usa una expresión regular para comparar el valor de una consulta basada en etiquetas con instance_id:

"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
},

Si tienes una variable de solo valor, omite la cláusula .value. Por ejemplo, para filtrar por zona con una variable de solo valor, la consulta incluiría algo como lo siguiente:

zone=~\"${my_value_only_variable}\"

En la siguiente tabla, se ilustra cómo PromQL resuelve las variables de ejemplo. Como se mencionó antes, cuando solo se usa el valor de una variable, debes usar una expresión regular como operador de comparación:

Sintaxis Valor
seleccionado		 Expresión de PromQL resuelta
${my_label_based_variable} 12345 instance_id == '12345'

La variable de ejemplo se basa en la etiqueta de recurso instance_id.
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

Gráficos con consultas en SQL

Hay dos lugares en los que puedes usar variables en tus consultas en SQL:

  • La cláusula FROM puede depender de la variable definida por el sistema llamada @__project_id, que se resuelve en el valor del proyecto seleccionado.

  • La cláusula WHERE puede depender de variables definidas por el usuario.

Actualiza la cláusula FROM para que dependa de una variable definida por el sistema

Si creas plantillas de panel y estas plantillas grafican los resultados de las consultas en SQL, reemplaza el ID del proyecto en tu consulta por la variable @__project_id. Cuando instalas la plantilla en un proyecto, la variable se resuelve automáticamente en el ID del proyecto. No es necesario que edites el widget de forma manual ni que actualices la cláusula FROM.

A continuación, se ilustra una cláusula FROM que depende de la variable definida por el sistema:

FROM `@__project_id.global._Default._Default`

La cláusula FROM no puede depender de variables definidas por el usuario.

Actualiza la cláusula WHERE para que dependa de una variable definida por el usuario

En esta sección, se describe cómo puedes actualizar la cláusula WHERE de un widget definido por SQL para que dependa de una variable definida por el usuario. Para todas las variables, antepón el signo de arroba al nombre de la variable, por ejemplo: @variable_name. Para las variables basadas en etiquetas, agrega .value al nombre de la variable, @my_label_based_variabe.value.

Para las consultas en SQL, la sustitución de variables se basa en BigQuery y es segura contra inyecciones de SQL. Para obtener más información, consulta Ejecuta consultas parametrizadas.

Console

Debido a que SQL no interpreta el operador de comodín como "cualquier valor", te recomendamos que siempre uses una declaración IF cuando uses variables en una consulta en SQL. En el siguiente ejemplo, se ilustra el uso de una variable de solo valor cuyo tipo de datos es una cadena:

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

Cuando la opción de menú de la variable permite que los usuarios seleccionen varios valores, debes convertir el valor de la variable en un tipo de datos de GoogleSQL con la función CAST. En la siguiente consulta, se ilustra esta sintaxis:

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

Se recomienda la sentencia IF que se muestra en los ejemplos anteriores, ya que SQL no interpreta el operador comodín como "cualquier valor". Por lo tanto, si omites la declaración IF y seleccionas el operador comodín, el resultado de la consulta será una tabla vacía. En el segundo ejemplo, la función UNNEST convierte el array en una tabla.

Para agregar una cláusula WHERE con el formato correcto, haz lo siguiente:

  1. Edita el widget.
  2. En la barra de herramientas, selecciona Insertar filtro de variable y, luego, la variable cuya cláusula WHERE quieras actualizar.
  3. En el cuadro de diálogo que se abre, revisa el código generado y, luego, haz clic en Copiar y cerrar.

  4. Pega el código copiado en el panel Consulta y realiza las modificaciones necesarias.

    Por ejemplo, supongamos que creas una variable llamada LogName que genera una lista de nombres de registros y genera el resultado en una tabla con una sola columna llamada log_name. A continuación, crea un gráfico, selecciona Insertar filtro de variable y, luego, selecciona la variable LogName. Se genera el siguiente código:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    En este ejemplo, debes editar el código generado y reemplazar LogName = por log_name = para que se pueda realizar la unión de tablas:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Haz clic en Ejecutar y, luego, en Aplicar.

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

REST

Debido a que SQL no interpreta el operador de comodín como "cualquier valor", te recomendamos que siempre uses una declaración IF cuando uses variables en una consulta en SQL. En el siguiente ejemplo, se ilustra el uso de una variable de solo valor cuyo tipo de datos es una cadena:

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

Por ejemplo, a continuación, se muestra una representación parcial en JSON de un gráfico que muestra los resultados de una consulta en SQL. Para admitir el filtrado de los resultados por el nombre de un registro, se agregó una cláusula WHERE que hace referencia a la variable llamada LogName:

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

La variable LogName también emite una consulta para determinar la lista de posibles nombres de registro:

"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
    }
  }
],

Cuando la opción de menú de la variable permite que los usuarios seleccionen varios valores, debes convertir el valor de la variable en un tipo de datos de GoogleSQL con la función CAST. En la siguiente consulta, se ilustra esta sintaxis:

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

Se recomienda la sentencia IF que se muestra en los ejemplos anteriores, ya que SQL no interpreta el operador comodín como "cualquier valor". Por lo tanto, si omites la declaración IF y seleccionas el operador comodín, el resultado de la consulta será una tabla vacía. En el segundo ejemplo, la función UNNEST convierte el array en una tabla.

Gráficos con consultas de filtro de Monitoring

Para actualizar un gráfico que tiene una consulta en forma de filtro de Monitoring para que dependa de una variable basada en etiquetas, sigue las instrucciones que se indican en Sintaxis general.

Console

Si usas la consola de Google Cloud para crear tus gráficos y la interfaz controlada por menús, puedes actualizar la consulta del gráfico con el campo Aplicar a gráficos de la variable o editando el widget y seleccionando la variable basada en etiquetas en el menú Filtro. En el menú Filtro, se enumeran todas las variables basadas en etiquetas y todas las claves de etiqueta.

Para actualizar la consulta de un gráfico de modo que dependa de una variable basada en valores, haz lo siguiente:

  1. Editar el gráfico
  2. En el panel de consultas, haz clic en Agregar filtro y selecciona una clave de etiqueta. Por ejemplo, puedes seleccionar zona.
  3. En el menú Valor, selecciona tu variable de solo valor.
  4. Haz clic en Aplicar.
  5. Para guardar el panel modificado, en la barra de herramientas, haz clic en Guardar.

Por ejemplo, el siguiente JSON ilustra una consulta que se basa en una variable basada en etiquetas, my_label_based_variable, que se resuelve en una expresión de filtro:

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

Los widgets que usan una consulta en forma de filtro de Monitoring no pueden filtrar la serie temporal por el valor de una variable basada en etiquetas. Sin embargo, puedes filtrar por variables de solo valor. Por ejemplo, en la siguiente consulta, se muestra el valor del campo Filtros de una consulta que filtra por zone, según el valor de una variable de solo valor:

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

REST

Por ejemplo, el siguiente JSON ilustra una consulta que se basa en una variable basada en etiquetas, my_label_based_variable, que se resuelve en una expresión de filtro:

"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
},

Los widgets que usan una consulta en forma de filtro de Monitoring no pueden filtrar la serie temporal por el valor de una variable basada en etiquetas. Sin embargo, puedes filtrar por variables de solo valor. Por ejemplo, en la siguiente consulta, se muestra el campo "filter" de una consulta que filtra por zone, según el valor de una variable de solo valor:

"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 ilustra cómo el filtro de Monitoring resuelve las variables de ejemplo. Como se mencionó antes, cuando solo se usa el valor de una variable, debes usar una expresión regular como operador de comparación:

Sintaxis Valor
seleccionado		 Expresión de filtro resuelta
${my_label_based_variable} 12345 resource.instance_id == "12345"

La variable de ejemplo se basa en la etiqueta de recurso instance_id.
${my_label_based_variable} * Omitido
${my_label_based_variable.value} 12345 No compatible
${my_label_based_variable.value} * No compatible
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Cómo modificar un filtro o una variable fijados

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

Si tu panel contiene una tabla que muestra datos de series temporales, puedes agregar filtros temporales o modificar filtros y variables permanentes con el botón Filtrar panel por este valor de una celda. Cuando se selecciona este botón, se aplica un filtro temporal nuevo o se actualiza el valor de un filtro o una variable existentes. Los filtros y las variables existentes 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 una variable, haz lo siguiente:

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
  3. En la barra de herramientas del panel, haz clic en Configuración.
  4. Busca el filtro o la variable que deseas modificar y expande su definición.
  5. Después de completar las modificaciones, haz clic en Aplicar.
  6. Para guardar el panel modificado, en la barra de herramientas, haz clic en Guardar.

Cómo borrar un filtro o una variable fijados

Para borrar un filtro fijado o una variable, haz lo siguiente:

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

    Acceder a Paneles

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
  3. En la barra de herramientas del panel, haz clic en Configuración.
  4. Busca el filtro o la variable que quieras quitar y, luego, haz clic en Borrar.
  5. Haz clic en Aplicar.
  6. Para guardar el panel modificado, en la barra de herramientas, haz clic en Guardar.

Limitaciones

  • Los filtros a nivel del panel se basan en el filtrado de datos por pares clave-valor. Estos filtros no se aplican cuando los datos no admiten pares clave-valor o cuando no admiten la clave específica. Por ejemplo, no puedes usar un filtro a nivel del panel para modificar los datos que muestra un widget de seguimiento.

  • Para aplicar una variable a un widget, debes modificar la consulta del widget. No todos los widgets admiten modificaciones.

¿Qué sigue?