Crea y administra paneles con la API

En este documento, se describe cómo puedes crear y administrar paneles personalizados y los widgets en esos paneles con el recurso Dashboard en la API de Cloud Monitoring. En los ejemplos que se incluyen aquí, se muestra cómo administrar tus paneles con curl para invocar la API y cómo usar Google Cloud CLI. Si bien también puedes administrar tus paneles personalizados a través de la consola de Google Cloud, la API te ofrece una forma programática de administrar muchos paneles al mismo tiempo.

El extremo admite los siguientes métodos para administrar y configurar paneles:

• dashboards.create: Crea un panel.
• dashboards.delete: borra un panel especificado
• dashboards.list: recupera una lista de todos los paneles de un proyecto determinado
• dashboards.get: recupera un panel especificado
• dashboards.patch: actualiza la estructura de un panel especificado

Puedes invocar la API de forma directa mediante la utilidad curl o Google Cloud CLI.

No puedes recuperar, editar ni borrar paneles predefinidos.

Esta función solo es compatible con los proyectos de Google Cloud.

Acerca de los paneles

Cuando creas un panel, debes especificar qué componentes o widgets deseas que se muestren y el diseño de esos widgets. También puedes agregar etiquetas y filtros a tu panel. Las etiquetas pueden ayudarte a encontrar un panel o indicar el tipo de contenido que contiene.

Diseños del panel

Los diseños definen cómo se ordenan los componentes de un panel. La API proporciona los siguientes diseños:

• GridLayout: divide el espacio disponible en columnas verticales de igual ancho y organiza un conjunto de widgets con una estrategia de filas.

• MosaicLayout: Divide el espacio disponible en una cuadrícula. Cada widget puede ocupar uno o más bloques de cuadrícula.

• RowLayout: divide el espacio disponible en filas y organiza un conjunto de widgets horizontalmente en cada fila.

• ColumnLayout: divide el espacio disponible en columnas verticales y organiza un conjunto de widgets verticalmente en cada columna.

Por ejemplo, a continuación se muestra la representación JSON de un panel en RowLayout con tres widgets Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widgets del panel

Un widget contiene un único componente de panel y la configuración de cómo presentar el componente en él. Un panel puede tener más de un widget. Existen varios tipos de objetos Widget:

• El widget XyChart muestra los datos en los ejes X e Y.

  Este widget muestra un conjunto de datos que puede ser de series temporales o generado por una consulta de SQL. Este widget te permite asociar los datos del gráfico con el eje Y izquierdo o derecho. Cuando se grafican varios tipos de métricas, puedes usar ambos ejes Y. El widget XyChart admite los siguientes estilos de visualización:

  • Gráficos de líneas
  • Gráficos de barras
  • Gráficos de áreas apiladas
  • Mapas de calor

• Widgets que se muestran a partir de una dimensión, como el valor más reciente:

  • PieChart: Muestra los valores más recientes de una colección de series temporales, en las que cada serie temporal aporta una porción al gráfico de tarta.

  • Scorecard: Muestra el valor más reciente de una serie temporal y cómo se relaciona este valor con uno o más umbrales.

  • TimeSeriesTable: Muestra el valor más reciente o un valor agregado para cada serie temporal. Las tablas admiten la personalización. Por ejemplo, puedes asignar códigos de color a las celdas y configurar los nombres de las columnas y la alineación de los datos.

• Widgets que muestran información de la política de alertas o de incidentes:

  • AlertChart: Muestra un resumen de una política de alertas de una sola condición. Este widget muestra los datos como un gráfico de líneas, el umbral y la cantidad de incidentes abiertos.

  • IncidentList: Muestra una lista de incidentes. Puedes configurar el widget para que muestre incidentes de políticas de alertas específicas o de tipos de recursos específicos.

