O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar e gerenciar painéis por API

O recurso Dashboard na API Cloud Monitoring permite criar e gerenciar de maneira programática painéis personalizados e os widgets deles em grande escala. É possível gerenciar painéis personalizados usando a Google Cloud CLI, o Terraform ou chamadas REST para os métodos create, list, get, patch e delete.

Não é possível recuperar, editar ou excluir painéis predefinidos usando a API. Para saber como criar e gerenciar painéis personalizados usando o console do Google Cloud , consulte Criar e gerenciar painéis personalizados.

Sobre os painéis

Ao criar um painel, você precisa especificar quais componentes ou widgets serão exibidos e qual será o layout desses widgets. Também é possível adicionar rótulos e filtros ao painel. Os rótulos podem ajudar você a encontrar um painel ou indicar o tipo de conteúdo nele.

Layouts de painel

Os layouts definem como os componentes de um painel são ordenados. A API fornece os seguintes layouts:

GridLayout: divide o espaço disponível em colunas verticais com larguras iguais e organiza um conjunto de widgets usando uma estratégia de linha primeiro.
MosaicLayout: divide o espaço disponível em uma grade. Cada widget pode ocupar um ou mais blocos de grade.
RowLayout: divide o espaço disponível em linhas e organiza um conjunto de widgets na horizontal em cada uma delas.
ColumnLayout: divide o espaço disponível em colunas verticais e organiza um conjunto de widgets na vertical em cada uma delas.

Por exemplo, veja a seguir a representação JSON de um painel em RowLayout com três widgets Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widgets do painel

Um widget inclui um único componente de painel, além da configuração de como ele será apresentado nesse painel. Um painel pode ter mais de um widget. Há vários tipos de objetos Widget:

XyChart: exibe dados nos eixos X e Y.

Esse widget mostra um conjunto de dados que pode ser de série temporal ou gerado por uma consulta SQL. Esse widget permite associar os dados do gráfico ao eixo Y esquerdo ou direito. Quando vários tipos de métricas são mostrados no gráfico, é possível usar os dois eixos Y. O widget XyChart é compatível com os seguintes estilos de exibição:
- Gráficos de linhas
- Gráficos de barras
- Gráficos de área empilhada
- Mapas de calor
É possível especificar o período para os widgets XyChart. Essa configuração substitui a configuração no nível do painel. Configure a substituição do período de um gráfico quando quiser que ele mostre dados de um período mais longo ou mais curto do que o adequado para outros widgets do painel. Para ver um exemplo, consulte Painel com um widget XyChart que define uma substituição de período.
Widgets que mostram uma dimensão, como o valor mais recente:
- PieChart: exibe os valores mais recentes de uma coleção de séries temporais, em que cada série temporal contribui com uma fatia para o gráfico de pizza.
- Scorecard: exibe o valor mais recente de uma série temporal e como esse valor se relaciona com um ou mais limites.
- TimeSeriesTable: exibe o valor mais recente ou um valor agregado para cada série temporal. As tabelas podem ser personalizadas. Por exemplo, é possível codificar as células por cores e configurar nomes de colunas e alinhamento de dados.
Widgets que mostram informações sobre política de alertas ou alertas:
- AlertChart: exibe um resumo de uma política de alertas de condição única. Esse widget exibe dados como um gráfico de linhas, mostra o limite e lista o número de alertas abertos.
- IncidentList: mostra uma lista de alertas. É possível configurar o widget para mostrar alertas de políticas de alertas específicas ou de tipos de recursos específicos.
Widgets que mostram entradas de registro e erros:
- ErrorReportingPanel: mostra os grupos de erros armazenados no projeto do Google Cloud selecionado.
- LogsPanel: exibe entradas de registro com escopo de projeto armazenadas no projeto Google Cloud atual. É possível configurar o widget para mostrar entradas de registro armazenadas em projetos do Google Cloud acessíveis pelo escopo de métricas atual.
Widgets que mostram dados de trace:
- XyChart: exibe dados nos eixos X e Y.
- TimeSeriesTable: mostra o valor mais recente ou um valor agregado. As tabelas podem ser personalizadas.
Widgets de texto e organização:
- CollapsibleGroup: mostra uma coleção de widgets. É possível fechar a visualização de um grupo.
- SingleViewGroup: mostra um widget em uma coleção de widgets. Você pode selecionar qual widget mostrar.
- SectionHeader: cria um divisor horizontal no painel e uma entrada no sumário do painel.
- Text: exibe conteúdo textual, como texto bruto ou uma string Markdown.
Para incluir os widgets de texto e organização em um painel, ele precisa ter um MosaicLayout.

