Crie e faça a gestão de painéis de controlo por API

Este documento descreve como pode criar e gerir painéis de controlo personalizados e os widgets nesses painéis de controlo através do recurso Dashboard na API Cloud Monitoring. Os exemplos aqui ilustram como gerir os seus painéis de controlo através de curl para invocar a API e mostram como usar a CLI Google Cloud. Embora também possa gerir os seus painéis de controlo personalizados através da Google Cloud consola, a API oferece-lhe uma forma programática de gerir vários painéis de controlo em simultâneo.

O ponto final suporta os seguintes métodos para gerir e configurar painéis de controlo:

Pode invocar a API diretamente através do utilitário curl ou da CLI Google Cloud.

Não pode obter, editar nem eliminar painéis de controlo predefinidos.

Esta funcionalidade só é suportada para projetos do Google Cloud . Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Acerca dos painéis de controlo

Quando cria um painel de controlo, tem de especificar os componentes ou os widgets que quer apresentar e o esquema desses widgets. Também pode adicionar etiquetas e filtros ao painel de controlo. As etiquetas podem ajudar a encontrar um painel de controlo ou indicar o tipo de conteúdo no painel de controlo.

Esquemas do painel de controlo

Os esquemas definem a ordem dos componentes de um painel de controlo. A API oferece os seguintes esquemas:

  • GridLayout: divide o espaço disponível em colunas verticais de largura igual e organiza um conjunto de widgets usando uma estratégia de prioridade às linhas.

  • MosaicLayout: divide o espaço disponível numa grelha. Cada widget pode ocupar um ou mais blocos da grelha.

  • RowLayout: divide o espaço disponível em linhas e organiza um conjunto de widgets horizontalmente em cada linha.

  • ColumnLayout: divide o espaço disponível em colunas verticais e organiza um conjunto de widgets verticalmente em cada coluna.

Por exemplo, o seguinte mostra a representação JSON de um painel de controlo 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 de controlo

Um widget contém um único componente do painel de controlo e a configuração de como apresentar o componente no painel de controlo. Um painel de controlo pode ter mais do que um widget. Existem vários tipos de Widgetobjetos:

  • O widget XyChart apresenta dados nos eixos X e Y.

    Este widget apresenta um conjunto de dados que pode ser dados de séries cronológicas ou gerado por uma consulta SQL. Este widget permite-lhe associar os dados representados no gráfico ao eixo Y esquerdo ou direito. Quando são representados vários tipos de métricas, pode usar ambos os eixos Y. O widget XyChart suporta os seguintes estilos de apresentação:

    • Gráficos de linhas
    • Gráficos de barras
    • Gráficos de áreas sobrepostas
    • Mapas térmicos

  • Widgets que apresentam dados de uma dimensão, como o valor mais recente:

    • PieChart: apresenta os valores mais recentes de uma coleção de séries cronológicas, em que cada série cronológica contribui com uma fatia para o gráfico circular.

    • Scorecard: apresenta o valor mais recente de uma série cronológica e a relação deste valor com um ou mais limites.

    • TimeSeriesTable: apresenta o valor mais recente ou um valor agregado para cada série cronológica. As tabelas suportam a personalização. Por exemplo, pode atribuir um código de cores às células e configurar os nomes das colunas e o alinhamento dos dados.

  • Widgets que apresentam informações sobre políticas de alerta ou incidentes:

    • AlertChart: apresenta um resumo de uma política de alerta de condição única. Este widget apresenta os dados como um gráfico de linhas, mostra o limite e indica o número de incidentes abertos.

    • IncidentList: apresenta uma lista de incidentes. Pode configurar o widget para mostrar incidentes para políticas de alerta específicas ou para tipos de recursos específicos.

  • Widgets que apresentam entradas do registo e erros:

  • Widgets de texto e organização:

    • CollapsibleGroup: apresenta uma coleção de widgets. Pode reduzir a vista de um grupo.

    • SingleViewGroup: apresenta um widget numa coleção de widgets. Pode selecionar o widget a apresentar.

    • SectionHeader: cria um separador horizontal no painel de controlo e cria uma entrada na tabela de conteúdos do painel de controlo.

    • Text: apresenta conteúdo textual, como texto não processado ou uma string Markdown.

    Para incluir os widgets de texto e organização num painel de controlo, o painel de controlo tem de ter um MosaicLayout.

