Administra los paneles con la API

Puedes administrar los paneles y los gráficos mediante el recurso Dashboard en la API de Cloud Monitoring. El extremo admite los siguientes métodos para administrar y configurar paneles:

Puedes invocar la API de forma directa mediante la utilidad curl o la herramienta de línea de comandos de gcloud. La integración gcloud se encuentra en versión Beta.

Si bien también puedes administrar tus paneles a través de Google Cloud Console, la API te ofrece una forma programática de administrar muchos paneles al mismo tiempo. Además, como los gráficos se implementan como widgets en los paneles, también puedes crear, configurar y manipular gráficos con la API del panel.

Antes de comenzar

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

Define el diseño del panel

Los diseños definen cómo se ordenan los componentes de un panel. La API proporciona los siguientes tres diseños:

  • GridLayout: divide el espacio disponible en columnas verticales de igual ancho y organiza un conjunto de widgets con una estrategia de filas.

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

Definición de widgets

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 los siguientes tres tipos de objetos Widget:

  • XyChart: muestra los datos mediante los ejes Y y X. Los gráficos creados a través de Google Cloud Console son instancias de este widget.

  • Scorecard: muestra el último valor de una métrica y cómo se relaciona este valor con uno o más límites. Solo puedes crear este widget con la API.

  • Text: muestra el contenido textual, ya sea como texto sin formato o como string de Markdown. Solo puedes crear este widget con la API.

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:

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

Si creaste gráficos a través de Google Cloud Console, ya conoces las métricas y las series temporales. Además de XyChart, puedes visualizar tus datos a través de widgets adicionales mediante la API del panel.

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

Además, es posible que las guías Crea gráficos, Selecciona las métricas y Configura las opciones de vista sean útiles. Si bien estas guías están diseñadas a fin de crear gráficos a través de Google Cloud Console, los conceptos para crear un gráfico, seleccionar métricas y seleccionar opciones de vista también se aplican a la creación de gráficos mediante la API del panel.

Ejemplos de uso de curl

En esta sección, se describen las convenciones y la configuración utilizadas para invocar a la API del panel mediante la herramienta 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. Usa la siguiente información sobre innovación y autenticación de curl para configurar las variables que se usan en las invocaciones de ejemplo.

Autenticación

  1. Crea una variable de entorno para retener el ID de tu lugar de trabajo de Cloud Monitoring. En estos ejemplos, se usa PROJECT_ID:

        PROJECT_ID=a-gcp-project-12345
        
  2. Autentica en el SDK de Cloud:

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

    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 cuentas con un token de acceso, reproduce la variable ACCESS_TOKEN:

    echo ${ACCESS_TOKEN}
        ya29.ImW8Bz56I04cN4qj6LF....
        

Invoca curl

Cada invocación curl incluye un conjunto de argumentos, seguido de la URL de un recurso de la API del panel. Los argumentos comunes incluyen valores especificados por las variables de entorno PROJECT_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 mostrar una lista de todos los paneles de tu proyecto, envía la siguiente solicitud:

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

Con esta solicitud, se muestra una lista de los paneles asociados con tu proyecto:

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

Crea 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/[HOST_PROJECT_ID]/dashboards/[DASHBOARD_ID]"
    

En la API, [HOST_PROJECT_ID] debe ser el proyecto host de un lugar de trabajo. Si especificas un identificador de proyecto de Google Cloud que no está asociado con un lugar de trabajo o que no es un proyecto host para un lugar de trabajo, se produce un error 400. Consulta Lugares de trabajo para obtener más información sobre cómo crear y administrar un lugar de trabajo.

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
    

Comando de gcloud

Para crear un panel en un proyecto, usa el comando gcloud beta monitoring dashboards create.

    gcloud beta monitoring dashboards create --config-from-file=my-dashboard.json
    

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

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

Para ver configuraciones adicionales del panel, ve a Paneles y diseños de muestra.

Borra paneles

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

Protocolo

Para borrar un panel, envía una solicitud DELETE al extremo Dashboard, calificada 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 completa correctamente, el método muestra una respuesta vacía. De lo contrario, muestra un error.

Comando de gcloud

Para borrar un panel, usa gcloud beta monitoring dashboards delete y especifica el ID completo del panel que deseas borrar:

    gcloud beta monitoring dashboards delete projects/[MY_PROJECT_ID]/dashboards/[MY_DASHBOARD_ID]
    

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

Enumera paneles

Para enumerar todos los paneles que pertenecen a un proyecto, invoca el método dashboards.list y especifica el ID del proyecto.

Protocolo

Para enumerar todos los paneles 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
    

Comando de gcloud

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

gcloud beta monitoring dashboards list
    

Para obtener más información, consulta la referencia gcloud beta 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.

Comando de gcloud

Para especificar la cantidad de recursos por página, pasa la marca --page-size con el comando. Por ejemplo:

    gcloud beta monitoring dashboards list --page-size=1
    

Obtén paneles

A fin de obtener un panel para un proyecto, invoca el método dashboards.get calificado con el ID del panel.

Protocolo

Para obtener un panel 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"
    }
    

Comando de gcloud

Para obtener un panel específico, usa el comando gcloud beta monitoring dashboards describe y especifica el ID del panel:

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

Actualiza paneles

Para actualizar un panel 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, envía una solicitud PATCH al extremo Dashboard y proporciona el objeto revisado Dashboard 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]
    

Comando de gcloud

Para actualizar un panel, usa gcloud beta monitoring dashboards update, especifica el ID del panel que deseas actualizar y proporciona los cambios en el panel.

    gcloud beta monitoring dashboards update [DASHBOARD_ID] --config-from-file=my-updated-dashboard.json
    

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

En los ejemplos, se actualiza un panel existente con el archivo my-updated-dashboard.json y se muestra una copia de la lista del panel actualizado, incluido un nuevo valor etag.