Criar e gerenciar variáveis e filtros fixados

Neste documento, descrevemos como fixar filtros no nível do painel para que eles sejam permanentes. Os filtros fixados, que permitem modificar os dados mostrados por um painel sem precisar alterar cada widget, têm um estado padrão e se aplicam a todo o painel. A barra de ferramentas do painel mostra cada filtro fixado, além de um menu que permite mudar temporariamente o valor do filtro.

As variáveis são semelhantes aos filtros fixados, mas se aplicam apenas a widgets específicos. Este documento descreve como criar variáveis e aplicá-las com um widget. Uma variável pode modificar a consulta do widget ou controlar a visibilidade dele. A barra de ferramentas do painel mostra cada variável por nome, além de um menu que permite mudar temporariamente o valor da variável. Para ajudar você a diferenciar filtros de variáveis, na barra de ferramentas, o nome de uma variável é precedido por um cifrão $.

Este documento descreve como usar o console do Google Cloud para criar variáveis e filtros fixados. Para informações sobre como usar a API Cloud Monitoring, consulte Criar e gerenciar painéis por API: filtros de painel.

Para saber como adicionar e modificar agrupamentos e filtros temporários, que se aplicam apenas à sessão atual, consulte Adicionar filtros temporários a um painel personalizado.

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

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 mostrados no painel. Para informações sobre a estrutura de um filtro, consulte DashboardFilter.

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 mostrados pelo widget:

• Se o widget mostrar dados que incluem a chave de rótulo especificada por um filtro fixado e não especificar um valor para essa chave, o filtro fixado poderá mudar os dados mostrados.

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

Sobre variáveis

Uma variável tem um nome e um tipo. Uma variável é aplicada a um widget específico modificando a consulta que ele contém. Para informações sobre a estrutura de um filtro, consulte DashboardFilter.

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

As variáveis podem ser baseadas em rótulo 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 mostrados no painel.

• As variáveis somente com 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 como 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.

  Existem 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 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. Por exemplo, você pode querer filtrar por URL, mas, ao criar a variável, não sabe a lista exata de URLs. Depois, ao usar o menu de filtro do widget, é possível inserir novos URLs e salvar as mudanças na sessão atual ou na definição da variável.

  • Consulta SQL: use quando quiser gerar a lista de valores possíveis usando uma consulta SQL. Elas são destinadas a gráficos criados com a Análise de dados de registros.

    Para essas variáveis, verifique se o resultado da consulta é uma tabela com uma coluna, se o tipo de dados dessa coluna é string e se cada linha da tabela contém um valor de string exclusivo:

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    A consulta SQL não pode depender de uma variável.

Para aplicar uma variável a um widget, atualize a consulta emitida por ele ou a visibilidade dele. Você pode 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 no menu. Para controlar a visibilidade, edite 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

Antes de começar

Conclua as etapas a seguir para o projeto do Google Cloud em que você quer configurar filtros e variáveis:

• Para ter as permissões necessárias para adicionar ou modificar variáveis ou filtros fixados usando o console 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 por meio de papéis personalizados ou de 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 aplica a todos os widgets do painel que aceitam filtros, faça o seguinte:

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

   Ir para Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
3. Selecione um painel, acesse a barra de ferramentas dele e clique em settings Configurações.
4. Na seção Filtros, clique em Adicionar um filtro.
5. Clique em arrow_drop_down Marcador e selecione um marcador. Por exemplo, é possível selecionar zone.
6. 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 selecionar uma opção no menu de valores.

7. Clique em arrow_drop_down Valor padrão e selecione o valor ou os valores padrão do rótulo. Para corresponder a todos os valores, selecione *.

   Depois que o filtro é criado, ele é adicionado à barra de ferramentas do painel. Para mudar temporariamente o valor do filtro, selecione-o e faça uma escolha no menu.

8. Clique em Concluído e em Aplicar.

9. Para salvar o dashboard 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:

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

   Ir para Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
3. Selecione um painel, acesse a barra de ferramentas dele e clique em settings Configurações.
4. Na seção Variáveis, clique em Adicionar uma variável.

