En este documento, se describe cómo crear y administrar paneles personalizados y los widgets en esos paneles mediante el recurso Dashboard en la API de Cloud Monitoring.
Los ejemplos que se presentan aquí ilustran cómo administrar tus paneles mediante curl para invocar la API y muestran cómo usar Google Cloud CLI.
Si bien también puedes administrar tus paneles personalizados a través de la consola de Google Cloud, la API te proporciona una forma programática de administrar muchos paneles al mismo tiempo.
El extremo admite los siguientes métodos para administrar y configurar paneles:
dashboards.create: crea un paneldashboards.delete: borra un panel especificadodashboards.list: recupera una lista de todos los paneles de un proyecto determinadodashboards.get: recupera un panel especificadodashboards.patch: actualiza la estructura de un panel especificado
Puedes invocar la API directamente con la utilidad curl o mediante Google Cloud CLI.
No puedes recuperar, editar o borrar los paneles predefinidos.
Antes de comenzar
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 filtros permanentes a tu 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. Hay varios tipos de objetos Widget:
XyChart: muestra los datos mediante los ejes Y y X. Los gráficos de líneas, de barras, de áreas apiladas y de mapas de calor creados a través de la consola de Google Cloud son instancias de este widget. Si creas un gráfico de líneas, un gráfico de barras apiladas o un gráfico de áreas apiladas, puedes especificar que una métrica haga referencia al eje Y izquierdo o derecho. Cuando se registran 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 una sola condición. Este widget muestra los datos como un gráfico de líneas, muestra 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 unMosaicLayout.IncidentList: Muestra una lista de incidentes. Puedes configurar el widget a fin de que muestre incidentes para políticas de alertas específicas o para tipos de recursos específicos.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 mostrar las entradas de registro almacenadas en proyectos de Cloud a los que se puede acceder a través del alcance de las métricas actual.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.
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 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"
}
}
}
]
}
}
Filtros del panel
Cuando diseñas un panel, puedes identificar varias formas de ver los datos que se muestran. Por ejemplo, cuando un panel muestra métricas de instancias de máquina virtual (VM), es posible que quieras ver las métricas de todas las VM y las de una zona específica. En este tipo de situación, te recomendamos que crees un filtro permanente y establezcas el valor predeterminado de ese filtro en la vista más usada. Los filtros permanentes se pueden aplicar a algunos o a todos los widgets del panel. Cuando visualizas el panel con Google Cloud Console, la barra de herramientas del panel muestra tus filtros permanentes y un menú que puedes usar para cambiar de forma temporal el valor del filtro.
Existen varios tipos de filtros permanentes del panel:
Los filtros que se aplican a todo el panel se aplican a todos los widgets de un panel que admiten la etiqueta de filtro y que no especifican 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 en función de la etiquetazone. Del mismo modo, los gráficos sin una etiquetazoneignoran los filtros del panel con esta etiqueta.Las variables de plantilla son variables con nombre que se aplican a widgets específicos. Cada variable corresponde a una etiqueta y un valor específicos. Tú determinas a qué widgets se aplica una variable de plantilla.
Todos los tipos de filtros 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:
{
"category": "CUSTOM",
"dashboardFilters": [
{
"filterType": "RESOURCE_LABEL",
"labelKey": "zone",
"stringValue": "us-central1-b",
"templateVariable": "my_zone_temp_var"
},
{
"filterType": "RESOURCE_LABEL",
"labelKey": "project_id",
"stringValue": "my-project-id",
"templateVariable": ""
}
],
"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 my_zone_temp_var.
La segunda entrada corresponde a un filtro para todo el panel. Para estos filtros, que se aplican a todos los widgets del panel, el valor del campo templateVariable se establece en una string de longitud cero, "".
La estructura de datos para una variable de plantilla no muestra los widgets a los que se aplica. En cambio, cuando asocias un widget con una variable de plantilla, la consulta del widget se modifica para incluir una referencia a la variable. Cuando uses el lenguaje de consulta de Monitoring (MQL) para configurar un gráfico, agrega una canalización y la variable a la string de consulta:
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n|
every 1m\n| ${my_zone_temp_var}\n"
Cuando defines un gráfico mediante PromQL, agrega lo siguiente a la string de consulta unida por llaves:
"prometheusQuery" :
"compute_googleapis_com:instance_cpu_utilization {project_id=\"my-project\", ${my_zone_temp_var}}\n"
En el ejemplo anterior, se ilustra cómo filtrar un widget definido por PromQL para mostrar solo las series temporales que están en el proyecto de Google Cloud my-project y que coinciden con una variable de plantilla.
Cuando definas un gráfico con filtros de series temporales, agrega la variable a la string de filtro:
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
resource.type=\"gce_instance\" ${my_zone_temp_var}"
En el siguiente JSON, se muestran las strings de consulta en el contexto de la definición completa del gráfico:
{
...
"displayName": "Illustrate Template Variables",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"title": "MQL",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n| every 1m\n| ${my_zone_temp_var} \n"
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 0,
"yPos": 0
},
{
"height": 4,
"widget": {
"title": "LTS",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"minAlignmentPeriod": "60s",
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"apiSource": "DEFAULT_CLOUD",
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${my_zone_temp_var}"
}
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 6,
"yPos": 0
}
]
}
}
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:
Mediante el uso de filtros de supervisión. Los filtros se usan en las consultas
TimeSeriesFilteryTimeSeriesFilterRatio. Para obtener más información sobre cómo recuperar datos de métricas de esta manera, consulta Lee datos de métricas.Mediante MQL Este enfoque usa una consulta de MQL en un objeto
TimeSeriesQuery. La string de consulta se pasa como el valor del campotimeSeriesQueryLanguage.- Para obtener información general sobre MQL, consulta Usa el lenguaje de consulta de Monitoring.
- Si deseas obtener información sobre cómo proporcionar consultas de MQL para los gráficos, consulta Usa MQL desde la API de Monitoring: Gráficos.
Si creaste los widgets del panel a través de Google Cloud Console, ya estás familiarizado con las métricas y las series temporales.
Para obtener información sobre las métricas y series temporales, consulta Métricas, series temporales y recursos.
Las siguientes guías también pueden resultarte útiles:
- Cómo crear y administrar widgets de panel
- Selecciona métricas para los gráficos de los paneles
- Cómo configurar las opciones de vista
Si bien estas guías están escritas 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.
Configuración de ejemplos
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 este documento, se accede a la API mediante la herramienta de curl para enviar solicitudes HTTP a los extremos de REST.
Para configurar las variables usadas en las invocaciones de ejemplo, usa la siguiente información.
Authentication
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
Autentícate en Google Cloud CLI:
gcloud auth loginDe manera opcional, puedes evitar tener que especificar tu ID del proyecto con cada comando si lo configuras como predeterminado con la CLI de gcloud:
gcloud config set project ${PROJECT_ID}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.
Para verificar que cuentas con un token de acceso, reproduce la variable
ACCESS_TOKEN:echo ${ACCESS_TOKEN} ya29.ImW8Bz56I04cN4qj6LF....Crea una variable de entorno para conservar el ID de tu panel. En estos ejemplos, se usa la variable
DASHBOARD_ID.
Invocar curl
Cada invocación de 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, 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 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
Por ejemplo, si deseas duplicar un panel, haz lo siguiente:
- Completa los pasos de Obtener panel para descargar la definición del panel original.
- Edita el JSON que se muestra para quitar los campos
etagyname, y cambia el valor del campodisplayName. - 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.
Ahora puedes administrar tu panel a través de Google Cloud Console.
Para obtener configuraciones adicionales del panel, 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.
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 con el archivo my-updated-dashboard.json y se muestra una copia de la lista actualizada del panel. Los datos que se muestran incluyen un valor etag nuevo.