Gerenciar painéis por API

Nesta página, descrevemos como gerenciar painéis personalizados e os widgets nesses painéis usando o recurso Dashboard na API Cloud Monitoring. Também é possível gerenciar os painéis personalizados por meio do Console do Google Cloud. No entanto, a API oferece uma maneira programática de gerenciar vários painéis ao mesmo tempo. Também é possível criar, configurar e manipular widgets do painel usando a API Cloud Monitoring.

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 ferramenta de linha de comando gcloud.

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

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.

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á três tipos de objetos Widget:

  • XyChart: exibe dados usando os eixos X e Y. Gráficos de linhas, de barras, de áreas empilhadas e de mapas de calor criados por meio do Console do Google Cloud são instâncias desse widget. Se você criar um gráfico de linhas, um gráfico de barras empilhadas ou um gráfico de área empilhado, será 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.

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

  • Text: exibe o conteúdo textual como texto bruto ou string do Markdown.

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

Além desses objetos, é possível adicionar um marcador vazio a um painel.

Por exemplo, 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"
          }
        }
      }
    ]
  }
}

Especificar os dados a serem 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 os widgets de painel por meio do Console do Google Cloud, então já está familiarizado com as métricas e as séries temporais.

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

Além disso, você pode encontrar os guias Criar e gerenciar widgets do painel, Selecionar dados ao gráfico e Definir opções de visualização úteis. Esses guias foram escritos 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.

Exemplos usando o curl

Nesta seção, descrevemos as convenções e as configurações usadas para invocar a API Cloud Monitoring usando a ferramenta curl. Com os exemplos desta página, você acessa 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. Autenticar no SDK do Cloud:

    gcloud auth login
    
  3. Como opção, evite especificar o código do projeto com cada comando definindo-o como padrão usando o SDK do Cloud:

    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.

Invoque 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. Você também pode ter que especificar outros argumentos, por exemplo, para especificar o tipo de 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

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 por meio do 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 personalizados 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 é compatível com a paginação, que permite usar os resultados de uma página por vez em vez de todos de uma 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"

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