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.
En los siguientes ejemplos, se muestra cómo administrar tus paneles mediante curl para invocar la API y cómo usar Google Cloud CLI.
Si bien también puedes administrar tus paneles personalizados mediante la
consola de Google Cloud, la API te proporciona una
manera 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 panel.dashboards.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 a la API directamente con la utilidad curl o con Google Cloud CLI.
No puedes recuperar, editar ni borrar paneles predefinidos.
Acerca de los paneles
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 etiquetas y filtros a tu panel. Las etiquetas pueden ayudarte a encontrar un panel o indicar el tipo de contenido en él.
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 varios tipos de objetos Widget:
Widgets de gráfico y tabla:
XyChart: muestra los datos mediante los ejes Y y X. Los siguientes gráficos son instancias del widgetXyChart:Gráficos de líneas
Gráficos de barras
Gráficos de áreas apiladas
Mapas de calor
Gráficos de Análisis de registros
Widgets de SLO, pero no se admite la creación de gráficos de SLO con la API.
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 se refiera al eje Y izquierdo o derecho. Cuando se representan varias métricas, puedes usar ambos ejes Y.
PieChart: Muestra el valor más reciente de una métrica, en el que cada serie temporal contribuye con una porción al gráfico.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 en función de columnas, filtrarla y agregar o quitar columnas de la pantalla.
Gráficos de políticas de alertas y widgets de incidentes:
AlertChart: Muestra un resumen de una política de alertas de condición única. Este widget muestra los datos como un gráfico de líneas, muestra el umbral y enumera la cantidad de incidentes abiertos.IncidentList: Muestra una lista de incidentes. Puedes configurar el widget para que muestre incidentes en políticas de alertas específicas o tipos de recursos específicos.
Widgets de registro y error:
ErrorReportingPanel: Muestra los grupos de errores que se almacenan en el proyecto de Google Cloud seleccionado.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 las entradas de registro almacenadas en proyectos de Google Cloud accesibles a través del permiso de métricas actual.
Widgets de texto y organización:
Para incluir estos widgets en un panel, este debe tener un
MosaicLayout.CollapsibleGroup: Muestra una colección de widgets. Puedes contraer la vista de un grupo.SingleViewGroup: Muestra un widget en una colección de widgets. Puedes seleccionar qué widget mostrar.SectionHeader: Crea un divisor horizontal en el panel y una entrada en el índice del panel.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 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"
}
}
}
]
}
}
Etiquetas del panel
Las etiquetas pueden ayudarte a administrar y organizar tus paneles. Por ejemplo, puedes agregar una etiqueta llamada prod para indicar que el panel muestra datos de series temporales y datos de registro para tus recursos de producción. Como alternativa, puedes agregar la etiqueta playbook para indicar que el panel contiene información que te ayuda a solucionar problemas.
Agregar etiquetas a un panel es opcional.
Por ejemplo, a continuación se muestra un objeto Dashboard que especifica la etiqueta llamada playbook.
{
"displayName": "Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
...
]
},
"dashboardFilters": [],
"labels": {
"playbook": ""
}
}
Como se muestra en el ejemplo anterior, el campo labels se implementa como una map, en la que los campos key y value son cadenas. Cuando agregas una etiqueta a un panel, configura key como el nombre de la etiqueta y el campo value como una string vacía.
Filtros del panel
Cuando diseñas un panel, puedes identificar varias formas de ver los datos que muestra. Por ejemplo, cuando un panel muestra métricas para instancias de máquina virtual (VM), es posible que desees ver métricas de todas las VM y 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. Se pueden aplicar filtros permanentes a algunos o a todos los widgets del panel. Cuando visualizas el panel con la consola de Google Cloud, 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.
Hay varios tipos de filtros permanentes del panel:
Los filtros para 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 basado en 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 es para una etiqueta y un valor específicos. Tú determinas a qué widgets se aplica una variable de plantilla.
Todos los tipos de filtro 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:
{
"dashboardFilters": [
{
"filterType": "RESOURCE_LABEL",
"labelKey": "instance_id",
"stringValue": "3133577226154888113",
"templateVariable": "iid"
},
{
"filterType": "RESOURCE_LABEL",
"labelKey": "zone"
}
],
"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 iid y un filtro para todo el panel con la clave de etiqueta zone. La variable de plantilla es un alias de la etiqueta instance_id.
En la estructura de datos de una variable de plantilla, no se enumeran los widgets a los que se aplica. En su lugar, debes asociar un widget con una variable de plantilla modificando la consulta del widget para que incluya una referencia a la variable. Cuando el widget se muestra en el panel, se resuelve el valor de la variable de plantilla.
Consulta las siguientes secciones para aprender a anotar paneles y gráficos de registros:
- Panel de registros
- Gráficos y tablas definidos por MQL
- Gráficos y tablas definidos por PromQL
- Gráficos y tablas definidos con filtros de series temporales
Panel de registros
Agrega la variable al panel de consultas para configurar un panel de registros a fin de filtrar la visualización según el valor de una variable de plantilla. En el siguiente ejemplo, se ilustra una consulta que filtra por el valor de la variable de plantilla iid:
${iid}
Antes de que el panel de registros consulte los registros que se mostrarán, se resuelve la variable de plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la sentencia resource.labels."instance_id"="12345".
También puedes incluir solo el valor de una variable de plantilla en una consulta. Te recomendamos que solo uses el valor como parte de un filtro definido con una expresión regular. Por ejemplo, la siguiente consulta usa una expresión regular para hacer coincidir las entradas de registro que tienen una carga útil de JSON que contiene la string descrita:
jsonPayload.message=~"Connected to instance: ${iid.value}"
Si configuraste una consulta para el panel de registros y, luego, seleccionas el botón para abrir el Explorador de registros, las variables de la plantilla se resuelven antes de que se abra el Explorador de registros.
En la siguiente tabla, se muestra cómo el panel de registros resuelve la variable de plantilla:
| Sintaxis | Valor seleccionado |
Expresión del panel de registros resuelta |
|---|---|---|
${iid} |
12345 |
resource.labels."instance_id"="12345" |
${iid} |
* |
"" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Gráficos y tablas definidos por MQL
Cuando uses el lenguaje de consulta de Monitoring (MQL) para configurar un gráfico, agrega un canal y la variable a la cadena de consulta:
fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}
Antes de que se realicen las consultas del gráfico de la serie temporal que se mostrará, se resuelve la variable de plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la sentencia filter (resource.instance_id == '12345'). Este filtro coincide con las series temporales que tienen una etiqueta llamada resource.instance_id y solo cuando el valor de esa etiqueta es exactamente 12345.
Si deseas filtrar series temporales mediante una expresión regular, configura la consulta para que incluya solo el valor de la variable de plantilla.
Para ilustrar la sintaxis, a continuación se muestra cómo usar una expresión regular a fin de determinar si el valor de la etiqueta resource.instance_id contiene el valor de la variable de plantilla iid:
fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m
En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla para consultas de MQL:
| Sintaxis | Valor seleccionado |
Expresión de MQL resuelta |
|---|---|---|
${iid} |
12345 |
filter (resource.instance_id == '12345') |
${iid} |
* |
filter (true) |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Gráficos y tablas definidos por PromQL
Cuando definas un gráfico con PromQL, agrega a la cadena de consulta la variable unida entre llaves:
compute_googleapis_com:instance_cpu_utilization {
project_id="my-project", ${iid}
}
Antes de que se realicen las consultas del gráfico de la serie temporal que se mostrará, se resuelve la variable de plantilla. En este ejemplo, si el valor de la variable de plantilla es "12345", entonces ${iid} se reemplaza por la sentencia instance_id == '12345'.
De manera similar a MQL, cuando defines un widget con PromQL, la consulta solo puede extraer el valor de la variable de plantilla. Te recomendamos que solo uses el valor como parte de un filtro definido con una expresión regular. Para ilustrar la sintaxis, a continuación se muestra cómo usar una expresión regular para determinar si el valor de la etiqueta instance_id contiene el valor de la variable de plantilla iid:
compute_googleapis_com:instance_cpu_utilization{
instance_id=~"${iid.value}"
}
En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla para consultas de PromQL:
| Sintaxis | Valor seleccionado |
Se resolvió la expresión de PromQL |
|---|---|---|
${iid} |
12345 |
instance_id == '12345' |
${iid} |
* |
noop_filter=~".*" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.+ |
Gráficos y tablas definidos con filtros de series temporales
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\" ${iid}"
A diferencia de los gráficos definidos por MQL y PromQL, no puedes usar el valor de una variable de plantilla en un filtro de series temporales.
En la siguiente tabla, se muestra cómo se resuelve la variable de plantilla:
| Sintaxis | Valor seleccionado |
Expresión de filtro resuelta |
|---|---|---|
${iid} |
12345 |
resource.instance_id == "12345" |
${iid} |
* |
Omitido |
${iid.value} |
12345 |
No compatible |
${iid.value} |
* |
No compatible |
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 que se indican en 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.
Puedes administrar el panel a través de la
consola de Google Cloud.
Para obtener configuraciones de panel adicionales, consulta Paneles y diseños de ejemplo.
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 mediante el archivo my-updated-dashboard.json y se muestra una copia de la ficha actualizada del panel. Los datos que se muestran incluyen un valor de etag nuevo.
¿Qué sigue?
- Ejemplos de paneles y diseños
- Crea y administra paneles personalizados con la consola de Google Cloud