Crea y administra paneles mediante la API

En este documento, se describe cómo crear y administrar paneles personalizados y los widgets de esos paneles mediante el recurso Dashboard en la API de Cloud Monitoring. En estos ejemplos, se muestra cómo administrar tus paneles mediante curl para invocar la API y se muestra 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 proporciona una forma programática de administrar muchos paneles al mismo tiempo.

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

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

No puedes recuperar, editar ni borrar los paneles predefinidos.

Antes de comenzar

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 filtros permanentes a tu panel.

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:

  • Widgets de gráfico y tabla:

    • XyChart: muestra los datos mediante los ejes Y y X. Los siguientes gráficos son instancias del widget XyChart:

    • Gráficos de líneas

    • Gráficos de barras

    • Gráficos de áreas apiladas

    • Mapas de calor

    • Gráficos de Análisis de registros

    • Widgets de SLO, pero no se admite la creación de gráficos de SLO mediante la API.

    Si creas un gráfico de líneas, un gráfico de barras apiladas o un gráfico de áreas apiladas, puedes especificar que una métrica haga referencia al eje Y izquierdo o derecho. Cuando se representan varias métricas, puedes usar ambos ejes Y.

    • PieChart: Muestra el valor más reciente de una métrica, en la que cada serie temporal contribuye con una porción al gráfico.

    • Scorecard: muestra el último valor de una métrica y cómo se relaciona este valor con uno o más umbrales.

    • TimeSeriesTable: Muestra el valor más reciente de una métrica. Puedes ordenar la tabla según las columnas, filtrarla y agregar o quitar columnas de la pantalla.

  • Gráfico de alertas y widgets 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 de modo que muestre incidentes para políticas de alertas específicas o tipos de recursos específicos.

  • Widgets de registro y error:

  • Widgets de texto y organización:

    Para incluir estos widgets en un panel, este debe tener un MosaicLayout.

    • 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 una división 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.

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

Filtros del panel

Cuando diseñas un panel, puedes identificar varias formas de ver los datos que muestra. Por ejemplo, cuando en un panel se muestran las métricas de las instancias de máquina virtual (VM), es posible que desees ver las métricas de todas las VM y de una zona específica. En este tipo de situación, te recomendamos que crees un filtro permanente y establezcas su valor predeterminado en la vista más usada. Los filtros permanentes se pueden aplicar a algunos widgets del panel o a todos ellos. Cuando visualizas el panel con la consola de Google Cloud, la barra de herramientas del panel muestra tus filtros permanentes y un menú que puedes usar para cambiar de forma temporal el valor del filtro.

Existen varios tipos de filtros de panel permanentes:

  • Los filtros de todo el panel se aplican a todos los widgets de un panel que admiten la etiqueta de filtro y que no especifican un valor para esa etiqueta.

    Por ejemplo, cuando un gráfico incluye el filtro zone = us-central1-a, ese gráfico ignora un filtro de panel basado en la etiqueta zone. Del mismo modo, los gráficos sin una etiqueta zone ignoran los filtros del panel con esta etiqueta.

  • Las variables de plantilla son variables con nombre que se aplican a widgets específicos. Cada variable corresponde a una etiqueta y un valor específicos. Determinas a qué widgets se aplica una variable de plantilla.

Todos los tipos de filtro se representan con la misma estructura de datos. Para obtener más información, consulta DashboardFilter.

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

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

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

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

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

Panel de registros

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

${iid}

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

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

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

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

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

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

Gráficos y tablas definidos por MQL

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

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

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

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

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

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

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

Tablas y gráficos definidos por PromQL

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

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

Antes de que se realicen las consultas de gráfico para las series temporales que se muestran, se resuelve la variable de la plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la instrucción instance_id == '12345'.

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

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

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

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

Gráficos y tablas definidos con filtros de series temporales

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

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

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

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

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

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.

Cuando creas un panel, la API genera automáticamente el dashboard_id. Si deseas especificar un dashboard_id personalizado, puedes establecer el campo name de un objeto Dashboard. El formato del campo de nombre se parece al siguiente:

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

Protocolo

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

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

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

  1. Completa los pasos 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.

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

Para ver configuraciones de panel adicionales, consulta Ejemplos de paneles y diseños.

Borrar paneles

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

Protocolo

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}

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

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 projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

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

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.

Protocolo

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

gcloud

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

gcloud monitoring dashboards list

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

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.

Protocolo

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

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.

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

Obtener panel

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

Protocolo

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}

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

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

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 gcloud monitoring dashboards describe.

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.

Protocolo

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}

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

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

En los ejemplos, se actualiza un panel personalizado existente con el archivo my-updated-dashboard.json y se muestra una copia de la ficha del panel actualizada. Los datos que se muestran incluyen un valor etag nuevo.

¿Qué sigue?