Gerenciar painéis por API

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Neste documento, descrevemos como criar e gerenciar painéis personalizados e 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 Google Cloud CLI. Também é possível gerenciar seus painéis personalizados usando o Console do Google Cloud, mas 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:

É possível invocar a API diretamente usando o utilitário curl ou a Google Cloud CLI.

Não é possível recuperar, editar ou excluir painéis predefinidos.

Antes de começar

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 filtros permanentes ao 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:

  • XyChart: exibe dados usando os eixos X e Y. Os gráficos de linhas, de barras, de área empilhada e de mapa de calor criados por meio do console do Google Cloud são instâncias desse widget. 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árias métricas são representadas no gráfico, é possível usar os dois eixos Y.

    Os gráficos de SLO também são instâncias do widget XyChart, mas não é possível criar gráficos de SLO usando a API.

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

  • CollapsibleGroup: exibe uma coleção de widgets. Você pode recolher a visualização de um grupo. Para incluir esses widgets, o painel precisa ter um MosaicLayout.

  • IncidentList: exibe uma lista de incidentes. É possível configurar o widget para mostrar incidentes de políticas de alertas específicas ou de tipos de recursos específicos.

  • 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 Cloud acessíveis por meio do escopo de métricas atual.

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

  • 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"
          }
        }
      }
    ]
  }
}

Filtros do painel

Ao projetar um painel, você pode identificar várias maneiras de visualizar os dados exibidos pelo painel. Por exemplo, quando um painel exibe métricas de instâncias de máquina virtual (VM), talvez você queira ver métricas para todas as VMs e uma zona específica. Nesse caso, recomendamos criar um filtro permanente e definir o valor padrão dele como a vista mais usada. Os filtros permanentes podem ser aplicados 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 pode ser usado para alterar temporariamente o valor do filtro.

Há vários tipos de filtros de painel permanentes:

  • Os filtros de todo o painel se aplicam a todos os widgets de um painel compatíveis com o rótulo e não especificam um valor para esse rótulo.

    Por exemplo, quando um gráfico inclui o filtro zone = us-central1-a, ele ignora um filtro do painel com base no rótulo zone. Da mesma forma, gráficos sem um rótulo zone ignoram os filtros do painel com esse rótulo.

  • As variáveis de modelo são variáveis nomeadas que se aplicam a widgets específicos. Cada variável representa um rótulo e um valor específicos. Você determina a quais widgets 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.

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:

{
  "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",
  ...

No JSON exibido, a primeira entrada na estrutura dashboardFilters é para uma variável de modelo com o nome my_zone_temp_var. A segunda entrada é para um filtro em todo o painel. Para esses filtros, que se aplicam a todos os widgets de painel, o valor do campo templateVariable é definido como uma string de comprimento zero, "".

A estrutura de dados de uma variável de modelo não lista os widgets a que ela se aplica. Em vez disso, quando você associa um widget a uma variável de modelo, a consulta do widget é modificada para incluir uma referência à variável. Ao usar a linguagem de consulta do Monitoring (MQL, na sigla em inglês) para configurar um gráfico, anexe um pipeline e a variável à string de consulta:


"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n|
           every 1m\n| ${my_zone_temp_var}\n"

Ao definir um gráfico usando o PromQL, anexe à string de consulta a variável encapsulada por chaves:

"prometheusQuery" :
  "compute_googleapis_com:instance_cpu_utilization {project_id=\"my-project\", ${my_zone_temp_var}}\n"

O exemplo anterior ilustra como filtrar um widget definido pelo PromQL para exibir apenas a série temporal que está no projeto do Google Cloud my-project e que correspondem a uma variável de modelo.

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\" ${my_zone_temp_var}"

As ilustrações a seguir de JSON mostram as strings de consulta no contexto da definição completa do 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
      }
    ]
  }
}

Especificar os dados que serão exibidos

Qualquer widget que exiba dados recuperados de uma série temporal tem um objeto TimeSeriesQuery incorporado a ele. Este objeto especifica os dados de série temporal a serem usados no widget.

Você pode especificar os dados de série temporal a serem exibidos da seguinte maneira:

Se você criou seus widgets de painel por meio do console do Google Cloud, já está familiarizado com as métricas e séries temporais.

Para informações sobre métricas e séries temporais, consulte Métricas, séries temporais e recursos.

Os seguintes guias também podem ser úteis:

Esses guias são criados para criar painéis usando o Console do Google Cloud, mas os conceitos também se aplicam à criação de widgets usando a API Cloud Monitoring.

Configurar para ver exemplos

Nesta seção, descrevemos as convenções e as configurações usadas para invocar a API Cloud Monitoring usando a ferramenta curl. Os exemplos neste documento acessam a API usando a ferramenta curl para enviar solicitações HTTP a endpoints REST. Para definir as variáveis usadas nas invocações de exemplo, use as informações a seguir.

Authentication

  1. Crie uma variável de ambiente para manter o ID do projeto do Google Cloud. Nestes exemplos, PROJECT_ID é utilizado:

    PROJECT_ID=a-gcp-project-12345

  2. Autentique-se na Google Cloud CLI:

    gcloud auth login

  3. Como alternativa, é possível evitar a necessidade de especificar o ID do projeto com cada comando definindo-o como padrão usando a CLI gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crie um token de autorização e colete-o em uma variável de ambiente. Nestes exemplos, a variável ACCESS_TOKEN é chamada:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    É necessário atualizar o token de acesso periodicamente. Se os comandos que funcionaram informarem de repente que você não está autenticado, reenvie este comando.

  5. Para verificar se você recebeu um token de acesso, faça o echo da variável ACCESS_TOKEN:

    echo ${ACCESS_TOKEN}
ya29.ImW8Bz56I04cN4qj6LF....

  6. Crie uma variável de ambiente para armazenar o ID do seu painel. Nestes exemplos, usamos a variável DASHBOARD_ID.

Invocar curl

Cada invocação curl inclui um conjunto de argumentos, seguido pelo URL de um recurso. Os argumentos comuns incluem valores especificados pelas variáveis de ambiente PROJECT_ID, DASHBOARD_ID e ACCESS_TOKEN. Talvez também seja necessário especificar outros argumentos, por exemplo, para especificar o tipo a solicitação HTTP (por exemplo, -X DELETE).

Cada invocação do curl tem esta estrutura geral:

curl -H "Authorization: Bearer $ACCESS_TOKEN" <other_args> https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/<request>

Por exemplo, para listar todos os painéis personalizados no seu projeto, emita a seguinte solicitação:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Veja a seguir a resposta desse comando para um projeto do 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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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 Instalar o painel para fazer o download da definição do painel original.
  2. Edite o JSON retornado para remover os campos etag e name e altere 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. Agora é possível gerenciar seu painel pelo console do Google Cloud.

Para outras configurações do painel, consulte Amostra 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. Por 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