5. Selecione o tipo de variável e preencha a caixa de diálogo.

   Para criar uma variável baseada em rótulo, selecione Rótulo. Use essa opção quando quiser uma variável com uma chave e um valor de rótulo que possa ser usada como um filtro. A lista de todos os valores possíveis é derivada dinamicamente dos dados de série temporal mostrados no painel. O menu Aplicar aos gráficos permite selecionar widgets cuja consulta será modificada pela variável. Você também pode 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 da 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ões.

6. Clique em Concluído e em Aplicar.

7. Para salvar o dashboard modificado, clique em Salvar na barra de ferramentas.

8. Aplique a variável aos widgets. Se você atualizar a consulta de um widget, quando mudar o valor da variável, a consulta e os dados exibidos pelo widget serão modificados. Você também pode usar uma variável para controlar se um widget está 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

Definir a visibilidade de um widget

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

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

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

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

   Ir para Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Selecione um painel.
3. Acesse a barra de ferramentas do widget cuja visibilidade você quer configurar e clique em edit Editar.
4. No painel Exibição, expanda Visibilidade do widget.

5. Selecione uma variável e preencha a caixa de diálogo.

6. Clique em Concluído e em Aplicar.

7. Para salvar o dashboard modificado, clique em Salvar na barra de ferramentas.

   O painel é atualizado. Quando pelo menos um widget no painel está oculto devido aos controles de visibilidade, um banner é exibido. 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, o nome da variável é anotado com um ícone visibility Visível na barra de ferramentas.

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 de exclusão de variável também remove qualquer referência a ela.

• Nem todos os painéis permitem a criação de variáveis. No entanto, se um painel contiver variáveis, use-as para gerenciar a visibilidade dos widgets no painel.

Atualizar a consulta de um widget

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

• Para gráficos que usam consultas SQL, PromQL ou MQL e para widgets do painel de registros, edite o widget e modifique a consulta. Esta seção descreve como fazer essas edições.

• Para gráficos configurados 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, edite o widget, acesse o campo Filtro e selecione 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 MQL

• Gráficos com consultas de filtro do Monitoring

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

Criar filtros e variáveis

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

Sintaxe geral para desreferenciar uma variável

Para todos os widgets, exceto aqueles 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 resolver a chave e o valor do rótulo 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 baseada 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.

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

severity =~ "${value_only_severity_variable}"

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

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

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

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

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:

Gráficos com consultas PromQL

Para atualizar um gráfico com uma consulta PromQL para depender de uma variável baseada em rótulo, siga as orientações listadas em Sintaxe geral.

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

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

zone=~"${my_value_only_variable}"

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

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:

Gráficos com consultas SQL

Quando você quiser atualizar um widget definido em 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 prefixo "at" ao nome da variável. Por exemplo: @variable_name. Para variáveis baseadas 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.

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

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

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

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

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

Para um gráfico que tem uma consulta MQL usar uma variável baseada em rótulo, adicione um pipe, (|), e siga as orientações listadas em Sintaxe geral.

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

resource.zone=~'${my_value_only_variable}'

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

resource.zone=~'${my_value_only_variable}'

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

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.

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

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

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

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

Modificar um filtro ou uma variável fixada

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

Se o painel tiver uma tabela que mostre dados de série temporal, você poderá adicionar filtros temporários ou modificar filtros e variáveis permanentes usando o botão Filtrar painel para este valor filter_list 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 existente. Os filtros e 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 variável.

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

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

   Ir para Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
3. Na barra de ferramentas do painel, clique em settings Configurações.
4. Encontre o filtro ou a variável que você quer modificar e expanda a definição.
5. Depois de concluir as modificações, clique em Aplicar.
6. Para salvar o dashboard 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:

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

   Ir para Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
3. Na barra de ferramentas do painel, clique em settings Configurações.
4. Encontre o filtro ou a variável que você quer remover e clique em delete Excluir.
5. Clique em Aplicar.
6. Para salvar o dashboard modificado, clique em Salvar na barra de ferramentas.

A seguir

• Analisar os dados em gráficos
• Acessar painéis específicos de recursos