Além destes objetos, também pode adicionar um marcador de posição em branco a um painel de controlo.

Por exemplo, o seguinte mostra a representação JSON de um widget XyChart cujo eixo Y direito 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 do painel de controlo

As etiquetas podem ajudar a gerir e organizar os painéis de controlo. Por exemplo, pode adicionar uma etiqueta com o nome prod para indicar que o painel de controlo apresenta dados de séries cronológicas e dados de registo para os seus recursos de produção. Em alternativa, pode adicionar a etiqueta playbook para indicar que o painel de controlo contém informações para ajudar a resolver problemas de falhas.

A adição de etiquetas a um painel de controlo é opcional.

Por exemplo, o seguinte mostra um objeto Dashboard que especifica a etiqueta denominada playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Conforme ilustrado no exemplo anterior, o campo labels é implementado como um map, em que os campos key e value são ambos strings. Quando adiciona uma etiqueta a um painel de controlo, defina o elemento key com o nome da etiqueta e defina o campo value como uma string vazia.

Filtros e variáveis do painel de controlo

Quando cria um painel de controlo, pode identificar várias formas de ver os dados que o painel de controlo apresenta. Por exemplo, suponhamos que um painel de controlo apresenta dados de séries cronológicas para as suas instâncias de máquinas virtuais (VMs). Pode querer ver os dados de séries cronológicas para todas as VMs e ver apenas os dados que estão numa zona específica. Nesta situação, recomendamos que crie um filtro fixo ou uma variável e, em seguida, defina o valor predefinido desse filtro para a zona mais vista.

Os filtros fixos aplicam-se a todos os widgets do painel de controlo que suportam a etiqueta especificada no filtro, a menos que o widget contenha um filtro com essa mesma chave de etiqueta. Por exemplo, quando um gráfico inclui o filtro zone = us-central1-a, esse gráfico ignora um filtro fixo cuja chave de etiqueta é zone. Da mesma forma, este filtro é ignorado pelos gráficos que não têm uma etiqueta com uma chave de zone.

As variáveis são como filtros fixos, mas aplicam-se apenas a widgets específicos. As variáveis podem basear-se em etiquetas, como os filtros fixados, ou podem ter apenas um valor. As variáveis apenas com valores contêm um ou mais valores predefinidos e uma lista de todos os valores possíveis. Se não especificar um valor predefinido, a predefinição é o operador universal (*). Para definir o conjunto de todos os valores possíveis, fornece uma matriz de valores ou escreve uma consulta SQL.

Para widgets que consultam dados, pode incluir uma variável na consulta do widget e usar uma variável para controlar a visibilidade do widget. Quando a consulta depende de uma variável, os dados pedidos pelo widget mudam quando altera o valor da variável. Consequentemente, os dados apresentados também mudam. Quando usa uma variável para controlar a visibilidade de um widget, é apresentado um ícone Visível na barra de ferramentas. Para restrições relacionadas com a visibilidade, consulte o artigo Defina a visibilidade de um widget.

Tanto para os filtros fixados como para as variáveis, a barra de ferramentas do painel de controlo apresenta cada variável, juntamente com um menu, que lhe permite alterar temporariamente o valor da variável. A mesma estrutura de dados é usada para representar filtros fixados e variáveis. Para ajudar a distinguir os filtros das variáveis, na barra de ferramentas do painel de controlo, o nome de uma variável tem um cifrão $ antes. Para mais informações, consulte DashboardFilter.

Para ver um exemplo que mostra como pode controlar a visibilidade do widget através de uma variável, consulte Painel de controlo com a visibilidade do widget configurada.

Para saber como atualizar a consulta de um widget com uma variável baseada em etiqueta ou uma variável apenas com valor, consulte as seguintes secções:

Crie filtros e variáveis

Consola

Para obter informações sobre como usar a Google Cloud consola para criar filtros fixos e variáveis, consulte os seguintes documentos:

API

Para definir filtros e variáveis fixos, use a estrutura de dados dashboardFilters.

  • Para criar uma variável, defina o valor do campo templateVariable para o nome da variável. Omita este campo ou defina o valor como uma string vazia quando quiser criar um filtro fixo.
  • Para criar um filtro fixo ou uma variável baseada em etiquetas, tem de especificar o campo labelKey. Omita este campo quando quiser uma variável apenas com valor.

  • Defina o valor predefinido para o filtro ou a variável. A configuração deste campo determina se um utilizador pode selecionar exatamente uma opção no menu de valores ou se pode selecionar vários valores.

    • Para definir um único valor predefinido e restringir os utilizadores à seleção de exatamente uma opção no menu de valores, defina o campo valueType como STRING e também defina o campo stringValue:
    "valueType": "STRING",
"stringValue": "my-default-value",
    • Para definir, pelo menos, um valor predefinido e permitir que os utilizadores selecionem várias opções no menu de valores, defina o campo valueType como STRING_ARRAY e defina também o campo stringArrayValue. No exemplo seguinte, existem três valores predefinidos.
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Opcional: para especificar a lista de todos os valores possíveis para uma variável apenas de valor, defina o campo stringArray ou o campo timeSeriesQuery. Se especificar uma consulta, tem de ser uma consulta de estatísticas.

Por exemplo, considere o seguinte objeto dashboardFilters:

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

O JSON anterior define um filtro fixo e duas variáveis:

  • O filtro fixo tem a chave da etiqueta zone, que é apresentada na barra de ferramentas. Os campos valueType e stringValue especificam o valor predefinido único. Para mais informações, consulte a página de referências da API para a estrutura de dados dashboardFilters.

  • A variável baseada em etiquetas tem o nome my_label_based_variable e a respetiva chave de etiqueta é instance_id. O valor predefinido desta variável está definido como um ID de instância específico. Também pode configurar o valor predefinido através de uma matriz. Na barra de ferramentas, o filtro é apresentado com o nome my_label_based_variable.

  • A variável apenas com valor tem o nome my_value_only_variable. Esta entrada não especifica um valor predefinido, pelo que o operador universal, (*), é aplicado automaticamente. Além disso, esta variável usa uma consulta SQL para gerar a lista de valores possíveis para a variável.

Tenha em atenção que o objeto dashboardFilters não apresenta os widgets aos quais a variável se aplica. Em alternativa, atualize a consulta de um widget para depender de uma variável.

Sintaxe geral para desreferenciar uma variável

Para todos os widgets, exceto os definidos por SQL, use a seguinte sintaxe para aplicar uma variável a uma consulta:

  • Para aplicar uma variável baseada em etiquetas e ter a chave da etiqueta e o valor da etiqueta resolvidos numa expressão de filtro válida para a linguagem de consulta, use ${my_label_based_variable}.

  • Para aplicar apenas o valor de uma variável baseada em etiquetas, use ${my_label_based_variable.value}. A comparação tem de usar uma expressão regular.

  • Para aplicar apenas o valor de uma variável apenas de valor, use ${my_value_only_variable}. Para variáveis apenas com valores, não inclua uma cláusula .value. A comparação tem de usar uma expressão regular.

Widgets do painel de registos

Para aplicar uma variável a um widget do painel Registos, atualize o painel de consultas. A sintaxe destes widgets segue a especificada em Sintaxe geral.

Consola

Por exemplo, a seguinte consulta usa uma expressão regular para comparar o valor do campo jsonPayload.message com um valor de string que inclui o valor de uma variável baseada em etiquetas:

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

Como outro exemplo, considere uma variável apenas com valores, value_only_severity_variable, e suponha que, no menu de valores, estão selecionados três valores: ERROR, INFO e NOTICE. Em seguida, adicione o seguinte ao painel de consultas do widget do painel de registos:

severity =~ "${value_only_severity_variable}"

A imagem seguinte ilustra o formulário renderizado:

severity =~ "^(ERROR|INFO|NOTICE)$"

API

Por exemplo, o JSON seguinte ilustra como atualizar a consulta de um widget do painel de registos com uma variável baseada em etiquetas:

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

Por exemplo, a seguinte consulta usa uma expressão regular para comparar o valor do campo jsonPayload.message com um valor de string que inclui o valor de uma variável baseada em etiquetas:

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

Como outro exemplo, considere uma variável apenas com valor, value_only_severity_variable, e suponha que são selecionados três valores no menu: ERROR, INFO e NOTICE. Em seguida, adicione o seguinte ao painel de consultas do widget do painel de registos:

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

A imagem seguinte ilustra a consulta conforme executada pelo widget do painel de registos:

severity =~ "^(ERROR|INFO|NOTICE)$"

Se tiver configurado uma consulta para o painel de registos e, em seguida, selecionar o botão para abrir o Explorador de registos, as variáveis são resolvidas antes de o Explorador de registos ser aberto.

A tabela seguinte ilustra como as variáveis de exemplo são resolvidas pelo painel de registos. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão do painel de registos resolvida
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

A variável de exemplo baseia-se na etiqueta do recurso instance_id.
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Gráficos com consultas PromQL

Para atualizar um gráfico que tenha uma consulta PromQL para depender de uma variável baseada em etiquetas, siga as orientações indicadas em Sintaxe geral.

Consola

Por exemplo, a seguinte consulta baseia-se na variável baseada em etiquetas my_label_based_variable, que é resolvida numa expressão de filtro:

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

Também pode modificar a consulta para resolver apenas o valor de uma variável. O exemplo seguinte usa uma expressão regular para comparar o valor de uma consulta baseada em etiquetas com instance_id:

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

Se tiver uma variável apenas com valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável apenas com valor, a consulta incluiria algo como o seguinte:

zone=~"${my_value_only_variable}"

API

Por exemplo, o JSON seguinte ilustra uma consulta que depende da variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa expressão de filtro:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Também pode modificar a consulta para resolver apenas o valor de uma variável. O exemplo seguinte usa uma expressão regular para comparar o valor de uma consulta baseada em etiquetas com instance_id:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Se tiver uma variável apenas com valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável apenas com valor, a consulta incluiria algo como o seguinte:

zone=~\"${my_value_only_variable}\"

A tabela seguinte ilustra como as variáveis de exemplo são resolvidas pelo PromQL. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão PromQL resolvida
${my_label_based_variable} 12345 instance_id == '12345'

A variável de exemplo baseia-se na etiqueta do recurso instance_id.
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

Gráficos com consultas SQL

Quando quiser atualizar um widget definido por SQL para depender de uma variável, atualize a cláusula WHERE para referenciar o valor da variável. Para todas as variáveis, adicione o símbolo "@" antes do nome da variável, por exemplo: @variable_name. Para variáveis baseadas em etiquetas, acrescente .value ao nome da variável, @my_label_based_variabe.value.

Para consultas SQL, a substituição de variáveis baseia-se no BigQuery e é segura contra injeção de SQL. Para mais informações, consulte o artigo Executar consultas parametrizadas.

Consola

Uma vez que o SQL não interpreta o operador de carateres universais como "qualquer valor", recomendamos que use sempre uma declaração IF quando usar variáveis numa consulta SQL. O exemplo seguinte ilustra a utilização de uma variável apenas de valor cujo tipo de dados é uma string:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Quando a opção de menu da variável permite aos utilizadores selecionar vários valores, tem de converter o valor da variável num tipo de dados GoogleSQL através da função CAST. A seguinte consulta ilustra esta sintaxe:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

A declaração IF apresentada nos exemplos anteriores é recomendada porque o SQL não interpreta o operador de carateres universais como "qualquer valor". Por conseguinte, se omitir a declaração IF e selecionar o operador de carateres universais, o resultado da consulta é uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz numa tabela.