• Widgets que muestran entradas de registro y errores:

  • ErrorReportingPanel: Muestra los grupos de errores almacenados en el proyecto de Google Cloud seleccionado.

  • LogsPanel: Muestra las entradas de registro centradas en el proyecto que se almacenan en el proyecto de Google Cloud actual. Puedes configurar el widget para que muestre las entradas de registro almacenadas en proyectos de Google Cloud a los que se puede acceder a través del permiso de métricas actual.

• Widgets de texto y organización:

  • CollapsibleGroup: Muestra una colección de widgets. Puedes contraer la vista de un grupo.

  • SingleViewGroup: Muestra un widget en una colección de widgets. Puedes seleccionar qué widget mostrar.

  • SectionHeader: Crea un divisor horizontal en el panel y una entrada en la tabla de contenido del panel.

  • Text: muestra el contenido textual, ya sea como texto sin formato o como string de Markdown.

  Para incluir los widgets de texto y organización en un panel, este debe tener un MosaicLayout.

Además de estos objetos, también puedes agregar un marcador de posición en blanco a un panel.

Por ejemplo, a continuación se muestra la representación JSON de un widget XyChart cuyo eje Y derecho está configurado:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Etiquetas del panel

Las etiquetas pueden ayudarte a administrar y organizar tus paneles. Por ejemplo, puedes agregar una etiqueta llamada prod para indicar que el panel muestra datos de series temporales y datos de registro de tus recursos de producción. Como alternativa, puedes agregar la etiqueta playbook para indicar que el panel contiene información que te ayudará a solucionar fallas.

Agregar etiquetas a un panel es opcional.

Por ejemplo, a continuación, se muestra un objeto Dashboard que especifica la etiqueta llamada playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Como se ilustra en el ejemplo anterior, el campo labels se implementa como un map, en el que los campos key y value son cadenas. Cuando agregues una etiqueta a un panel, establece key en el nombre de la etiqueta y establece el campo value en una cadena vacía.

Nota: En los objetos Dashboard.labels, solo se procesan los campos key. Se ignoran los campos value.

Filtros y variables del panel

Cuando diseñas un panel, puedes identificar varias formas de ver los datos que muestra. Por ejemplo, supongamos que un panel muestra datos de series temporales para tus instancias de máquina virtual (VM). Es posible que desees ver los datos de series temporales de todas las VMs o solo los datos que se encuentran en una zona específica. En esta situación, te recomendamos que crees un filtro fijado o una variable y, luego, establezcas el valor predeterminado de ese filtro en la zona que se ve con más frecuencia.

Los filtros fijados se aplican a todos los widgets del panel que admiten la etiqueta especificada en el filtro, a menos que el widget contenga un filtro con esa misma clave de etiqueta. Por ejemplo, cuando un gráfico incluye el filtro zone = us-central1-a, ese gráfico ignora un filtro fijado cuya clave de etiqueta es zone. Del mismo modo, los gráficos que no tienen una etiqueta con una clave de zone ignoran este filtro.

Las variables son como los filtros fijados, pero solo se aplican a widgets específicos. Las variables pueden basarse en etiquetas, como los filtros fijados, o pueden tener solo un valor. Las variables de solo valor contienen uno o más valores predeterminados y una lista de todos los valores posibles. Si no especificas un valor predeterminado, el valor predeterminado se establece en el operador de comodín (*). Para definir el conjunto de todos los valores posibles, proporciona un array de valores o escribe una consulta de SQL.

En el caso de los widgets que consultan datos, puedes incluir una variable en la consulta del widget y usarla para controlar la visibilidad del widget. Cuando la consulta depende de una variable, los datos que solicita el widget cambian cuando cambias el valor de la variable. Como resultado, los datos que se muestran también cambian. Cuando usas una variable para controlar la visibilidad de un widget, se muestra un ícono Visible en la barra de herramientas. Para conocer las restricciones relacionadas con la visibilidad, consulta Cómo configurar la visibilidad de un widget.

