Crea y administra paneles por API

En este documento, se describe cómo puedes crear y administrar los paneles personalizados y los widgets en esos paneles mediante 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 puede administrar sus paneles personalizados a través de la la consola de Google Cloud, la API te proporciona una y 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 de forma directa mediante la utilidad curl o Google Cloud CLI.

No puedes recuperar, editar ni borrar paneles predefinidos.

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 datos sobre 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 desde 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 una 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 la política de alertas o la información del incidente:

    • 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, muestra el de seguridad de la nube y enumera la cantidad de incidentes abiertos.

    • IncidentList: Muestra una lista de incidentes. Puedes configurar el widget para que muestre incidentes en políticas de alertas específicas o en 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 contraer la vista de un grupo.

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

    • SectionHeader: Crea un divisor horizontal en tu panel y crea una entrada en la tabla del panel contenidos.

    • 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.

Filtros del panel

Cuando diseñas un panel, puedes identificar varias formas de ver la datos que muestra el panel. Por ejemplo, supongamos que un panel muestra datos de series temporales para tus instancias de máquina virtual (VM). Es posible que quieras para ver los datos de series temporales de todas las VMs, y puedes solo los datos que están en una zona específica. En esta situación, te recomendamos que crees un filtro permanente y establezcas el valor predeterminado de ese filtro en la vista que se usa con más frecuencia. Los filtros permanentes se pueden aplicar a algunos o a todos los widgets del panel. 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 temporalmente el valor del filtro.

Hay varios tipos de filtros permanentes del panel:

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

    Por ejemplo, cuando un gráfico incluye el filtro zone = us-central1-a, este ignora un filtro de panel basado en la etiqueta zone. De forma similar, 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. Tú determinas a qué widgets se aplica una variable de plantilla.

Todos los tipos de filtros 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, se asocia un widget con una variable de plantilla modificar la consulta del widget para incluir una referencia a la variable Cuando el widget se muestra en el panel, se resuelve el valor de la variable de plantilla.

Consulta las siguientes secciones para aprender a anotar paneles y gráficos de registros:

Panel de registros

Para configurar un panel de registros que filtre la visualización según el valor de una variable de plantilla, agrega la variable al panel de consulta. En el siguiente ejemplo, se ilustra una consulta que filtra por el valor de la variable de plantilla iid:

${iid}

Antes de que el panel de registros consulte los registros que se mostrarán, se resuelve la variable de plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", luego, ${iid} se reemplaza con la sentencia 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, la siguiente consulta usa una expresión regular para que coincida con las entradas de registro que tienen una carga útil JSON que contiene los valores descritos cadena:

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

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

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

Sintaxis Selected
Value		 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 supervisión (MQL) para configurar un gráfico, agrega una barra y la variable a la cadena de consulta:

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

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

Cuando quieras filtrar series temporales con una expresión regular, configurar 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 Selected
Value		 Expresión de MQL resuelta
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

Gráficos y tablas definidos por PromQL

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

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

Antes de que el gráfico consulte las series temporales que se mostrarán, la variable de plantilla se haya resuelto. En este ejemplo, si el valor de la variable de plantilla es "12345", ${iid} se reemplaza por la sentencia instance_id == '12345'.

De manera similar a MQL, cuando defines un widget con PromQL, la consulta solo puedes extraer 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 Selected
Value		 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 cadena 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 Selected
Value		 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 que se indican en Obtener panel para descargar la definición de el panel original.
  2. Edita el JSON que se muestra para quitar el 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 tu panel mediante Consola de Google Cloud.

Para ver parámetros de configuración adicionales del panel, 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 de gcloud monitoring dashboards list.

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

Paginar 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 de 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 de 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 lista del panel actualizado. Los datos que se muestran incluyen un valor de etag nuevo.

¿Qué sigue?