Crear y gestionar paneles de control mediante APIs

En este documento se describe cómo puedes crear y gestionar paneles de control personalizados y los widgets de esos paneles mediante el recurso Dashboard de la API Cloud Monitoring. En los ejemplos de este artículo se muestra cómo gestionar los paneles de control mediante curl para invocar la API y cómo usar la CLI de Google Cloud. Aunque también puedes gestionar tus paneles de control personalizados a través de la consola, la API te ofrece una forma programática de gestionar muchos paneles de control al mismo tiempo.Google Cloud

El endpoint admite los siguientes métodos para gestionar y configurar los paneles de control:

Puedes invocar la API directamente con la utilidad curl o con la CLI de Google Cloud.

No puedes recuperar, editar ni eliminar paneles de control predefinidos.

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 paneles de control

Al crear un panel de control, debe especificar los componentes o widgets que quiere mostrar y el diseño de esos widgets. También puedes añadir etiquetas y filtros a tu panel de control. Las etiquetas pueden ayudarte a encontrar un panel de control o indicar el tipo de contenido que incluye.

Diseños de panel de control

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

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

  • MosaicLayout: divide el espacio disponible en una cuadrícula. Cada widget puede ocupar uno o varios bloques de la cuadrícula.

  • RowLayout: divide el espacio disponible en filas y coloca 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 de control 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 de control

Un widget contiene un solo componente de panel de control y la configuración de cómo presentar el componente en el panel. Un panel de control puede tener más de un widget. Hay varios tipos de objetos Widget:

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

    Este widget muestra un conjunto de datos que puede ser una serie temporal o que se puede generar mediante una consulta SQL. Este widget te permite asociar los datos representados en el gráfico con el eje Y izquierdo o el derecho. Cuando se representan varios tipos de métricas en un gráfico, 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 muestran datos de una dimensión, como el valor más reciente:

    • PieChart: muestra los valores más recientes de una colección de series temporales, donde cada serie temporal aporta una porción al gráfico circular.

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

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

  • Widgets que muestran información sobre políticas de alertas o incidentes:

    • AlertChart: muestra un resumen de una política de alertas de una sola condición. Este widget muestra los datos en un gráfico de líneas, indica el umbral y muestra el número de incidencias abiertas.

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

  • Widgets que muestran entradas de registro y errores:

  • Widgets de texto y organización:

    • CollapsibleGroup: muestra una colección de widgets. Puedes ocultar la vista de un grupo.

    • SingleViewGroup: muestra un widget en una colección de widgets. Puedes seleccionar el widget que quieras mostrar.

    • SectionHeader: crea un separador horizontal en tu panel de control y una entrada en la tabla de contenido del panel.

    • Text: muestra contenido de texto, ya sea como texto sin formato o como una cadena de Markdown.

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

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

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 de control

Las etiquetas pueden ayudarte a gestionar y organizar tus paneles de control. Por ejemplo, puedes añadir una etiqueta llamada prod para indicar que el panel de control muestra datos de serie temporal y datos de registro de tus recursos de producción. También puedes añadir la etiqueta playbook para indicar que el panel de control contiene información que te ayudará a solucionar los fallos.

Añadir etiquetas a un panel de control 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 muestra en el ejemplo anterior, el campo labels se implementa como map, donde los campos key y value son cadenas. Cuando añadas una etiqueta a un panel de control, asigna el valor key al nombre de la etiqueta y el valor value a una cadena vacía.

Filtros y variables del panel de control

Cuando diseñas un panel de control, puedes identificar varias formas de ver los datos que muestra. Por ejemplo, supongamos que un panel de control muestra datos de series temporales de tus instancias de máquina virtual (VM). Puede que quieras ver los datos de series temporales de todas las máquinas virtuales o solo los datos de una zona específica. En esta situación, te recomendamos que crees un filtro fijado o una variable y, a continuación, asignes a ese filtro el valor predeterminado de la zona más vista.