En el caso de los filtros y las variables fijados, la barra de herramientas del panel muestra cada variable, junto con un menú que te permite cambiar temporalmente el valor de la variable. Se usa la misma estructura de datos para representar los filtros y las variables fijados. Para ayudarte a diferenciar los filtros de las variables, en la barra de herramientas del panel, el nombre de una variable se antepone con un signo de dólar $. Para obtener más información, consulta DashboardFilter.

Para ver un ejemplo que muestra cómo puedes controlar la visibilidad de un widget con una variable, consulta Panel con visibilidad de widgets configurada.

Para obtener información sobre 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 anular la referencia de una variable
• Widgets del panel de registros
• Gráficos con consultas de PromQL
• Gráficos con consultas SQL
• Gráficos con consultas de MQL

• Gráficos con consultas de filtros de supervisión

  Cuando usas la interfaz basada en menús para crear un gráfico que muestre datos de series temporales, tus selecciones se convierten en un filtro de Monitoring.

Crea filtros y variables

Console

Si deseas obtener información para usar la consola de Google Cloud y crear variables y filtros fijados, consulta los siguientes documentos:

• Cómo crear y fijar un filtro
• Cómo crear una variable

API

Para definir los filtros y las 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 desees 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 a seleccionar 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 el campo stringArrayValue. En el siguiente ejemplo, hay tres valores predeterminados.

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

  Nota: Si no especificas un valor predeterminado, el operador comodín, (*), se selecciona automáticamente. Si planeas usar la variable en un panel de registros, debes usar la expresión regular como comparador. Para las consultas de SQL, debes usar una sentencia IF. Para obtener más información, consulta Gráficos con consultas de SQL.

• Opcional: Para especificar la lista de todos los valores posibles de una variable solo de valor, establece el campo stringArray o el campo timeSeriesQuery. Si especificas una consulta, esta debe ser una consulta de análisis.

  Nota: No configures los campos timeSeriesQuery ni stringArray cuando creas un filtro fijado o una variable basada en etiquetas. El conjunto de todos los valores posibles se determina de forma dinámica.

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 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 referencias de la API de la estructura de datos de 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 SQL para generar la lista de valores posibles para la variable.

Ten en cuenta que el objeto dashboardFilters no muestra 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 anular la referencia de una variable

Para todos los widgets, excepto los que define 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, 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 especificada en Sintaxis general.

Console

Por ejemplo, la siguiente consulta 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 solo de valor, value_only_severity_variable, y supongamos que, en el menú de valores, se seleccionan tres valores: ERROR, INFO y NOTICE. A continuación, agrega lo siguiente al panel de consulta del widget del panel de registros:

severity =~ "${value_only_severity_variable}"

A continuación, se muestra el formulario renderizado:

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

API

Por ejemplo, el siguiente JSON 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, la siguiente consulta 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 solo de valor, value_only_severity_variable, y supongamos que se seleccionaron tres valores en el menú: ERROR, INFO y NOTICE. A continuación, agrega lo siguiente al panel de consulta del widget del panel de registros:

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

A continuación, se ilustra la consulta que 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 muestra cómo el panel de registros resuelve las variables de ejemplo. Como se mencionó anteriormente, 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 resuelta del panel de registros
${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 búsqueda 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}"

API

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 búsqueda 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 muestra cómo PromQL resuelve las variables de ejemplo. Como se mencionó anteriormente, 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 de SQL

Cuando quieras actualizar un widget definido en SQL para que dependa de una variable, actualiza la cláusula WHERE para hacer referencia al valor de la variable. Para todas las variables, agrega el signo "acento grave" al principio del 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.

En el caso de las consultas de SQL, la sustitución de variables se basa en BigQuery y es segura contra la inyección de SQL. Para obtener más información, consulta Ejecuta consultas con parámetros.

Console

