Administra paneles por API

En esta página, se describe cómo administrar paneles personalizados y los widgets en esos paneles mediante el recurso Dashboard en la API de Cloud Monitoring. Si bien también puedes administrar tus paneles personalizados a través de Google Cloud Console, la API te proporciona una manera programática de administrar muchos paneles al mismo tiempo. También puedes crear, configurar y manipular los widgets del panel mediante la API de Cloud Monitoring.

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

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

No puedes recuperar, editar o borrar paneles predefinidos con la API.

Antes de comenzar

Cuando creas un panel, debes especificar qué componentes, o widgets, deseas mostrar y el diseño de esos widgets.

Diseños de paneles

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 solo componente de panel y la configuración de cómo presentar el componente en el panel. Un panel puede tener más de un widget. Existen varios tipos de objetos Widget:

  • XyChart: muestra datos mediante los ejes Y y X. Los gráficos de líneas, de barras, apilados y de mapas de calor creados a través de Google Cloud Console son instancias de este widget. Si creas un gráfico de líneas, de barras apiladas o de áreas apiladas, puedes especificar que una métrica haga referencia al eje Y a la izquierda o derecha. Cuando se muestran varias métricas, puedes usar ambos ejes Y.

    Los gráficos de SLO también son instancias del widget XyChart, pero no se admite la creación de gráficos de SLO mediante la API.

  • AlertChart: Muestra un resumen de una política de alertas de condición única. que muestra los datos como un gráfico de líneas, el umbral y enumera la cantidad de incidentes abiertos.

  • CollapsibleGroup: Muestra una colección de widgets. Puedes contraer la vista de un grupo. Para incluir estos widgets en un panel, el panel debe tener una MosaicLayout.

  • LogsPanel: Muestra las entradas de registro con alcance de proyecto que se almacenan en el proyecto actual de Google Cloud. Puedes configurar el widget para que muestre entradas de registro almacenadas en proyectos de Cloud a los que se pueda acceder a través del alcance de las métricas actual.

  • Scorecard: Muestra el valor más reciente 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.

  • Text: Muestra contenido de texto, como texto sin procesar o una 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 derecho 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"
          }
        }
      }
    ]
  }
}

Especifica los datos que se mostrarán

Cualquier widget que muestre datos recuperados de una serie temporal tiene un objeto TimeSeriesQuery incorporado. Este objeto especifica los datos de series temporales que se usarán en el widget.

Puedes especificar los datos de series temporales para que se muestren de la siguiente manera:

Si creaste los widgets del panel a través de Google Cloud Console, ya estás familiarizado con las métricas y series temporales.

Para obtener información sobre las métricas y las series temporales, consulta Métricas, series temporales y recursos.

Además, es posible que las guías Create and manage dashboard widgets, Select data to chart y Set view options sean útiles. Si bien estas guías se escriben para crear paneles mediante Google Cloud Console, los conceptos también se aplican a la creación de widgets mediante la API de Cloud Monitoring.

Ejemplos en los que se usa curl

En esta sección, se describen las convenciones y la configuración que se usan para invocar la API de Cloud Monitoring mediante la herramienta de curl. En los ejemplos de esta página, se accede a la API mediante la herramienta de curl para enviar solicitudes HTTP a los extremos de REST. Para configurar las variables utilizadas en las invocaciones de ejemplo, usa la siguiente información.

Autenticación

  1. Crea una variable de entorno para guardar el ID de tu proyecto de Cloud. En estos ejemplos, se usa PROJECT_ID:

    PROJECT_ID=a-gcp-project-12345
    
  2. Realiza la autenticación en la CLI de Google Cloud:

    gcloud auth login
    
  3. De manera opcional, puedes evitar tener que especificar el ID del proyecto con cada comando si lo configuras como predeterminado mediante la CLI de gcloud:

    gcloud config set project ${PROJECT_ID}
    
  4. Crea un token de autorización y captúralo en una variable de entorno. Estos ejemplos llaman a la variable ACCESS_TOKEN:

    ACCESS_TOKEN=`gcloud auth print-access-token`
    

    Deberás actualizar el token de acceso de forma periódica. Si los comandos que funcionaban de repente informan que no estás autenticado, vuelve a emitir este comando.

  5. Para verificar que hayas obtenido un token de acceso, repite la variable ACCESS_TOKEN:

    echo ${ACCESS_TOKEN}
    ya29.ImW8Bz56I04cN4qj6LF....
    
  6. Cree una variable de entorno para conservar el ID de su panel. En estos ejemplos, se usa la variable DASHBOARD_ID.

Invocar a curl

Cada invocación a curl incluye un conjunto de argumentos, seguido de la URL de un recurso. Los argumentos comunes incluyen valores especificados por las variables de entorno PROJECT_ID, DASHBOARD_ID y ACCESS_TOKEN. Es posible que también debas especificar otros argumentos, por ejemplo, para especificar el tipo de solicitud HTTP (por ejemplo, -X DELETE).

Cada invocación curl tiene esta estructura general:

curl -H "Authorization: Bearer $ACCESS_TOKEN" <other_args> https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/<request>

Por ejemplo, para enumerar todos los paneles personalizados de tu proyecto, envía la siguiente solicitud:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

A continuación, se ilustra la respuesta de este comando para un proyecto de Cloud:

{
  "dashboards": [
    {
      "name": "projects/123456789000/dashboards/c2ab1f1c-b8b9-1234-9c48-c7745802b659",
      "displayName": "Grid-layout example",
      "etag": "76a95cc500a7c7d6b3799709c13afe91",
      "gridLayout": {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    },
    {
      "name": "projects/123456789000/dashboards/cae85db7-6920-4e67-a45c-97a94c0e2679",
      "displayName": "Row-layout example",
      "etag": "a600be01afe0b37762cd7a9b92fc3e7e",
      "rowLayout": {
        "rows": [
          {
            "widgets": [
              {
                "text": {
                  "content": "Text Widget 1",
                  "format": "RAW"
                }
              },
              {
                "text": {
                  "content": "**Text Widget 2**",
                  "format": "MARKDOWN"
                }
              },
              {
                "text": {
                  "content": "_Text Widget 3_",
                  "format": "MARKDOWN"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Cree un panel

Para crear un nuevo panel 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 el dashboard_id de forma automática. Si deseas especificar un dashboard_id personalizado, puedes establecer el campo name de un objeto Dashboard. El formato del campo del nombre debe tener el siguiente aspecto:

"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

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

En los ejemplos, se crea un panel de muestra mediante el archivo my-dashboard.json. Ahora puedes administrar el panel a través de Google Cloud Console.

Para obtener más opciones de configuración de paneles, consulta Paneles y diseños de muestra.

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 deseas borrar.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Si se ejecuta de forma correcta, el método mostrará una respuesta vacía. De lo contrario, se 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 de gcloud monitoring dashboards delete.

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

Los ejemplos muestran los paneles personalizados asociados con tu proyecto.

Pagina la respuesta de la lista

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

Protocolo

Para la página inicial de la lista de resultados, especifica el parámetro de búsqueda pageSize con la 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 el 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. como los siguientes:

gcloud monitoring dashboards list --page-size=1

Obtener panel

A fin de obtener un panel personalizado específico para 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 al 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 deseas actualizar y proporciona 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 mediante el archivo my-updated-dashboard.json y se muestra una copia de la lista del panel actualizada. Los datos que se muestran incluyen un nuevo valor de etag.