Neste documento, descrevemos como criar e gerenciar
painéis personalizados e os widgets neles usando
o recurso Dashboard
na API Cloud Monitoring.
Os exemplos aqui ilustram como gerenciar seus painéis usando
curl
para invocar a API e mostram como usar a CLI do Google Cloud.
Também é possível gerenciar seus painéis personalizados pelo Console do Google Cloud. No entanto, a API oferece uma maneira programática de gerenciar vários painéis ao mesmo tempo.
O endpoint é compatível com os métodos de gerenciamento e configuração de painéis a seguir:
dashboards.create
: cria um painel.dashboards.delete
: exclui um painel especificado.dashboards.list
: recupera uma lista de todos os painéis em um determinado projeto.dashboards.get
: recupera um painel especificado.dashboards.patch
: atualiza a estrutura de um painel especificado.
É possível invocar a API diretamente usando o utilitário curl
ou o
Google Cloud CLI.
Não é possível recuperar, editar ou excluir painéis predefinidos.
Sobre os painéis
Ao criar um painel, você precisa especificar quais componentes ou widgets serão exibidos e qual será o layout desses widgets. Também é possível adicionar rótulos e filtros ao painel. Os marcadores podem ajudar a encontrar um painel ou indicar o tipo de conteúdo nele.
Layouts de painel
Os layouts definem como os componentes de um painel são ordenados. A API fornece os seguintes layouts:
GridLayout
: divide o espaço disponível em colunas verticais com larguras iguais e organiza um conjunto de widgets usando uma estratégia de linha primeiro.MosaicLayout
: divide o espaço disponível em uma grade. Cada widget pode ocupar um ou mais blocos de grade.RowLayout
: divide o espaço disponível em linhas e organiza um conjunto de widgets na horizontal em cada uma delas.ColumnLayout
: divide o espaço disponível em colunas verticais e organiza um conjunto de widgets na vertical em cada uma delas.
Por exemplo, veja a seguir a representação JSON de um painel em RowLayout
com três 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 do painel
Um widget inclui um único componente de painel, além da configuração de como ele será apresentado nesse painel. Um painel pode ter mais de um widget. Há vários tipos de objetos Widget
:
O widget
XyChart
exibe dados nos eixos X e Y.Este widget exibe um conjunto de dados que pode ser de série temporal ou gerados por uma consulta SQL. Esse widget permite associar os dados do gráfico ao eixo Y à esquerda ou à direita. Quando vários tipos de métricas são representados no gráfico, é possível usar os dois eixos Y. O widget
XyChart
oferece suporte aos seguintes estilos de exibição:- Gráficos de linhas
- Gráficos de barras
- Gráficos de área empilhada
- Mapas de calor
Widgets exibidos de uma dimensão, como o valor mais recente:
PieChart
: exibe os valores mais recentes de uma coleção de séries temporais, em que cada série contribui com uma fatia do gráfico de pizza.Scorecard
: exibe o valor mais recente de uma série temporal e como esse valor se relaciona a um ou mais limites.TimeSeriesTable
: mostra o valor mais recente ou um valor agregado para cada série temporal. As tabelas podem ser personalizadas. Por exemplo, é possível codificar por cores as células e configurar nomes e dados de colunas alinhamento dos dados.
Widgets que exibem informações sobre incidentes ou política de alertas:
AlertChart
: exibe um resumo de uma política de alertas de condição única. Esse widget exibe dados como um gráfico de linhas, mostra o limite e lista o número de incidentes abertos.IncidentList
: mostra uma lista de incidentes. É possível configurar o widget para mostrar incidentes de políticas de alerta ou de tipos de recursos específicos.
Widgets que mostram entradas de registro e erros:
ErrorReportingPanel
: mostra grupos de erros armazenados no projeto selecionado do Google Cloud.LogsPanel
: exibe entradas de registro no escopo do projeto que estão armazenadas no projeto atual do Google Cloud. É possível configurar o widget para mostrar as entradas de registro armazenadas em projetos do Google Cloud acessíveis pelo escopo de métricas atual.
Widgets de texto e organização:
CollapsibleGroup
: exibe uma coleção de widgets. É possível ocultar a visualização de um grupo.SingleViewGroup
: exibe um widget em um uma coleção de widgets. É possível selecionar o widget a ser exibido.SectionHeader
: cria um divisor horizontal em seu painel e cria uma entrada na tabela do painel de conteúdo.Text
: exibe o conteúdo textual como texto bruto ou string do Markdown.
Para incluir os widgets de texto e organização em um painel, ele precisa ter um
MosaicLayout
.
Além desses objetos, é possível adicionar um marcador vazio a um painel.
O exemplo a seguir mostra a representação JSON de um
widget XyChart
com o eixo Y direito 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"
}
}
}
]
}
}
Rótulos de painel
Os identificadores ajudam você a gerenciar e organizar seus painéis. Por exemplo, você pode adicionar um rótulo chamado prod
para indicar que o painel mostra dados de séries temporais e de registros dos seus recursos de produção. Como alternativa,
adicione o rótulo playbook
para indicar que o painel
contém informações para ajudar a resolver falhas.
Adicionar rótulos a um painel é opcional.
Por exemplo, o exemplo a seguir mostra um objeto Dashboard
que
especifica o rótulo chamado playbook
.
{
"displayName": "Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
...
]
},
"dashboardFilters": [],
"labels": {
"playbook": ""
}
}
Como o exemplo anterior ilustra, o campo labels
é implementado como um
map
, em que os campos key
e value
são strings. Quando você adiciona um
rótulo a um painel, defina key
como o nome dele e defina o
value
como uma string vazia.
Filtros do painel
Ao projetar um painel, você pode identificar várias maneiras de visualizar os dados que ele exibe. Por exemplo, suponha que um painel mostre dados de séries temporais para suas instâncias de máquina virtual (VM). Talvez você queira para conferir os dados das séries temporais de todas as VMs. somente os dados que estão em uma zona específica. Nessa situação, recomendamos que você crie um filtro permanente e defina o valor padrão desse filtro para a visualização mais usada. Os filtros permanentes podem se aplicam a alguns ou a todos os widgets do painel. Ao visualizar o painel com o console do Google Cloud, a barra de ferramentas do painel mostra seus filtros permanentes e um menu que pode ser usado para mudar temporariamente o valor do filtro.
Há vários tipos de filtros permanentes no painel:
Os filtros do painel aplicam-se a todos os widgets em um painel que suportam o rótulo de filtro e que não especifiquem um valor para esse rótulo.
Por exemplo, quando um gráfico inclui o filtro
zone = us-central1-a
, ignora um filtro de painel com base no rótulozone
. Da mesma forma, os gráficos sem o marcadorzone
ignoram os filtros do painel com esse marcador.As variáveis de modelo são variáveis nomeadas que se aplicam a widgets específicos. Cada variável é para um rótulo e um valor específicos. Você determina quais widgets aos quais uma variável de modelo se aplica.
Todos os tipos de filtro são representados com a mesma estrutura de dados.
Para ver mais informações, consulte DashboardFilter
.
Por exemplo, o exemplo a seguir mostra a representação JSON parcial de um painel que define uma variável de modelo e um filtro em todo o painel:
{ "dashboardFilters": [ { "filterType": "RESOURCE_LABEL", "labelKey": "instance_id", "stringValue": "3133577226154888113", "templateVariable": "iid" }, { "filterType": "RESOURCE_LABEL", "labelKey": "zone" } ], "displayName": "Illustrate Template Variables", ...
No JSON exibido, a primeira entrada na estrutura dashboardFilters
é para uma variável de modelo com o nome iid
e um filtro em todo o painel com a chave de rótulo zone
. A variável de modelo é
um alias do marcador instance_id
.
A estrutura de dados de uma variável de modelo não lista os widgets aos quais em que ele se aplica. Em vez disso, você associa um widget a uma variável de modelo a modificação da consulta do widget para incluir uma referência à variável. Quando o widget é mostrado no painel, o valor da variável do modelo é resolvido.
Consulte as seções a seguir para saber como anotar painéis de registros e gráficos:
- Painel de registros
- Gráficos e tabelas definidos pelo MQL
- Gráficos e tabelas definidos pelo PromQL
- Gráficos e tabelas definidos com filtros de série temporal
Painel de registros
Para configurar um painel de registros para filtrar a exibição com base no valor de um
variável de modelo, adicione a variável ao painel de consulta. O exemplo a seguir
ilustra uma consulta que filtra pelo valor da variável de modelo iid
:
${iid}
Antes de o painel de registros consultar os registros a serem exibidos, a variável de modelo
for resolvida. Neste exemplo, se o valor da variável do modelo
for "12345"
, ${iid}
será substituído pela instrução
resource.labels."instance_id"="12345"
.
Também é possível incluir apenas o valor de uma variável de modelo em uma consulta. Recomendamos que você use o valor apenas como parte de um filtro definido com um expressão regular. Por exemplo, a consulta a seguir usa uma expressão regular para corresponder a entradas de registro que tenham um payload JSON que contenha os string:
jsonPayload.message=~"Connected to instance: ${iid.value}"
Se você configurou uma consulta para o painel de registros e selecionou o botão para abrir a Análise de registros, as variáveis de modelo são resolvidas antes a Análise de registros é aberta.
A tabela a seguir mostra como a variável de modelo é resolvida pelo painel de registros:
Sintaxe | Valor selecionado |
Expressão do painel de registros resolvida |
---|---|---|
${iid} |
12345 |
resource.labels."instance_id"="12345" |
${iid} |
* |
"" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Tabelas e gráficos definidos pela MQL
Ao usar a linguagem de consulta do Monitoring (MQL) para configurar um gráfico, anexe um pipe e a variável à string de consulta:
fetch gce_instance | metric 'compute.googleapis.com/instance/cpu/utilization' | every 1m | ${iid}
Antes de o gráfico consultar a série temporal a ser exibida, a variável do modelo
for resolvida. Neste exemplo, se o valor da variável de modelo
for "12345"
, então ${iid}
será substituído pela instrução
filter (resource.instance_id == '12345')
Esse filtro corresponde a séries
temporais com um rótulo chamado resource.instance_id
e somente quando o valor
desse rótulo é exatamente 12345
.
Quando você quiser filtrar séries temporais usando uma expressão regular, configure a consulta para incluir apenas o valor da variável do modelo.
Para ilustrar a sintaxe, o exemplo a seguir
mostra como usar uma expressão regular para determinar se o valor do
rótulo resource.instance_id
contém o valor da variável de modelo 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
A tabela a seguir mostra como a variável de modelo é resolvida para consultas MQL:
Sintaxe | Selected Value |
Expressão MQL resolvida |
---|---|---|
${iid} |
12345 |
filter (resource.instance_id == '12345') |
${iid} |
* |
filter (true) |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Gráficos e tabelas definidos por PromQL
Ao definir um gráfico com PromQL, anexe à string de consulta o variável entre chaves:
compute_googleapis_com:instance_cpu_utilization { project_id="my-project", ${iid} }
Antes de o gráfico consultar a série temporal a ser exibida, a variável de modelo
é resolvido. Neste exemplo, se o valor da variável do modelo
for "12345"
, ${iid}
será substituído pela instrução
instance_id == '12345'
.
Assim como no MQL, quando você define um widget com PromQL, a consulta
pode extrair apenas o valor da variável de modelo. Recomendamos que você
use o valor apenas como parte de um filtro definido com uma expressão regular. Para
ilustrar a sintaxe, o exemplo a seguir mostra como usar uma expressão regular para
determinar se o valor do rótulo instance_id
contém o valor da
variável de modelo iid
:
compute_googleapis_com:instance_cpu_utilization{ instance_id=~"${iid.value}" }
A tabela a seguir mostra como a variável de modelo é resolvida para o PromQL consultas:
Sintaxe | Valor selecionado |
Expressão PromQL resolvida |
---|---|---|
${iid} |
12345 |
instance_id == '12345' |
${iid} |
* |
noop_filter=~".*" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.+ |
Gráficos e tabelas definidos com filtros de série temporal
Ao definir um gráfico usando filtros de série temporal, anexe a variável à string de filtro:
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${iid}"
Ao contrário dos gráficos definidos por MQL e PromQL, não é possível usar o valor de uma variável de modelo em um filtro de série temporal.
A tabela a seguir mostra como a variável de modelo é resolvida:
Sintaxe | Valor selecionado |
Expressão de filtro resolvida |
---|---|---|
${iid} |
12345 |
resource.instance_id == "12345" |
${iid} |
* |
Omitida |
${iid.value} |
12345 |
Sem suporte |
${iid.value} |
* |
Sem suporte |
Crie um painel
Para criar um novo painel personalizado, invoque o método dashboards.create
e inclua nele o layout e os widgets a serem exibidos no painel.
Quando você cria um painel, a API gera o dashboard_id
automaticamente. Se você quiser especificar um dashboard_id
personalizado, defina o campo name
de um objeto Dashboard
. O formato do campo de nome é assim:
"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"
Protocolo
Para criar um novo painel, envie uma solicitação POST
para o endpoint 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 criar um painel em um projeto, use o comando gcloud monitoring dashboards create
.
gcloud monitoring dashboards create --config-from-file=my-dashboard.json
Por exemplo, se você quiser duplicar um painel, faça o seguinte:
- Conclua as etapas em Receber painel para fazer o download da definição de no painel original.
- Edite o JSON retornado para remover
etag
ename
e mudar o valor do campodisplayName
. - Execute o comando para criar o painel.
Para mais informações, consulte a referência de gcloud monitoring dashboards
create
.
Os exemplos criam um painel de amostra usando o arquivo my-dashboard.json
.
Você pode gerenciar seu painel por meio do
Console do Google Cloud.
Para outras configurações do painel, consulte Exemplos de painéis e layouts.
Excluir painéis
Para excluir um painel personalizado, invoque o método dashboards.delete
e especifique o painel que você quer excluir.
Protocolo
Para excluir um painel personalizado, envie uma solicitação DELETE
para o endpoint Dashboard
, qualificado com o código do painel a ser excluído.
curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}
Se for bem-sucedido, o método retornará uma resposta vazia. Caso contrário, um erro será exibido.
gcloud
Para excluir um painel personalizado, use
gcloud monitoring dashboards delete
e
especifique o ID totalmente qualificado do painel a ser excluído:
gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}
Para mais informações, consulte a referência de gcloud monitoring dashboards
delete
.
Listar painéis
Para listar todos os painéis que pertencem a um projeto, invoque o
método dashboards.list
e especifique o ID do projeto.
Protocolo
Para listar todos os painéis personalizados de um projeto, envie o código do projeto para o endpoint Dashboard
.
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards
gcloud
Para listar todos os painéis personalizados de um projeto, use o comando gcloud monitoring dashboards list
:
gcloud monitoring dashboards list
Para mais informações, consulte a referência
gcloud monitoring dashboards list
.
Os exemplos retornam os painéis personalizados associados ao seu projeto.
Paginar a resposta da lista
O método dashboards.list
suporta paginação. Com ela,
em vez de ver todos os resultados ao mesmo tempo, você os visualiza em uma página de cada vez.
Protocolo
Na página inicial da lista de resultados, especifique o parâmetro de consulta pageSize
com a solicitação:
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1
O método retorna a primeira página da lista e o nextPageToken
. Exemplo:
{ "dashboards" : [ { "displayName" : "Grid Layout Example", "gridLayout" : { "widgets" : [ { ... }, { ... }, { ... }, ] } } ] }, "nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"
Em cada página restante, você precisa incluir o nextPageToken
correspondente
na solicitação.
gcloud
Para especificar o número de recursos por página, passe a sinalização --page-size
com o comando. Exemplo:
gcloud monitoring dashboards list --page-size=1
Acessar painel
Para receber um painel personalizado específico para um projeto, invoque o método dashboards.get
, qualificado com o código do painel.
Protocolo
Para receber um painel personalizado específico, envie o código dele para o endpoint Dashboard
.
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}
O método retorna uma resposta semelhante ao exemplo a seguir:
{ "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 obter um painel personalizado específico, use o
gcloud monitoring dashboards describe
e especifique o ID do painel:
gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json
O comando retorna o painel 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 mais informações, consulte a referência gcloud monitoring dashboards describe
.
Atualizar painel
Para atualizar um painel personalizado existente, invoque o método dashboards.patch
. Para receber o valor etag
atual, invoque o método dashboards.get
, e ele estará incluído na resposta.
Protocolo
Para atualizar um painel personalizado, envie uma solicitação PATCH
para o endpoint Dashboard
e forneça o objeto Dashboard
revisado e o valor etag
da resposta dashboards.get
mais recente.
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 atualizar um painel personalizado, use
gcloud monitoring dashboards update
, especifique
o ID do painel a ser atualizado e forneça as alterações no painel.
gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json
Para mais informações, consulte a referência gcloud monitoring dashboards update
.
Os exemplos atualizam um painel personalizado existente usando o arquivo my-updated-dashboard.json
e retornam uma cópia da listagem do painel atualizada. Os dados retornados incluem um novo valor de etag
.
A seguir
- Exemplos de painéis e layouts
- Criar e gerenciar painéis personalizados com o console do Google Cloud