Debido a que SQL no interpreta el operador comodín como “cualquier valor”, te recomendamos que siempre uses una sentencia IF cuando uses variables en una consulta de SQL. En el siguiente ejemplo, se ilustra el uso de una variable solo de 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 transmitir el valor de la variable a 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 porque SQL no interpreta el operador comodín como “cualquier valor”. Por lo tanto, si omites la sentencia IF y seleccionas el operador comodín, el resultado de la consulta es 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, selecciona la variable cuya cláusula WHERE deseas actualizar.
3. En el 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 muestra el resultado en una tabla con una sola columna llamada log_name. A continuación, creas un gráfico, seleccionas Insertar filtro de variables y, luego, seleccionas 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 Run y, luego, en Apply.

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

API

Debido a que SQL no interpreta el operador comodín como “cualquier valor”, te recomendamos que siempre uses una sentencia IF cuando uses variables en una consulta de SQL. En el siguiente ejemplo, se ilustra el uso de una variable solo de 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 JSON parcial de un gráfico que muestra los resultados de una consulta de 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 transmitir el valor de la variable a 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 porque SQL no interpreta el operador comodín como “cualquier valor”. Por lo tanto, si omites la sentencia IF y seleccionas el operador comodín, el resultado de la consulta es una tabla vacía. En el segundo ejemplo, la función UNNEST convierte el array en una tabla.

Gráficos con consultas de MQL

Para un gráfico que tiene una consulta de MQL para usar una variable basada en etiquetas, agrega una barra, (|), y, luego, sigue las instrucciones que se indican en Sintaxis general.

Cuando usas la interfaz basada en menús para crear un gráfico que muestre datos de series temporales, tus selecciones se convierten en un filtro de Monitoring.

Console

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${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 búsqueda basada en etiquetas con instance_id:

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

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:

resource.zone=~'${my_value_only_variable}'

API

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": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "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 búsqueda basada en etiquetas con instance_id:

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "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:

resource.zone=~'${my_value_only_variable}'

En la siguiente tabla, se muestra cómo la MQL resuelve las variables de ejemplo. Como se mencionó anteriormente, 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 MQL resuelta
${my_label_based_variable}	12345	filter (resource.instance_id == '12345') La variable de ejemplo se basa en la etiqueta de recurso instance_id.
${my_label_based_variable}	*	filter (true)
${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 filtros de supervisión

Para actualizar un gráfico que tiene una consulta en forma de filtro de supervisión 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 basada en 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ú Filtrar. En el menú Filtro, se enumeran todas las variables basadas en etiquetas y todas las claves de etiquetas.

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

1. Editar el gráfico
2. En el panel de consulta, 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, haz clic en Guardar en la barra de herramientas.

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 supervisión no pueden filtrar las series temporales por el valor de una variable basada en etiquetas. Sin embargo, puedes filtrar por variables de solo valor. Por ejemplo, la siguiente consulta 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})

API

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 supervisión no pueden filtrar las series temporales por el valor de una variable basada en etiquetas. Sin embargo, puedes filtrar por variables de solo valor. Por ejemplo, la siguiente consulta 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 muestra cómo el filtro de supervisión resuelve las variables de ejemplo. Como se mencionó anteriormente, 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}	*	".*"

Antes de comenzar

Completa lo siguiente en el proyecto de Google Cloud en el que deseas crear o administrar paneles:

• Select the tab for how you plan to use the samples on this page:

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Terraform

  Para usar las muestras de Terraform de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .

  REST

  Para usar las muestras de la API de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a la CLI de gcloud.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Para obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud .

Crear un panel

Para crear un panel nuevo personalizado, invoca el método dashboards.create y proporciónale el diseño y los widgets que se mostrarán en él.

El campo name es opcional. El valor del campo de nombre tiene la siguiente estructura:

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

Cuando creas un panel, la API genera automáticamente el componente DASHBOARD_ID. Si deseas especificar un DASHBOARD_ID personalizado, puedes especificar el campo name del objeto Dashboard.

