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 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:

  • 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 con la API.

    Si creas un gráfico de líneas, un gráfico de barras apiladas o un gráfico de áreas apiladas, luego especifica que una métrica se refiere al eje Y de la izquierda o la derecha. Cuando hay varios métricas del proyecto, puedes usar ambos ejes Y.

    • PieChart: Muestra el valor más reciente de una métrica. en el 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 columnas, filtrarla y agregar o quitar columnas de la pantalla.

  • Gráficos de políticas de alertas y widgets de incidentes:

    • AlertChart: Muestra un resumen de una sola condición. política de alertas. 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 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 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.

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 muestra en el ejemplo anterior, el campo labels se implementa como una map, donde 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 la datos que muestra el panel. Por ejemplo, cuando un panel muestra métricas para instancias de máquina virtual (VM), es posible que desees ver las métricas y es posible que quieras ver las métricas de una zona específica. En este tipo de 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 veas el panel con 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 para una variable de plantilla no enumera los widgets para los cuales que se aplique. 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", luego, ${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 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 Monitoring (MQL) para configurar un gráfico, agrega una canalización y el 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 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.

Si quieres 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 por la sentencia instance_id == '12345'.

Al igual que en 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 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 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 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 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 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 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?