Administra los paneles con la API

Puedes administrar paneles y gráficos personalizados 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.

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

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

Cualquier widget que muestre datos recuperados de una serie temporal tendrá 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 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 las 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

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 gcloud 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 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/[MY_PROJECT_ID]/dashboards/[MY_DASHBOARD_ID]

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

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

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.

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

Obtén paneles

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.

Actualiza paneles

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 existente con el archivo my-updated-dashboard.json y se muestra una copia de la lista del panel actualizado, incluido un nuevo valor etag.