Nota: El valor del campo name debe ser único a nivel global, ya que este campo sirve como nombre único para un panel. Si especificas este campo en un archivo YAML o JSON que usas para crear paneles, asegúrate de usar un valor único para DASHBOARD_ID en cada ejecución. Si intentas crear un panel en el mismo proyecto y el ID que especificas está en uso, se producirá un error. Para obtener más información, consulta El panel no se crea. El nombre visible no tiene que ser único.

gcloud

Para crear un panel en un proyecto, usa el comando gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json --project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.

Por ejemplo, si quieres duplicar un panel, haz lo siguiente:

1. Completa los pasos que se indican en Obtener panel para descargar la definición del panel original.
2. Edita el JSON que se muestra para quitar los campos etag y name, y cambia el valor del campo displayName.
3. Ejecuta el comando para crear el panel.

Para obtener más información, consulta la referencia gcloud monitoring dashboards create.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor de Terraform.

Nota: Si creas un panel con Terraform, puedes verlo con la consola de Google Cloud. Sin embargo, no edites el panel en la consola de Google Cloud. La edición hace que se vuelva a escalar el panel. Para obtener más información, consulta Soluciona problemas: Se vuelve a escalar el panel creado con Terraform.

Para crear un panel con Terraform, haz lo siguiente:

1. Instala y configura Terraform para tu proyecto.

2. Usa el recurso google_monitoring_dashboard de Terraform.

   En el comando, establece los siguientes campos:

   • dashboard_json: Es la representación JSON del panel, que usa el formato Dashboards.

     Para ver ejemplos de este formato, puedes enumerar tus paneles con el Explorador de APIs o abrir un panel en la consola de Google Cloud y ver las representaciones JSON.

   • parent: Es el nombre completamente calificado de tu proyecto. Por ejemplo, puedes establecer este campo en "projects/PROJECT_ID", en el que PROJECT_ID es el ID de tu proyecto de Google Cloud.

REST

Para crear un panel nuevo, envía una solicitud POST al extremo Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.

En los ejemplos, se crea un panel de muestra con el archivo my-dashboard.json. Puedes administrar tu panel a través de la consola de Google Cloud.

Para ver configuraciones adicionales del panel, consulta Paneles y diseños de ejemplo.

Cómo borrar paneles

Para borrar un panel personalizado, invoca el método dashboards.delete y especifica el panel que deseas borrar.

gcloud

Para borrar un panel personalizado, usa gcloud monitoring dashboards delete y especifica el ID completo del panel que deseas borrar:

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.
• DASHBOARD_ID: Es el ID del panel.

Para obtener más información, consulta la referencia gcloud monitoring dashboards delete.

Terraform

Puedes borrar recursos con Terraform. Para obtener información sobre cómo borrar recursos, consulta el comando destroy de Terraform.

REST

Para borrar un panel personalizado, envía una solicitud DELETE al extremo Dashboard, calificado con el ID del panel que se borrará.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.
• ${DASHBOARD_ID}: Es una variable de entorno que almacena el ID del panel.

Si se completa correctamente, el método muestra una respuesta vacía. De lo contrario, muestra un error.

Mostrar paneles

Para enumerar todos los paneles personalizados que pertenecen a un proyecto, invoca el método dashboards.list y especifica el ID del proyecto.

gcloud

Para enumerar todos los paneles personalizados de un proyecto, usa el comando gcloud monitoring dashboards list:

gcloud monitoring dashboards list --project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.

Para obtener más información, consulta la referencia de gcloud monitoring dashboards list.

Terraform

No puedes usar Terraform para enviar una consulta a tu proyecto con la respuesta de una lista de paneles. Sin embargo, puedes ver estos paneles con la consola de Google Cloud.

REST

Para enumerar todos los paneles personalizados de un proyecto, envía el ID del proyecto al extremo Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.

En los ejemplos, se muestran los paneles asociados con tu proyecto.

Pagina la respuesta de la lista

