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. Estos ejemplos ilustran cómo administrar tus paneles usando curl para invocar la API, y se muestra 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 a la API directamente con la utilidad curl o con el 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 te ayudan a encontrar un panel o indicar el tipo de contenido en el 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:

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

    Este widget muestra un conjunto de datos que puede de series temporales o que se generan mediante una consulta en SQL. Este widget te permite asociar los datos del gráfico con el eje Y de la izquierda o la derecha. Cuándo puede 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 contribuye con una porción al gráfico.

    • Scorecard: muestra el valor más reciente de uno. de las series temporales 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 codificar las celdas con colores y configurar los nombres y los datos de las columnas. alineación.

  • 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 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 de 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, podría agregar una etiqueta llamada prod para indicar que el panel muestra de series temporales y datos de registro para tus recursos de producción. Por otro lado, puedes agregar la etiqueta playbook para indicar que el panel contiene información para ayudarte a solucionar problemas.

Agregar etiquetas a un panel es opcional.

Por ejemplo, a continuación se muestra un objeto Dashboard que especifica la etiqueta denominada 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 agregas un elemento a un panel, establece key en el nombre de la etiqueta y value a una string vacía.

Filtros 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 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 este recomendamos que crees un filtro permanente y establezcas la configuración de ese filtro a la vista más usada. Los filtros permanentes pueden se aplican 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 filtro y que no especifiquen 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. 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 es para una etiqueta y un valor específicos. Tú determinas qué widgets a los que 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, 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

Configurar un panel de registros para filtrar la visualización según el valor de una variable de plantilla, agrégala al panel de consultas. 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, 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 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 de que se abra el Explorador de registros.

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

Sintaxis Selected
Value		 Expresión del panel de registros resuelta
${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, la variable de plantilla se haya resuelto. En este ejemplo, si el valor de la variable de plantilla es "12345", luego, ${iid} se reemplaza con 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, el siguiente muestra cómo usar una expresión regular para determinar si el valor del 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 MQL. en la nube:

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 el variable unida por 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", luego, ${iid} se reemplaza con 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 usa solo el valor como parte de un filtro definido con una expresión regular. Para ilustramos la sintaxis; a continuación, se muestra cómo usar una expresión regular para determina si el valor de la etiqueta instance_id contiene el valor del 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 PromQL. en la nube:

Sintaxis Selected
Value		 Se resolvió la expresión de PromQL
${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 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 deseas 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 a través de la 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 completamente calificado 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

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.

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, utiliza la 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, especificar el ID del panel que se actualizará y proporcionar los cambios al 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 my-updated-dashboard.json y devuelve una copia del archivo actualizado panel de control de calidad. Los datos que se muestran incluyen un valor de etag nuevo.

¿Qué sigue?