Para adicionar uma cláusula WHERE formatada corretamente, faça o seguinte:

  1. Edite o widget.
  2. Na barra de ferramentas, selecione Inserir filtro de variável e, de seguida, selecione a variável cuja cláusula WHERE quer atualizar.
  3. Na caixa de diálogo apresentada, reveja o código gerado e, de seguida, clique em Copiar e fechar.

  4. Cole o código copiado no painel Consulta e faça as edições necessárias.

    Por exemplo, suponhamos que cria uma variável denominada LogName que gera uma lista de nomes de registos e produz o resultado numa tabela com uma única coluna denominada log_name. Em seguida, cria um gráfico, seleciona Inserir filtro de variável e, de seguida, seleciona a variável LogName. É gerado o seguinte código:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    Neste exemplo, tem de editar o código gerado e substituir LogName = por log_name = para que a junção de tabelas possa ocorrer:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Clique em Executar e, de seguida, em Aplicar.

  6. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

API

Uma vez que o SQL não interpreta o operador de carateres universais como "qualquer valor", recomendamos que use sempre uma declaração IF quando usar variáveis numa consulta SQL. O exemplo seguinte ilustra a utilização de uma variável apenas de valor cujo tipo de dados é uma string:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Por exemplo, o seguinte mostra uma representação JSON parcial de um gráfico que apresenta os resultados de uma consulta SQL. Para suportar a filtragem dos resultados pelo nome de um registo, foi adicionada uma cláusula WHERE que faz referência à variável denominada LogName:

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

A variável LogName também envia uma consulta para determinar a lista de nomes de registos possíveis:

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

Quando a opção de menu da variável permite aos utilizadores selecionar vários valores, tem de converter o valor da variável num tipo de dados GoogleSQL através da função CAST. A seguinte consulta ilustra esta sintaxe:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

A declaração IF apresentada nos exemplos anteriores é recomendada porque o SQL não interpreta o operador de carateres universais como "qualquer valor". Por conseguinte, se omitir a declaração IF e selecionar o operador de carateres universais, o resultado da consulta é uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz numa tabela.

Gráficos com consultas de filtros de monitorização

Para atualizar um gráfico que tenha uma consulta sob a forma de um filtro de monitorização para depender de uma variável baseada em etiquetas, siga as orientações indicadas na secção Sintaxe geral.

Consola

Se usar a Google Cloud consola para criar os gráficos e usar a interface orientada por menus, pode atualizar a consulta do gráfico usando o campo Aplicar a gráficos da variável ou editando o widget e selecionando a variável baseada em etiquetas no menu Filtro. O menu Filtro apresenta todas as variáveis baseadas em etiquetas e todas as chaves de etiquetas.

Para atualizar a consulta de um gráfico de modo a depender de uma variável baseada em valor, faça o seguinte:

  1. Edite o gráfico.
  2. No painel de consulta, clique em Adicionar filtro e selecione uma chave de etiqueta. Por exemplo, pode selecionar zona.
  3. No menu Valor, selecione a variável apenas de valor.
  4. Clique em Aplicar.
  5. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

Por exemplo, o JSON seguinte ilustra uma consulta que depende de uma variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa expressão de filtro:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Os widgets que usam uma consulta sob a forma de um filtro de monitorização não podem filtrar a série cronológica pelo valor numa variável baseada em etiquetas; no entanto, pode filtrar por variáveis apenas de valor. Por exemplo, a consulta seguinte mostra o valor do campo Filtros de uma consulta que filtra por zone, com base no valor de uma variável apenas de valor:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

API

Por exemplo, o JSON seguinte ilustra uma consulta que depende de uma variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa expressão de filtro:

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Os widgets que usam uma consulta sob a forma de um filtro de monitorização não podem filtrar a série cronológica pelo valor numa variável baseada em etiquetas; no entanto, pode filtrar por variáveis apenas de valor. Por exemplo, a seguinte consulta mostra o campo "filter" de uma consulta que filtra por zone, com base no valor de uma variável apenas de valor:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