El método dashboards.list admite la paginación, lo que te permite tomar los resultados de una página a la vez en lugar de todos juntos.

gcloud

Para especificar la cantidad de recursos por página, pasa la marca --page-size con el comando. Por ejemplo:

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.

Terraform

No puedes usar Terraform para enviar una consulta a tu proyecto con la respuesta de una lista paginada de paneles. Sin embargo, puedes ver estos paneles con la consola de Google Cloud.

REST

Para la página inicial de la lista de resultados, especifica el parámetro de búsqueda pageSize con solicitud:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.

El método muestra la primera página de la lista y nextPageToken. Por ejemplo:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Para cada página restante, debes incluir el nextPageToken correspondiente en la solicitud.

Cómo obtener el panel

Para obtener un panel personalizado específico de un proyecto, invoca el método dashboards.get calificado con el ID del panel.

gcloud

Para obtener un panel personalizado específico, usa el comando gcloud monitoring dashboards describe y especifica el ID del panel:

gcloud monitoring dashboards describe DASHBOARD_ID --format=json -project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.
• DASHBOARD_ID: Es el ID del panel.

El comando muestra el panel solicitado:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Para obtener más información, consulta la referencia de gcloud monitoring dashboards describe.

Terraform

No puedes usar Terraform para enviar una consulta a tu proyecto con la respuesta como un panel individual. Sin embargo, puedes ver estos paneles con la consola de Google Cloud.

REST

Para obtener un panel personalizado específico, envía el ID del panel al extremo Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.
• ${DASHBOARD_ID}: Es una variable de entorno que almacena el ID del panel.

En la expresión anterior, ${DASHBOARD_ID} es una variable de entorno que almacena el nombre completamente calificado del panel.

El método muestra una respuesta similar a la del siguiente ejemplo:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Actualizar panel

Para actualizar un panel personalizado existente, invoca el método dashboards.patch. Para obtener el valor etag actual, puedes invocar el método dashboards.get y encontrarlo en la respuesta.

gcloud

Para actualizar un panel personalizado, usa gcloud monitoring dashboards update, especifica el ID del panel que se actualizará y proporciona los cambios en el panel.

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

Antes de ejecutar el comando anterior, reemplaza lo siguiente:

• PROJECT_ID: Es el identificador del proyecto.
• DASHBOARD_ID: Es el ID del panel.

Para obtener más información, consulta la referencia de gcloud monitoring dashboards update.

En el ejemplo anterior, se actualiza un panel personalizado existente con el archivo my-updated-dashboard.json. La respuesta, que incluye un valor etag nuevo, es una copia de la ficha del panel actualizada.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor de Terraform.

Para actualizar un panel con Terraform, haz lo siguiente:

1. Instala y configura Terraform para tu proyecto.

2. Usa el recurso google_monitoring_dashboard de Terraform.

   En el comando, establece los siguientes campos:

   • dashboard_json: Es la representación JSON del panel, que usa el formato Dashboards.

   • parent: Es el nombre completamente calificado de tu proyecto. Por ejemplo, puedes establecer este campo en "projects/PROJECT_ID", en el que PROJECT_ID es el ID de tu proyecto de Google Cloud.

REST

Para actualizar un panel personalizado, envía una solicitud PATCH al extremo Dashboard y proporciona el objeto Dashboard revisado y el valor etag de la respuesta dashboards.get más reciente.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Antes de ejecutar el comando anterior, configura lo siguiente:

• ${PROJECT_ID}: Es una variable de entorno que almacena el ID del proyecto en el que se creará el panel.
• ${DASHBOARD_ID}: Es una variable de entorno que almacena el ID del panel.

En el ejemplo anterior, se actualiza un panel personalizado existente con el archivo my-updated-dashboard.json. La respuesta, que incluye un valor etag nuevo, es una copia de la ficha del panel actualizada.

¿Qué sigue?

• Ejemplos de paneles y diseños
• Crea y administra paneles personalizados con la consola de Google Cloud