Administra paneles por API

En esta página, se describe cómo administrar los 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 de forma directa mediante la utilidad curl o la herramienta de línea de comandos de gcloud.

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 que se muestren y el diseño de esos widgets.

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

  • XyChart: muestra los datos mediante los ejes Y y X. Los gráficos de líneas, de barras, de pilas 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.

  • 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 las columnas, filtrarla y agregar o quitar columnas de la pantalla.

  • Text: muestra el contenido textual, ya sea como texto sin formato o como string de Markdown.

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

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 encuentres las guías Crea y administra widgets del panel, Selecciona los datos para el gráfico y Configura las opciones de vista. útil. 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 de uso de 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.

Authentication

  1. Crea una variable de entorno para guardar el ID de tu proyecto de Google Cloud. 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....
    
  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 muestra 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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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

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

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 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 mediante el archivo my-updated-dashboard.json y se muestra una copia de la lista del panel actualizada. Los datos de retorno incluyen un valor etag nuevo.