Além desses objetos, também é possível adicionar um marcador de posição em branco a um painel.

O exemplo a seguir mostra a representação JSON de um widget XyChart com o eixo Y direito configurado:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Rótulos de painel

Os rótulos podem ajudar você a gerenciar e organizar seus painéis. Por exemplo, é possível adicionar um rótulo chamado prod para indicar que o painel exibe dados de série temporal e de registro para os recursos de produção. Como alternativa, é possível adicionar o rótulo playbook para indicar que o painel contém informações para ajudar a resolver falhas.

A adição de rótulos a um painel é opcional.

Por exemplo, o código a seguir mostra um objeto Dashboard que especifica o rótulo chamado playbook.

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

Como o exemplo anterior ilustra, o campo labels é implementado como um map, em que os campos key e value são strings. Ao adicionar um rótulo a um painel, defina key como o nome do rótulo e o campo value como uma string vazia.

Filtros e variáveis do painel

Ao projetar um painel, é possível identificar várias maneiras de visualizar os dados que ele exibe. Por exemplo, suponha que um painel mostre dados de série temporal para suas instâncias de máquina virtual (VM). Talvez você queira visualizar os dados de série temporal de todas as VMs ou apenas os dados de uma zona específica. Nessa situação, recomendamos que você crie um filtro fixado ou uma variável e defina o valor padrão desse filtro como a zona mais visualizada.

Os filtros fixados se aplicam a todos os widgets do painel que aceitam o rótulo especificado no filtro, a menos que o widget contenha um filtro com essa mesma chave de rótulo. Por exemplo, quando um gráfico inclui o filtro zone = us-central1-a, ele ignora um filtro fixado com a chave de rótulo zone. Da mesma forma, esse filtro é ignorado por gráficos que não têm um rótulo com uma chave de zone.

As variáveis são como filtros fixados, mas só se aplicam a widgets específicos. As variáveis podem ser baseadas em rótulos ou ter apenas um valor. As variáveis somente de valor contêm um ou mais valores padrão e uma lista de todos os valores possíveis. Se você não especificar um valor padrão, o padrão será definido como o operador curinga (*). Para definir o conjunto de todos os valores possíveis, forneça uma matriz de valores ou escreva uma consulta SQL.

Se você criar um filtro ou uma variável fixada, o Monitoring vai atualizar a barra de ferramentas do painel personalizado para exibir um filtro. Para filtros fixados, o nome do filtro da barra de ferramentas é o nome do filtro fixado. Para variáveis, o nome do filtro da barra de ferramentas é um cifrão $ seguido pelo nome da variável. Cada filtro da barra de ferramentas contém um menu que permite mudar o valor do filtro ou da variável fixada associada. Para variáveis, é possível substituir o filtro da barra de ferramentas por um widget de painel. Para saber mais, consulte Painel com um widget FilterControl.

Para widgets que consultam dados, é possível 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 solicitados pelo widget mudam quando você altera o valor da variável. Como resultado, os dados exibidos também mudam. Quando você usa uma variável para controlar a visibilidade de um widget, um ícone Visível é mostrado na barra de ferramentas. Para restrições relacionadas à visibilidade, consulte Definir a visibilidade de um widget.

A mesma estrutura de dados é usada para representar filtros e variáveis fixados. Para ver mais informações, consulte DashboardFilter.

Para ver um exemplo de como controlar a visibilidade de um widget usando uma variável, consulte Painel com visibilidade de widget configurada.

Para saber como atualizar a consulta de um widget com uma variável baseada em rótulo ou somente valor, consulte as seções a seguir:

Sintaxe geral para desreferenciar uma variável
Widgets do painel de registros
Gráficos com consultas PromQL
Gráficos com consultas SQL
Gráficos com consultas de filtro do Monitoring

Quando você usa a interface orientada por menu para criar um gráfico que exibe dados de série temporal, suas seleções são convertidas em um filtro do Monitoring.

Criar filtros e variáveis

Console

Para saber como usar o console do Google Cloud para criar filtros e variáveis fixados, consulte os seguintes documentos:

REST

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

Para criar uma variável, defina o valor do campo templateVariable como o nome da variável. Omita esse campo ou defina o valor como uma string vazia quando quiser criar um filtro fixado.
Para criar um filtro fixado ou uma variável baseada em rótulo, especifique o campo labelKey. Omita esse campo quando quiser uma variável somente de valor.
Defina o valor padrão para o filtro ou a variável. A configuração desse campo determina se um usuário pode selecionar exatamente uma opção no menu de valores ou se pode selecionar vários valores.
Para definir um único valor padrão e restringir os usuários a selecionar exatamente uma opção no menu de valores, defina o campo valueType como STRING e também o campo stringValue:
```
"valueType": "STRING",
"stringValue": "my-default-value",
```
Para definir pelo menos um valor padrão e permitir que os usuários selecionem várias opções no menu de valores, defina o campo valueType como STRING_ARRAY e também o campo stringArrayValue. No exemplo a seguir, há três valores padrão.
```
"valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},
```
Observação: se você não especificar um valor padrão, o operador de caracteres curinga, (*), será selecionado automaticamente. Se você planeja usar a variável em um painel de registros, use a expressão regular como um comparador. Para consultas SQL, use uma instrução IF. Para mais informações, consulte Gráficos com consultas SQL.
Opcional: para especificar a lista de todos os valores possíveis para uma variável somente de valor, defina o campo stringArray ou o campo timeSeriesQuery. Se você especificar uma consulta, ela precisará ser uma consulta de análise.

Observação :não defina os campos timeSeriesQuery ou stringArray ao criar um filtro fixado ou uma variável baseada em rótulo. O conjunto de todos os valores possíveis é determinado dinamicamente.

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 fixado e duas variáveis:

O filtro fixado tem a chave de rótulo de zone, que é exibida na barra de ferramentas. Os campos valueType e stringValue especificam o valor padrão único. Para mais informações, consulte a página de referências da API para a estrutura de dados dashboardFilters.
A variável com base em rótulo tem o nome my_label_based_variable, e a chave de rótulo é instance_id. O valor padrão dessa variável é definido como um ID de instância específico. Também é possível configurar o valor padrão usando uma matriz. Na barra de ferramentas, o filtro é exibido com o nome my_label_based_variable.
A variável somente de valor é chamada de my_value_only_variable. Essa entrada não especifica um valor padrão, então o operador curinga, (*), é aplicado automaticamente. Além disso, essa variável usa uma consulta SQL para gerar a lista de valores possíveis para a variável.

O objeto dashboardFilters não lista os widgets aos quais a variável se aplica. Em vez disso, atualize a consulta de um widget para que ela dependa 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 com base em rótulo e fazer com que a chave e o valor do rótulo sejam resolvidos em uma 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 com base em rótulo, use ${my_label_based_variable.value}. A comparação precisa usar uma expressão regular.
Para aplicar apenas o valor de uma variável somente de valor, use ${my_value_only_variable}. Para variáveis somente de valor, não inclua uma cláusula .value. A comparação precisa usar uma expressão regular.

Widgets do painel de registros

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

Console

Por exemplo, a consulta a seguir 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 rótulo:

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

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

severity =~ "${value_only_severity_variable}"

Veja a seguir o formulário renderizado:

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

REST

Por exemplo, o JSON a seguir ilustra como atualizar a consulta de um widget do painel de registros com uma variável baseada em rótulo:

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

Por exemplo, a consulta a seguir 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 rótulo:

"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 somente de valor, value_only_severity_variable, e suponha que três valores sejam selecionados no menu: ERROR, INFO e NOTICE. Em seguida, adicione o seguinte ao painel de consulta do widget do painel de registros:

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

Veja a seguir a consulta executada pelo widget do painel de registros:

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

Se você tiver configurado uma consulta para o painel de registros e selecionar o botão para abrir a Análise de registros, as variáveis serão resolvidas antes da abertura da Análise de registros.

A tabela a seguir ilustra como as variáveis de exemplo são resolvidas pelo painel de registros. Como mencionado anteriormente, quando apenas o valor de uma variável é usado, é necessário usar uma expressão regular como operador de comparação:

Sintaxe	Valor selecionado	Expressão do painel de registros resolvidos
`${my_label_based_variable}`	`12345`	`resource.labels."instance_id"="12345"` A variável de exemplo é baseada no rótulo de 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 tem uma consulta PromQL para depender de uma variável baseada em rótulo, siga as orientações listadas em Sintaxe geral.

Console

Por exemplo, a consulta a seguir depende da variável baseada em rótulo, my_label_based_variable, que é resolvida em uma expressão de filtro:

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

Também é possível modificar a consulta para resolver apenas o valor de uma variável. O exemplo a seguir usa uma expressão regular para comparar o valor de uma consulta baseada em rótulo com instance_id:

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

Se você tiver uma variável somente de valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável somente de valor, a consulta incluiria algo como:

zone=~"${my_value_only_variable}"

REST

Por exemplo, o JSON a seguir ilustra uma consulta que depende da variável baseada em rótulo, my_label_based_variable, sendo resolvida em uma 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
},

"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 você tiver uma variável somente de valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável somente de valor, a consulta incluiria algo como:

zone=~\"${my_value_only_variable}\"

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

Sintaxe	Valor selecionado	Expressão PromQL resolvida
`${my_label_based_variable}`	`12345`	`instance_id == '12345'` A variável de exemplo é baseada no rótulo de 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

Há dois lugares em que é possível usar variáveis nas consultas SQL:

A cláusula FROM pode depender da variável definida pelo sistema chamada @__project_id, que é resolvida para o valor do projeto selecionado.
A cláusula WHERE pode depender de variáveis definidas pelo usuário.

Atualizar a cláusula FROM para depender de uma variável definida pelo sistema

Se você criar modelos de painel e esses modelos representarem os resultados de consultas SQL, substitua o ID do projeto na consulta pela variável @__project_id. Quando você instala o modelo em um projeto, a variável é resolvida automaticamente para o ID do projeto. Não é necessário editar manualmente o widget e atualizar a cláusula FROM.

Veja a seguir uma cláusula FROM que depende da variável definida pelo sistema:

FROM `@__project_id.global._Default._Default`

A cláusula FROM não pode depender de variáveis definidas pelo usuário.

Atualizar a cláusula WHERE para depender de uma variável definida pelo usuário

Nesta seção, descrevemos como atualizar a cláusula WHERE de um widget definido por SQL para que ela dependa de uma variável definida pelo usuário. Para todas as variáveis, use o prefixo "@" no nome da variável, por exemplo: @variable_name. Para variáveis com base em rótulos, anexe .value ao nome da variável, @my_label_based_variabe.value.

Para consultas SQL, a substituição de variáveis depende do BigQuery e é segura contra injeção de SQL. Para mais informações, consulte Como executar consultas parametrizadas.

Console

Como o SQL não interpreta o operador curinga como "qualquer valor", recomendamos que você sempre use uma instrução IF ao usar variáveis em uma consulta SQL. O exemplo a seguir ilustra o uso de uma variável somente de valor com um tipo de dados de string:

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

Quando a opção de menu da variável permite que os usuários selecionem vários valores, é necessário converter o valor da variável em um tipo de dados do GoogleSQL usando a função CAST. A consulta a seguir ilustra essa sintaxe:

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

A instrução IF mostrada nos exemplos anteriores é recomendada porque o SQL não interpreta o operador curinga como "qualquer valor". Portanto, se você omitir a instrução IF e selecionar o operador de caractere curinga, o resultado da consulta será uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz em uma tabela.

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

Edite o widget.
Na barra de ferramentas, selecione Inserir filtro de variável e escolha a variável com a cláusula WHERE que você quer atualizar.
Na caixa de diálogo que aparece, revise o código gerado e clique em Copiar e fechar.
Cole o código copiado no painel Consulta e faça as edições necessárias.

Por exemplo, suponha que você crie uma variável chamada LogName que gera uma lista de nomes de registro e gera o resultado em uma tabela com uma única coluna chamada log_name. Em seguida, crie um gráfico, selecione Inserir filtro de variável e selecione a variável LogName. O seguinte código é gerado:
```
WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
```
Neste exemplo, é necessário editar o código gerado e substituir LogName = por log_name = para que a mesclagem de tabelas possa ocorrer:
```
WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
```
Clique em Executar e em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

REST

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

