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 variáveis e filtros fixados

Com os filtros e as variáveis fixados em um painel personalizado no Cloud Monitoring, é possível mudar dinamicamente os dados exibidos no painel na barra de ferramentas sem editar widgets individuais. Os filtros fixados se aplicam a todos os widgets que aceitam o rótulo do filtro, enquanto as variáveis se aplicam a widgets específicos para modificar as consultas ou controlar a visibilidade deles.

Neste documento, descrevemos como configurar filtros e variáveis fixados no console doGoogle Cloud . Para configurá-los usando a API Cloud Monitoring, consulte Criar e gerenciar painéis por API: filtros de painel. Para aplicar filtros ou agrupamentos apenas à sessão atual, consulte Adicionar filtros temporários a um painel personalizado.

Sobre os filtros fixados

Um filtro fixado contém um rótulo, um ou mais valores padrão e uma lista de todos os valores possíveis. A lista de todos os valores possíveis é derivada dinamicamente dos dados de série temporal exibidos no painel.

Não é possível aplicar um filtro fixado a widgets individuais. Em vez disso, as regras a seguir são usadas para determinar se o filtro fixado pode mudar os dados exibidos pelo widget:

Se o widget exibir dados que incluem a chave de rótulo especificada por um filtro fixado e se o widget não especificar um valor para essa chave de rótulo, o filtro fixado poderá alterar os dados exibidos.

Por exemplo, suponha que você adicione o filtro fixado cluster_name: mycluster. Em seguida, os gráficos mostram automaticamente apenas as série temporal que têm um rótulo cluster_name com o valor mycluster. Da mesma forma, as consultas nos widgets do painel de registros são modificadas para resource.labels."cluster_name"="mycluster", e os gráficos exibem automaticamente apenas as série temporal que incluem o rótulo no filtro fixado.
Um filtro fixado é ignorado por um widget quando ele inclui um filtro para a mesma chave de rótulo ou quando os dados exibidos pelo widget não contêm a chave de rótulo especificada no filtro fixado.

Na API, os filtros fixados são definidos pela estrutura DashboardFilter. Por exemplo, a estrutura a seguir define um filtro fixado. As séries temporais que têm um rótulo zone com o valor us-central1-c correspondem ao filtro fixado.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

Sobre as variáveis

Assim como os filtros fixados, uma variável tem um nome, um tipo e um ou mais valores padrão. No entanto, ao contrário dos filtros fixados, que são sempre baseados em rótulos, as variáveis não precisam depender de rótulos.

Uma variável é aplicada a um widget específico modificando a consulta que o widget contém.

Na barra de ferramentas do painel, os nomes das variáveis são precedidos por um cifrão $. Se você também encontrar um ícone Visível, isso significa que a variável controla a visibilidade de pelo menos um widget.

As variáveis definidas pelo usuário podem ser baseadas em rótulos ou ter apenas um valor:

As variáveis com base em rótulo são como filtros fixados. Essas variáveis contêm uma chave de rótulo, um ou mais valores de rótulo padrão e uma lista de todos os valores de rótulo possíveis. A lista de todos os valores possíveis é derivada dinamicamente dos dados de série temporal exibidos no painel.
As variáveis somente de valor contêm um ou mais valores padrão e podem listar todos os valores possíveis. Se você não especificar um valor padrão, o operador curinga, (*), será selecionado para o valor padrão. Para definir o conjunto de todos os valores possíveis, forneça uma matriz de valores ou escreva uma consulta SQL.

Há três tipos de variáveis somente de valor: Personalizada, Entrada de texto e Consulta SQL.
- Personalizado: use quando quiser enumerar a lista de todos os valores possíveis e também definir um ou mais valores padrão. Por exemplo, é possível definir a lista de todos os valores possíveis como prod, staging, dev e o valor padrão como prod.
- Entrada de texto: use quando você não souber todos os valores possíveis. Ao criar essa variável, é possível especificar um ou mais valores. No entanto, a opção de menu permite adicionar novos valores que se aplicam à sessão atual.
- Consulta SQL: use quando quiser gerar a lista de valores possíveis usando uma consulta SQL. Essas variáveis são destinadas a serem aplicadas a gráficos criados com a Análise de Observabilidade.
  
  Para essas variáveis, verifique se o resultado da consulta é uma tabela com uma coluna, se o tipo de dados dessa coluna é uma string e se cada linha na tabela contém um valor de string exclusivo:
```
SELECT log_name
FROM `VIEW`
GROUP BY log_name
```
  A consulta SQL não pode depender de uma variável.

Há uma variável definida pelo sistema, @__project_id. É possível usar essa variável somente na cláusula FROM para consultas SQL. Para saber como aplicar essa variável a uma consulta, consulte Gráficos com consultas SQL.

Para aplicar uma variável a um widget, atualize a consulta emitida pelo widget ou a visibilidade dele. É possível editar o widget para atualizar a consulta. No entanto, para variáveis baseadas em rótulos e alguns tipos de widget, é possível atualizar a consulta fazendo seleções de menu. Para controlar a visibilidade, é necessário editar o widget. Para mais informações, consulte as seguintes seções deste documento:

Atualizar a consulta de um widget
Definir a visibilidade de um widget

Na API, as variáveis são definidas pela estrutura DashboardFilter. Por exemplo, a estrutura a seguir define a variável my_zone_variable que opera no rótulo de recurso zone. As séries temporais que têm um rótulo zone com o valor us-central1-c correspondem à variável.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

Antes de começar

No projeto do Google Cloud em que você quer configurar filtros e variáveis fixados, faça o seguinte:

Para receber as permissões necessárias para adicionar ou modificar variáveis ou filtros fixados usando o console do Google Cloud , peça ao administrador para conceder a você o papel do IAM de Editor do Monitoring (roles/monitoring.editor) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre papéis, consulte Controlar o acesso com o Identity and Access Management.

Criar e fixar um filtro

Para criar e fixar um filtro que se aplique a todos os widgets do painel que aceitam filtros, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Selecione um painel, acesse a barra de ferramentas dele e clique em Configurações.
Na seção Filtros, clique em Adicionar um filtro.
Clique em Marcador e selecione um marcador. Por exemplo, selecione zone.
Para permitir que os usuários selecionem vários valores no menu de valores do filtro, selecione Seleção múltipla. Quando a Seleção múltipla não está ativada, os usuários só podem escolher uma opção no menu de valores.
Clique em Valor padrão e selecione o valor ou os valores padrão do marcador. Para corresponder a todos os valores, selecione *.

Observação :quando os painéis contêm gráficos definidos pelo PromQL, o menu de valores de um filtro pode não ser carregado ou não conter os valores corretos. No entanto, é possível inserir o valor do filtro manualmente.

Depois que o filtro é criado, ele é adicionado à barra de ferramentas do painel. Para mudar temporariamente o valor do filtro, selecione o filtro e faça uma seleção no menu.
Clique em Concluído e em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Crie uma variável

Para criar uma variável que se aplique a widgets específicos do painel, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Selecione um painel, acesse a barra de ferramentas dele e clique em Configurações.
Na seção Variáveis, clique em Adicionar uma variável.
Selecione o tipo de variável e preencha a caixa de diálogo.

Observação: para permitir que um usuário selecione vários valores no menu de valores da variável, selecione Seleção múltipla. Quando a Seleção múltipla não está ativada, os usuários só podem escolher uma opção no menu de valores.

Para criar uma variável com base em rótulo, selecione Rótulo. Use essa opção quando quiser uma variável que tenha uma chave e um valor de rótulo e que possa ser usada como um filtro fixado. A lista de todos os valores possíveis é derivada dinamicamente dos dados de série temporal exibidos no painel. O menu Aplicar aos gráficos permite selecionar widgets com consultas que serão modificadas pela variável. Também é possível atualizar a consulta editando o widget.

Para variáveis somente de valor, você tem as seguintes opções:
- SQL: use essa opção quando quiser que os resultados de uma consulta SQL gerem a lista de todos os valores possíveis.
  
  Insira um ou mais valores padrão e uma consulta SQL que gere a lista de todos os valores possíveis. Verifique se o resultado da consulta é uma tabela com uma coluna, se o tipo de dados dessa coluna é string e se cada linha na tabela contém um valor de string exclusivo.
- Personalizado: use essa opção quando quiser especificar a lista de valores possíveis e um valor padrão. Por exemplo, você pode definir o campo Valores como prod, staging, dev e o Valor padrão como prod.
- Entrada de texto: use essa opção quando quiser especificar uma lista de valores que são aplicados como padrão.
Clique em Concluído e em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

O Monitoring adiciona a variável à barra de ferramentas do painel. O nome na barra de ferramentas é um cifrão $ seguido pelo nome da variável. A barra de ferramentas contém um menu que permite mudar o valor da variável.
Opcional: mova a variável da barra de ferramentas do painel para um widget do painel.

É possível adicionar um widget ao painel para modificar o valor da variável. Se você fizer essa mudança, a variável da barra de ferramentas será removida. No entanto, é possível colocar o widget que controla a variável ao lado dos widgets que ela afeta. Para saber como fazer essa mudança, consulte Adicionar widget para gerenciar o valor de uma variável.
Aplique a variável aos widgets. Se você atualizar a consulta de um widget, quando mudar o valor da variável, a consulta será modificada, assim como os dados exibidos pelo widget. Também é possível usar uma variável para controlar se um widget fica visível. Para mais informações, consulte as seguintes seções deste documento:
- Definir a visibilidade de um widget
- Atualizar a consulta de um widget

Como as variáveis se aplicam a um subconjunto de widgets do painel, talvez você queira agrupar o controle da variável e os widgets aos quais ela se aplica. Por exemplo, é possível criar um grupo recolhível ou uma seção no painel para o menu de variáveis e os widgets associados. Essa estratégia também simplifica a barra de ferramentas, removendo variáveis que não se aplicam a todos os widgets.