A tabela seguinte ilustra como as variáveis de exemplo são resolvidas pelo filtro de monitorização. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão de filtro resolvida
${my_label_based_variable} 12345 resource.instance_id == "12345"

A variável de exemplo baseia-se na etiqueta do recurso instance_id.
${my_label_based_variable} * Omitido
${my_label_based_variable.value} 12345 Não suportado
${my_label_based_variable.value} * Não suportado
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Antes de começar

Conclua o seguinte no Google Cloud projeto onde quer criar ou gerir painéis de controlo:

  • Select the tab for how you plan to use the samples on this page:

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    Terraform

    Para usar os exemplos do Terraform nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Configure o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

Crie um painel de controlo

Para criar um novo painel de controlo personalizado, invoque o método dashboards.create e faculte-lhe o esquema e os widgets a apresentar no painel de controlo.

O campo name é opcional. O valor do campo de nome tem a seguinte estrutura:

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

Quando cria um painel de controlo, a API gera automaticamente o componente DASHBOARD_ID. Se quiser especificar um valor personalizado DASHBOARD_ID, pode especificar o campo name do objeto Dashboard.

gcloud

Para criar um painel de controlo num projeto, use o comando gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Por exemplo, se quiser duplicar um painel de controlo, faça o seguinte:

  1. Conclua os passos em Obter painel de controlo para transferir a definição do painel de controlo original.
  2. Edite o JSON devolvido para remover os campos etag e name e alterar o valor do campo displayName.
  3. Execute o comando para criar o painel de controlo.

Para mais informações, consulte a referência gcloud monitoring dashboards create.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform. Para mais informações, consulte a Terraform documentação de referência do fornecedor.

Para criar um painel de controlo com o Terraform, faça o seguinte:

  1. Instale e configure o Terraform para o seu projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

  2. Use o recurso do Terraform google_monitoring_dashboard.

    No comando, defina os seguintes campos:

    • dashboard_json: a representação JSON do painel de controlo, usando o formato Dashboards.

      Para ver exemplos deste formato, pode listar os painéis de controlo através do Explorador de APIs ou abrir um painel de controlo na Google Cloud consola e ver as representações JSON.

    • parent: o nome totalmente qualificado do seu projeto. Por exemplo, pode definir este campo como "projects/PROJECT_ID", onde PROJECT_ID é o ID do seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

REST

Para criar um novo painel de controlo, envie um pedido POST para o ponto final 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

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Os exemplos criam um painel de controlo de amostra através do ficheiro my-dashboard.json. Pode gerir o seu painel de controlo através da Google Cloud consola.

Para configurações adicionais do painel de controlo, consulte o artigo Exemplos de painéis de controlo e esquemas.

Elimine painéis de controlo

Para eliminar um painel de controlo personalizado, invoque o método dashboards.delete e especifique o painel de controlo que quer eliminar.

gcloud

Para eliminar um painel de controlo personalizado, use gcloud monitoring dashboards delete e especifique o ID totalmente qualificado do painel de controlo a eliminar:

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • DASHBOARD_ID: o ID do painel de controlo.

Para mais informações, consulte a referência gcloud monitoring dashboards delete.

Terraform

Pode eliminar recursos através do Terraform. Para obter informações sobre como eliminar recursos, consulte o comando destroy do Terraform.

REST