Los filtros fijados se aplican a todos los widgets del panel de control que admitan la etiqueta especificada en el filtro, a menos que el widget contenga un filtro con la misma clave de etiqueta. Por ejemplo, si 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, este filtro se ignora en los gráficos que no tienen una etiqueta con la clave zone.

Las variables son como 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 varios valores predeterminados y una lista de todos los valores posibles. Si no especifica ningún valor predeterminado, se asigna el operador comodín (*). Para definir el conjunto de todos los valores posibles, puedes proporcionar una matriz de valores o escribir una consulta SQL.

En los widgets que consultan datos, puede incluir una variable en la consulta del widget y usar una variable para controlar la visibilidad del widget. Cuando la consulta depende de una variable, los datos que solicita el widget cambian al modificar el valor de la variable. Por lo tanto, los datos que se muestran también cambian. Cuando usas una variable para controlar la visibilidad de un widget, se muestra el icono Visible en la barra de herramientas. Para ver las restricciones relacionadas con la visibilidad, consulta Configurar la visibilidad de un widget.

En el caso de los filtros y las variables fijados, la barra de herramientas del panel de control muestra cada variable junto con un menú que le 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 de control, el nombre de una variable va precedido de un signo de dólar $. Para obtener más información, consulta DashboardFilter.

Para ver un ejemplo de cómo controlar la visibilidad de un widget mediante una variable, consulta Panel de control con la visibilidad de los widgets configurada.

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:

Crear filtros y variables

Consola

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

API

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

  • Para crear una variable, asigna al campo templateVariable el nombre de la variable. Omite este campo o asigna el valor de una cadena vacía cuando quieras crear un filtro fijado.
  • Para crear un filtro fijado o una variable basada en etiquetas, debe especificar el campo labelKey. Omite este campo si quieres una variable que solo tenga un valor.

  • Define el valor predeterminado del 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 definir un único valor predeterminado y restringir a los usuarios a seleccionar exactamente una opción en el menú de valores, define el campo valueType como STRING y también el campo stringValue:
    "valueType": "STRING",
"stringValue": "my-default-value",
    • Para definir al menos un valor predeterminado y permitir que los usuarios seleccionen varias opciones en el menú de valores, define el campo valueType como STRING_ARRAY y también define 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, defina el campo stringArray o el campo timeSeriesQuery. Si especifica una consulta, debe ser una consulta de analíticas.

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 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 es un ID de instancia específico. También puedes configurar el valor predeterminado mediante una matriz. 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 ningún valor predeterminado, por lo que se aplica automáticamente el operador comodín (*). Además, esta variable usa una consulta de SQL para generar la lista de valores posibles de la variable.

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

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.

Consola

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

Por ejemplo, supongamos que tenemos una variable que solo tiene valores, value_only_severity_variable, y que en el menú de valores se han seleccionado tres: ERROR, INFO y NOTICE. A continuación, añade lo siguiente al panel de consulta del widget de 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 muestra 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"
  ]
}

Por ejemplo, supongamos que tenemos una variable que solo tiene valores, value_only_severity_variable, y que se han seleccionado tres valores en el menú: ERROR, INFO y NOTICE. A continuación, añade lo siguiente al panel de consulta del widget de panel de registros:

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

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

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:

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

La variable de ejemplo se basa en la etiqueta del 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 tenga una consulta de PromQL para que dependa de una variable basada en etiquetas, sigue las directrices que se indican en Sintaxis general.

Consola

Por ejemplo, la siguiente consulta se basa en la variable 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 tiene una variable de solo valor, omita la cláusula .value. Por ejemplo, para filtrar por zona usando una variable de solo valor, la consulta incluiría algo parecido a lo siguiente:

zone=~"${my_value_only_variable}"

API

Por ejemplo, el siguiente JSON muestra una consulta que se basa en la variable 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 tiene una variable de solo valor, omita la cláusula .value. Por ejemplo, para filtrar por zona usando una variable de solo valor, la consulta incluiría algo parecido a lo siguiente:

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:

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

La variable de ejemplo se basa en la etiqueta del 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

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.

Consola