Por exemplo, o código a seguir mostra uma representação JSON parcial de um gráfico que exibe os resultados de uma consulta SQL. Para filtrar os resultados pelo nome de um registro, foi adicionada uma cláusula WHERE que faz referência à variável chamada 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 emite uma consulta para determinar a lista de nomes de registro 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
    }
  }
],

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

Gráficos com consultas de filtro do Monitoring

Para atualizar um gráfico que tem uma consulta na forma de um filtro do Monitoring para depender de uma variável baseada em rótulo, siga as orientações listadas em Sintaxe geral.

Console

Se você usar o console do Google Cloud para criar os gráficos e a interface orientada por menu, poderá atualizar a consulta do gráfico usando o campo Aplicar aos gráficos da variável ou editando o widget e selecionando a variável baseada em rótulo no menu Filtro. O menu Filtro lista todas as variáveis com base em rótulo e todas as chaves de rótulo.

Para atualizar a consulta de um gráfico para que ela dependa de uma variável baseada em valor, faça o seguinte:

Edite o gráfico.
No painel de consulta, clique em Adicionar filtro e selecione uma chave de rótulo. Por exemplo, é possível selecionar zona.
No menu Valor, selecione a variável somente de valor.
Clique em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Por exemplo, o JSON a seguir ilustra uma consulta que depende de uma variável baseada em rótulo, my_label_based_variable, sendo resolvida em uma 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 na forma de um filtro do Monitoring não podem filtrar a série temporal pelo valor em uma variável com base em rótulo. No entanto, é possível filtrar por variáveis somente de valor. Por exemplo, a consulta a seguir mostra o valor do campo Filtros de uma consulta que filtra por zone, com base no valor de uma variável somente 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})

REST

Por exemplo, o JSON a seguir ilustra uma consulta que depende de uma variável baseada em rótulo, my_label_based_variable, sendo resolvida em uma 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 na forma de um filtro do Monitoring não podem filtrar a série temporal pelo valor em uma variável com base em rótulo. No entanto, é possível filtrar por variáveis somente de valor. Por exemplo, a consulta a seguir mostra o campo "filter" de uma consulta que filtra por zone, com base no valor de uma variável somente 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 a seguir ilustra como as variáveis de exemplo são resolvidas pelo filtro do Monitoring. Como mencionado anteriormente, quando apenas o valor de uma variável é usado, é necessário usar uma expressão regular como operador de comparação:

Sintaxe	Valor selecionado	Expressão de filtro resolvida
`${my_label_based_variable}`	`12345`	`resource.instance_id == "12345"` A variável de exemplo é baseada no rótulo de recurso `instance_id`.
`${my_label_based_variable}`	`*`	Omitida
`${my_label_based_variable.value}`	`12345`	Sem suporte
`${my_label_based_variable.value}`	`*`	Sem suporte
`${my_value_based_variable}`	`12345`	`"12345"`
`${my_value_based_variable}`	`*`	`".*"`

Antes de começar

No projeto do Google Cloud em que você quer criar ou gerenciar painéis, faça o seguinte:

gcloud

Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando:

gcloud init

Terraform

Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

Instale a CLI do Google Cloud.
Configure a CLI gcloud para usar sua identidade federada.

Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.
Crie credenciais de autenticação local para sua conta de usuário:
```
gcloud auth application-default login
```
Se um erro de autenticação for retornado, confirme se você fez login na CLI gcloud com sua identidade federada.

Saiba mais em Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

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.

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

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

Quando você cria um painel, a API gera automaticamente o componente DASHBOARD_ID. Se você quiser especificar um DASHBOARD_ID personalizado, especifique o campo name do objeto Dashboard.

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 --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 host ou de gerenciamento do App Hub.

Por exemplo, para duplicar um painel, faça o seguinte:

Siga as etapas em Acessar painel para fazer o download da definição do painel original.
Edite o JSON retornado para remover os campos etag e name e altere o valor do campo displayName.
Execute o comando para criar o painel.

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

Terraform

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

Para criar um painel usando o Terraform, faça o seguinte:

Instale e configure o Terraform para seu projeto. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Use o recurso do Terraform google_monitoring_dashboard.

No comando, defina os seguintes campos:
- dashboard_json: a representação JSON do painel, usando o formato Dashboard.
  
  Para ver exemplos desse formato, liste seus painéis usando o APIs Explorer ou abra um painel no console do Google Cloud e veja a representação JSON.