Para eliminar um painel de controlo personalizado, envie um pedido DELETE para o ponto final Dashboard, qualificado com o ID do painel de controlo a eliminar.

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

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • ${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel de controlo.

Se for bem-sucedido, o método devolve uma resposta vazia. Caso contrário, devolve um erro.

Listar painéis de controlo

Para listar todos os painéis de controlo personalizados que pertencem a um projeto, invoque o método dashboards.list e especifique o ID do projeto.

gcloud

Para apresentar uma lista de todos os painéis de controlo personalizados de um projeto, use o comando gcloud monitoring dashboards list:

gcloud monitoring dashboards list --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Para mais informações, consulte a gcloud monitoring dashboards list referência.

Terraform

Não pode usar o Terraform para enviar uma consulta ao seu projeto com a resposta a ser uma lista de painéis de controlo. No entanto, pode ver estes painéis de controlo através da Google Cloud consola.

REST

Para listar todos os painéis de controlo personalizados de um projeto, envie o ID do projeto para o ponto final Dashboard.

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

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Os exemplos devolvem os painéis de controlo personalizados associados ao seu projeto.

Paginar a resposta da lista

O método dashboards.list suporta a paginação, o que lhe permite obter os resultados uma página de cada vez, em vez de todos de uma só vez.

gcloud

Para especificar o número de recursos por página, transmita a flag --page-size com o comando. Por exemplo:

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Terraform

Não pode usar o Terraform para enviar uma consulta ao seu projeto com a resposta a ser uma lista paginada de painéis de controlo. No entanto, pode ver estes painéis de controlo através da Google Cloud consola.

REST

Para a página inicial da lista de resultados, especifique o parâmetro de consulta pageSize com o pedido:

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

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

O método devolve a primeira página da lista e o nextPageToken. Por exemplo:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Para cada página restante, tem de incluir o nextPageToken correspondente no pedido.

Aceda ao painel de controlo

Para obter um painel de controlo personalizado específico para um projeto, invoque o método dashboards.get, qualificado com o ID do painel de controlo.

gcloud

Para obter um painel de controlo personalizado específico, use o comando gcloud monitoring dashboards describe e especifique o ID do painel de controlo:

gcloud monitoring dashboards describe DASHBOARD_ID --format=json --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • DASHBOARD_ID: o ID do painel de controlo.

O comando devolve o painel de controlo pedido:

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

Terraform

Não pode usar o Terraform para enviar uma consulta ao seu projeto com a resposta a ser um painel de controlo individual. No entanto, pode ver estes painéis de controlo através da Google Cloud consola.

REST

Para obter um painel de controlo personalizado específico, envie o ID do painel de controlo para o ponto final Dashboard.

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

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • ${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel de controlo.

Na expressão anterior, ${DASHBOARD_ID} é uma variável de ambiente que armazena o nome totalmente qualificado do painel de controlo.

O método devolve uma resposta semelhante ao seguinte exemplo:

{
  "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"
}

Atualizar painel de controlo

Para atualizar um painel de controlo personalizado existente, invoque o método dashboards.patch. Para obter o valor atual, pode invocar o método dashboards.get e encontrá-lo na resposta.etag

gcloud

Para atualizar um painel de controlo personalizado, use gcloud monitoring dashboards update, especifique o ID do painel de controlo a atualizar e faculte as alterações ao painel de controlo.

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • DASHBOARD_ID: o ID do painel de controlo.

Para mais informações, consulte a referência gcloud monitoring dashboards update.

O exemplo anterior atualiza um painel de controlo personalizado existente através do ficheiro my-updated-dashboard.json. A resposta, que inclui um novo valor etag, é uma cópia da ficha do painel de controlo atualizada.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform. Para mais informações, consulte a Terraform documentação de referência do fornecedor.

Para atualizar um painel de controlo através do Terraform, faça o seguinte:

  1. Instale e configure o Terraform para o seu projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

  2. Use o recurso do Terraform google_monitoring_dashboard.

    No comando, defina os seguintes campos:

    • dashboard_json: a representação JSON do painel de controlo, usando o formato Dashboards.

    • parent: o nome totalmente qualificado do seu projeto. Por exemplo, pode definir este campo como "projects/PROJECT_ID", onde PROJECT_ID é o ID do seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

REST

Para atualizar um painel de controlo personalizado, envie um pedido PATCH para o ponto final Dashboard e forneça o objeto Dashboard revisto 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}

Antes de executar o comando anterior, configure o seguinte:

  • ${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto no qual criar o painel de controlo. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
  • ${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel de controlo.

O exemplo anterior atualiza um painel de controlo personalizado existente através do ficheiro my-updated-dashboard.json. A resposta, que inclui um novo valor etag, é uma cópia da ficha do painel de controlo atualizada.

O que se segue?