Como SQL no interpreta el operador comodín como "cualquier valor", te recomendamos que siempre uses una instrucción IF cuando uses variables en una consulta SQL. En el siguiente ejemplo se muestra el uso de una variable que solo tiene un valor y 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 a los usuarios seleccionar varios valores, debes convertir el valor de la variable a un tipo de datos de GoogleSQL mediante la función CAST. La siguiente consulta ilustra esta sintaxis:

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

Se recomienda usar la instrucción IF que se muestra en los ejemplos anteriores porque SQL no interpreta el operador comodín como "cualquier valor". Por lo tanto, si omite la instrucción IF y selecciona el operador comodín, el resultado de la consulta será una tabla vacía. En el segundo ejemplo, la función UNNEST convierte la matriz en una tabla.

Para añadir una cláusula WHERE con el formato adecuado, siga estos pasos:

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

  4. Pega el código copiado en el panel Consulta y haz los cambios necesarios.

    Por ejemplo, supongamos que crea 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, crea un gráfico, selecciona Insertar filtro de variable y, después, la variable LogName. Se genera el siguiente código:

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

    En este ejemplo, debe editar el código generado y sustituir LogName = por log_name = para que se pueda unir la tabla:

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

  5. Haga clic en Ejecutar y, a continuación, en Aplicar.

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

API

Como SQL no interpreta el operador comodín como "cualquier valor", te recomendamos que siempre uses una instrucción IF cuando uses variables en una consulta SQL. En el siguiente ejemplo se muestra el uso de una variable que solo tiene un valor y 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 SQL. Para permitir que los resultados se filtren por el nombre de un registro, se ha añadido una cláusula WHERE que hace referencia a la variable 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 envía una consulta para determinar la lista de nombres de registro posibles:

"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 a los usuarios seleccionar varios valores, debes convertir el valor de la variable a un tipo de datos de GoogleSQL mediante la función CAST. La siguiente consulta ilustra esta sintaxis:

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

Se recomienda usar la instrucción IF que se muestra en los ejemplos anteriores porque SQL no interpreta el operador comodín como "cualquier valor". Por lo tanto, si omite la instrucción IF y selecciona el operador comodín, el resultado de la consulta será una tabla vacía. En el segundo ejemplo, la función UNNEST convierte la matriz en una tabla.

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.

Consola

Si usas la Google Cloud consola para crear tus gráficos y la interfaz basada en menús, puedes actualizar la consulta del gráfico mediante 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ú Filtrar se muestran todas las variables basadas en etiquetas y todas las claves de etiqueta.

Para actualizar la consulta de un gráfico de forma que dependa de una variable basada en valores, sigue estos pasos:

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

Por ejemplo, el siguiente JSON muestra 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 las series temporales por el valor de una variable basada en etiquetas, pero sí pueden filtrar por variables que solo tengan valores. Por ejemplo, la siguiente consulta muestra el valor del campo Filters de una consulta que filtra por zone, en función del 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 muestra 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 las series temporales por el valor de una variable basada en etiquetas, pero sí pueden filtrar por variables que solo tengan valores. Por ejemplo, la siguiente consulta muestra el campo "filter" de una consulta que filtra por zone en función del 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 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:

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 del 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 empezar

En el Google Cloud proyecto en el que quieras crear o gestionar paneles de control, haz lo siguiente:

  • 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 la CLI de gcloud y, a continuación, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

      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.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación Google Cloud .

    REST

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

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

Crear un panel de control

Para crear un panel de control personalizado, invoca el método dashboards.create y proporciónale el diseño y los widgets que quieras que se muestren en el panel.

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 de control, la API genera automáticamente el componente DASHBOARD_ID. Si quieres especificar un DASHBOARD_ID personalizado, puedes indicar el campo name del objeto Dashboard.

gcloud

Para crear un panel de control 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, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.

Por ejemplo, si quiere duplicar un panel de control, siga estos pasos:

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

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

Terraform

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor Terraform.

.

