Criar e gerenciar painéis por API

Este documento descreve como criar e gerenciar painéis personalizados e os widgets desses painéis usando o recurso Dashboard na API Cloud Monitoring. Os exemplos aqui ilustram como gerenciar seus painéis usando curl para invocar a API e mostrar como usar a Google Cloud CLI. Embora você também possa gerenciar seus painéis personalizados por meio do o console do Google Cloud, a API oferece 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:

É 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. Você também pode adicionar marcadores e filtros ao painel. Os marcadores podem ajudar você a encontrar um painel ou indicar o tipo de conteúdo no painel.

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:

  • Widgets de gráfico e tabela:

    • XyChart: exibe dados usando os eixos X e Y. Os gráficos abaixo são instâncias do widget XyChart:

    • Gráficos de linhas

    • Gráficos de barras

    • Gráficos de área empilhada

    • Mapas de calor

    • Gráficos da Análise de dados de registros

    • Widgets de SLO, mas não há suporte para a criação de gráficos de SLO usando a API.

    Se você criar um gráfico de linhas, de barras empilhadas ou de área empilhado, é possível especificar que uma métrica se refira ao eixo Y à esquerda ou à direita. Quando vários em um gráfico, é possível usar os dois eixos Y.

    • PieChart: mostra o valor mais recente de uma métrica. em que cada série temporal contribui com uma fatia da pizza.

    • Scorecard: exibe o valor mais recente de uma métrica e como ele está relacionado a um ou mais limites.

    • TimeSeriesTable: exibe o valor mais recente de uma métrica. É possível classificar a tabela com base em colunas, filtrá-la e adicionar ou remover colunas da exibição.

  • Gráficos de políticas de alertas e widgets de incidentes:

    • 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. Você pode configure o widget para mostrar incidentes de políticas de alertas específicas ou tipos de recursos específicos.

  • Widgets de registro e erro:

  • Widgets de texto e organização:

    Para incluir esses widgets em uma painel, o painel precisa ter um MosaicLayout.

    • CollapsibleGroup: mostra uma coleção de widgets. Você pode recolher 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.

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 do painel

Os identificadores ajudam você a gerenciar e organizar seus painéis. Por exemplo, pode adicionar um rótulo chamado prod para indicar que o painel exibe dados de série temporal e de registro para seus recursos de produção. Como alternativa, adicione o rótulo playbook para indicar que o painel contém informações para ajudar você 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": ""
  }
}

Conforme ilustrado no exemplo anterior, o campo labels é implementado como uma 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 as que o painel exibe. Por exemplo, quando um painel exibe métricas para instâncias de máquina virtual (VM), convém conferir as métricas de todas VMs e talvez queira conferir as métricas de uma zona específica. Nesse tipo de situação, recomendamos que você crie um filtro permanente e defina o padrão valor desse filtro para a vista 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 exibe seus filtros permanentes e um menu que você pode usar para alterar 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 especificam 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ótulo zone. Da mesma forma, os gráficos sem o marcador zone 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 código 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 chamada 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 é exibido no painel, o valor da variável de modelo é resolvido.

Consulte as seções abaixo para saber como fazer anotações em painéis e gráficos de registros:

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 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 de modelo for "12345", então ${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 às entradas de registro que têm um payload JSON que contém as 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 Selected
Value		 Expressão do painel de registros resolvida
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

Gráficos e tabelas definidos pelo MQL

Ao usar a linguagem de consulta do Monitoring (MQL, na sigla em inglês) para configurar um gráfico, anexe um pipe e a à 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') Este filtro corresponde ao horário séries com um rótulo chamado resource.instance_id e somente quando o valor desse rótulo é exatamente 12345.

Quando você quiser filtrar série temporal usando uma expressão regular, configure a consulta para incluir apenas o valor da variável de modelo. Para ilustrar a sintaxe, a seguinte mostra como usar uma expressão regular para determinar se o valor do o 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 MQL consultas:

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 pelo 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 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 instance_id == '12345'

Assim como no MQL, ao definir um widget com o PromQL, a consulta pode extrair apenas o valor da variável de modelo. Recomendamos que você usar o valor apenas como parte de um filtro definido com uma expressão regular. Para ilustrar a sintaxe, o seguinte mostra como usar uma expressão regular para determinar se o valor do rótulo instance_id contém o valor do iid da variável de modelo:

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 Selected
Value		 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 Selected
Value		 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:

  1. Conclua as etapas em Receber painel para fazer o download da definição de do painel original.
  2. Edite o JSON retornado para remover etag e name e mudar o valor do campo displayName.
  3. 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 mais 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 código 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 de 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 receber um painel personalizado específico, use o comando gcloud monitoring dashboards describe e especifique o código 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 de 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 código 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 de 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