- parent: o nome totalmente qualificado do projeto. Por exemplo, é possível definir esse campo como "projects/PROJECT_ID", em que PROJECT_ID é o ID do projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

REST

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

Antes de executar o comando anterior, configure o seguinte:

${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

Os exemplos criam um painel de amostra usando o arquivo my-dashboard.json. É possível gerenciar o painel pelo console doGoogle Cloud .

Para outras configurações de 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.

gcloud

Para excluir um painel personalizado, use gcloud monitoring dashboards delete e especifique o ID totalmente qualificado do painel a ser excluído:

gcloud monitoring dashboards delete 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 host ou de gerenciamento do App Hub.
DASHBOARD_ID: o ID do painel.

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

Terraform

É possível excluir recursos usando o Terraform. Para informações sobre como excluir recursos, consulte o comando destroy do Terraform.

REST

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}

Antes de executar o comando anterior, configure o seguinte:

${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel.

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

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.

gcloud

Para listar todos os painéis 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 host ou de gerenciamento do App Hub.

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

Terraform

Não é possível usar o Terraform para enviar uma consulta ao projeto com a resposta sendo uma lista de painéis. No entanto, é possível visualizar esses painéis usando o console do Google Cloud .

REST

Para listar todos os painéis personalizados de um projeto, envie o ID do projeto para o endpoint 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 em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

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.

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 --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 host ou de gerenciamento do App Hub.

Terraform

Não é possível usar o Terraform para enviar uma consulta ao projeto com a resposta sendo uma lista paginada de painéis. No entanto, é possível visualizar esses painéis usando o console do Google Cloud .

REST

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

Antes de executar o comando anterior, configure o seguinte:

${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

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.

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.

gcloud

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

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 host ou de gerenciamento do App Hub.
DASHBOARD_ID: o ID do painel.

O comando retorna o painel solicitado:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

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

Terraform

Não é possível usar o Terraform para enviar uma consulta ao projeto com a resposta sendo um painel individual. No entanto, é possível visualizar esses painéis usando o console do Google Cloud .

REST

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}

Antes de executar o comando anterior, configure o seguinte:

${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel.

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

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

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.

gcloud

Para atualizar um painel personalizado, use gcloud monitoring dashboards update, especifique o ID do painel a ser atualizado e forneça as alterações no painel.

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --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 host ou de gerenciamento do App Hub.
DASHBOARD_ID: o ID do painel.

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

O exemplo anterior atualiza um painel personalizado usando o arquivo my-updated-dashboard.json. A resposta, que inclui um novo valor etag, é uma cópia da listagem de painéis atualizada.

Terraform

Para atualizar um painel usando o Terraform, faça o seguinte:

Instale e configure o Terraform para seu projeto. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Use o recurso do Terraform google_monitoring_dashboard.

No comando, defina os seguintes campos:
- dashboard_json: a representação JSON do painel, usando o formato Dashboard.
- parent: o nome totalmente qualificado do projeto. Por exemplo, é possível definir esse campo como "projects/PROJECT_ID", em que PROJECT_ID é o ID do projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

REST

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}

Antes de executar o comando anterior, configure o seguinte:

${PROJECT_ID}: uma variável de ambiente que armazena o ID do projeto em que o painel será criado. Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
${DASHBOARD_ID}: uma variável de ambiente que armazena o ID do painel.

O exemplo anterior atualiza um painel personalizado usando o arquivo my-updated-dashboard.json. A resposta, que inclui um novo valor etag, é uma cópia da listagem de painéis atualizada.

Criar e gerenciar painéis por API Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Sobre os painéis

Layouts de painel

Widgets do painel

Rótulos de painel

Filtros e variáveis do painel

Criar filtros e variáveis

Console

REST

Sintaxe geral para desreferenciar uma variável

Widgets do painel de registros

Console

REST

Gráficos com consultas PromQL

Console

REST

Gráficos com consultas SQL

Console

REST

Gráficos com consultas de filtro do Monitoring

Console

REST

Antes de começar

gcloud

Terraform

REST

Crie um painel

gcloud

Terraform

REST

Excluir painéis

gcloud

Terraform

REST

Listar painéis

gcloud

Terraform

REST

Paginar a resposta da lista

gcloud

Terraform

REST

Acessar painel

gcloud

Terraform

REST

Atualizar painel

gcloud

Terraform

REST

A seguir

Criar e gerenciar painéis por API