Para crear un panel de control con Terraform, sigue estos pasos:

  1. Instala y configura Terraform para tu 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.

  2. Usa el recurso de Terraform google_monitoring_dashboard.

    En el comando, define los siguientes campos:

    • dashboard_json: representación JSON del panel de control con el formato Dashboards.

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

    • parent: el nombre completo de tu proyecto. Por ejemplo, puedes asignar a este campo el valor "projects/PROJECT_ID", donde PROJECT_ID es el ID de tu proyecto 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.

REST

Para crear un panel de control, envía una solicitud POST al endpoint 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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.

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

Para ver más configuraciones de paneles, consulta Ejemplos de paneles y diseños.

Eliminar paneles de control

Para eliminar un panel de control personalizado, invoca el método dashboards.delete y especifica el panel de control que quieras eliminar.

gcloud

Para eliminar un panel de control personalizado, usa gcloud monitoring dashboards delete y especifica el ID completo del panel de control que quieras eliminar:

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

Antes de ejecutar el comando anterior, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.
  • DASHBOARD_ID: ID del panel de control.

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

Terraform

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

REST

Para eliminar un panel de control personalizado, envía una solicitud DELETE al endpoint Dashboard, que debe incluir el ID del panel de control que quieras eliminar.

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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.
  • ${DASHBOARD_ID}: variable de entorno que almacena el ID del panel de control.

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

Mostrar paneles

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

gcloud

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

gcloud monitoring dashboards list --project=PROJECT_ID

Antes de ejecutar el comando anterior, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.

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 y obtener como respuesta una lista de paneles de control. Sin embargo, puedes ver estos paneles de control mediante la Google Cloud consola.

REST

Para enumerar todos los paneles de control personalizados de un proyecto, envía el ID del proyecto al endpoint 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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.

Los ejemplos devuelven los paneles de control personalizados asociados a tu proyecto.

Paginación de la respuesta de la lista

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

gcloud

Para especificar el número de recursos por página, añade la marca --page-size al comando. Por ejemplo:

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

Antes de ejecutar el comando anterior, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.

Terraform

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

REST

Para la página inicial de la lista de resultados, especifica el parámetro de consulta pageSize con la 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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.

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

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

En cada página restante, debe incluir el nextPageToken correspondiente en la solicitud.

Obtener panel de control

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

gcloud

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

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

Antes de ejecutar el comando anterior, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.
  • DASHBOARD_ID: ID del panel de control.

El comando devuelve el panel de control 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 panel de control individual. Sin embargo, puedes ver estos paneles de control mediante la Google Cloud consola.

REST

Para obtener un panel de control personalizado específico, envía el ID del panel de control al endpoint 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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.
  • ${DASHBOARD_ID}: variable de entorno que almacena el ID del panel de control.

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

El método devuelve 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 de control personalizado, invoca el método dashboards.patch. Para obtener el valor actual de etag, puedes invocar el método dashboards.get y buscarlo en la respuesta.

gcloud

Para actualizar un panel de control personalizado, usa gcloud monitoring dashboards update, especifica el ID del panel de control que quieras actualizar y proporciona los cambios que quieras hacer.

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

Antes de ejecutar el comando anterior, sustituya lo siguiente:

  • PROJECT_ID: identificador del 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.
  • DASHBOARD_ID: ID del panel de control.

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

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

Terraform

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor Terraform.

Para actualizar un panel de control con Terraform, siga estos pasos:

  1. Instala y configura Terraform para tu 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.

  2. Usa el recurso de Terraform google_monitoring_dashboard.

    En el comando, define los siguientes campos:

    • dashboard_json: representación JSON del panel de control con el formato Dashboards.

    • parent: el nombre completo de tu proyecto. Por ejemplo, puedes asignar a este campo el valor "projects/PROJECT_ID", donde PROJECT_ID es el ID de tu proyecto 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.

REST

Para actualizar un panel de control personalizado, envía una solicitud PATCH al endpoint 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}: variable de entorno que almacena el ID del proyecto en el que se va a crear el panel de control. 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.
  • ${DASHBOARD_ID}: variable de entorno que almacena el ID del panel de control.

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

Siguientes pasos