Para gerenciar o valor de uma variável usando um widget de painel, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Na caixa de diálogo Adicionar widget, acesse a seção Layout e selecione Variável.
Preencha a caixa de diálogo e selecione Salvar.

O painel exibe um widget que permite selecionar o valor da variável. É possível mover esse widget para um grupo recolhível ou reposicioná-lo.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Definir a visibilidade de um widget

Quando um widget consulta dados, é possível usar uma variável para controlar se ele fica visível em um painel. Por exemplo, suponha que um painel contenha widgets que exibem dados dos sistemas de produção e outro conjunto de widgets que exibem dados dos sistemas de preparo. Ao depurar durante o desenvolvimento, talvez você queira visualizar apenas os dados de preparo. Ao configurar a visibilidade dos widgets do painel com uma variável, é possível alternar entre apenas dados de produção, apenas dados de preparo e todos os dados.

Qualquer tipo de variável pode controlar se um widget fica visível ou oculto.

Para configurar a visibilidade de um widget, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Selecione um painel.
Acesse a barra de ferramentas do widget que você quer configurar e clique em Editar.
No painel Exibição, abra Visibilidade do widget.
Selecione uma variável e preencha a caixa de diálogo.

Observação: o valor do Comparador precisa ser definido como expressão regular.
Clique em Concluído e em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

O painel será atualizado. Quando pelo menos um widget no painel está oculto devido aos controles de visibilidade, o painel exibe um banner. Para ver todos os widgets, clique em Mostrar todos os widgets.

Quando você usa uma variável para controlar a visibilidade de pelo menos um widget no painel, na barra de ferramentas, o nome da variável é anotado com um ícone Visível.

Limitações

As seguintes limitações se aplicam ao configurar a visibilidade de um widget:

Os widgets organizacionais, como grupo recolhível, cabeçalho de seção e visualização única, estão sempre visíveis.
É possível excluir uma variável referenciada pelos controles de visibilidade de um widget. A ação variable-delete também remove qualquer referência à variável.
Nem todos os painéis são compatíveis com a criação de variáveis. No entanto, se um painel contiver variáveis, será possível usá-las para gerenciar a visibilidade dos widgets no painel.

Atualizar a consulta de um widget

Nesta seção, descrevemos como incluir variáveis na consulta que o widget emite. Como resultado, quando você altera o valor da variável, a consulta é modificada, e os dados exibidos pelo widget são modificados:

Para gráficos que usam consultas SQL ou PromQL e para widgets do painel de registros, é necessário editar o widget e modificar a consulta. Nesta seção, descrevemos como fazer essas edições.
Para gráficos que você configurou usando menus ou o modo de filtro direto, o Monitoring edita a consulta quando você seleciona o widget usando o menu Aplicar aos gráficos. Como alternativa, é possível editar o widget, acessar o campo Filtro e selecionar a variável.

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}`	`*`	`".*"`

Modificar um filtro ou uma variável fixada

Para mudar temporariamente o valor de qualquer filtro ou variável fixada mostrada na barra de ferramentas do painel, clique no nome do filtro ou da variável e insira um valor ou faça uma seleção no menu.

Se o painel tiver uma tabela que mostra dados de série temporal, será possível adicionar filtros temporários ou modificar filtros e variáveis permanentes usando o botão Filtrar painel para este valor de uma célula. Quando selecionado, esse botão aplica um novo filtro temporário ou atualiza o valor de um filtro ou variável atual. Os filtros e as variáveis atuais são atualizados quando a chave de rótulo da coluna da tabela corresponde à chave de rótulo de um filtro ou uma variável.

Para mudar a configuração de um filtro fixado ou de uma variável, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Na barra de ferramentas do painel, clique em Configurações.
Encontre o filtro ou a variável que você quer modificar e expanda a definição.
Depois de concluir as modificações, clique em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Excluir um filtro ou uma variável fixada

Para excluir um filtro fixado ou uma variável, faça o seguinte:

No console Google Cloud , acesse a página Painéis:
Acesse Painéis

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
Na barra de ferramentas do painel, clique em Configurações.
Encontre o filtro ou a variável que você quer remover e clique em Excluir.
Clique em Aplicar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Limitações

Os filtros no nível do painel dependem da filtragem de dados por pares de chave-valor. Esses filtros não se aplicam quando os dados não são compatíveis com pares de chave-valor ou com a chave específica. Por exemplo, não é possível usar um filtro no nível do painel para modificar os dados exibidos por um widget de trace.
Para aplicar uma variável a um widget, é preciso modificar a consulta dele. Nem todos os widgets podem ser modificados.

Criar e gerenciar variáveis e filtros fixados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Sobre os filtros fixados

Sobre as variáveis

Antes de começar

Criar e fixar um filtro

Crie uma variável

Adicionar widget para gerenciar o valor de uma variável

Definir a visibilidade de um widget

Limitações

Atualizar a consulta de um widget

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

Modificar um filtro ou uma variável fixada

Excluir um filtro ou uma variável fixada

Limitações

A seguir

Criar e gerenciar variáveis e filtros fixados