Adicionar filtros permanentes a um painel personalizado

Neste documento, descrevemos como adicionar filtros permanentes no nível do painel aos seus painéis personalizados. Os filtros permanentes, que permitem modificar os dados exibidos por um painel sem ter que modificar cada widget, têm um estado padrão e podem ser aplicados a todo o painel ou apenas a widgets específicos. A barra de ferramentas do painel exibe cada filtro permanente, junto com um menu, que permite alterar temporariamente o valor do filtro.

Quando você quiser definir uma apresentação padrão de dados em um painel, junto com opções baseadas em menus para modificar essa exibição, adicione filtros permanentes. Por exemplo, se você quiser ver as métricas de todas as zonas e de uma zona específica, crie um filtro permanente com base no rótulo zone.

É possível criar e aplicar filtros permanentes usando o console do Google Cloud ou a API Cloud Monitoring. Neste documento, descrevemos como usar o console do Google Cloud. Para mais informações sobre como usar a API Cloud Monitoring, consulte Criar e gerenciar painéis por API: filtros do painel.

Para saber mais sobre como adicionar e modificar agrupamentos e filtros temporários, consulte Adicionar filtros temporários a um painel personalizado.

Como funcionam os filtros do painel

Um filtro de painel especifica um rótulo e um valor. A série temporal que o painel exibe determina os rótulos disponíveis para filtragem. A forma como um widget oferece suporte a um filtro em todo o painel depende do tipo de dados exibido e da configuração do widget:

  • Para widgets que exibem dados de série temporal, como gráficos de linhas, as seguintes regras são aplicadas:

    • Se a série temporal exibida pelo widget não for compatível com o rótulo em um filtro, o filtro do painel não alterará os dados exibidos.

      Por exemplo, se você adicionar um filtro no rótulo instance_id, mas um gráfico no painel não exibir dados com um rótulo instance_id, o filtro não alterará os dados exibidos.

    • Se o widget especificar um valor para um rótulo, o filtro do painel não alterará os dados exibidos.

      Por exemplo, se você adicionar um filtro no rótulo instance_id, mas um gráfico no painel incluir um filtro baseado no rótulo instance_id, o filtro do painel não alterará os dados exibidos.

    • Caso contrário, o gráfico filtrará os dados exibidos apenas para as série temporal que satisfaçam o filtro do painel.

  • Para widgets do painel de registros, os filtros de todo o painel baseados em um rótulo de recurso atualizam a consulta. Por exemplo, se você adicionar o filtro cluster_name: mycluster em todo o painel, a consulta será atualizada para incluir resource.labels."cluster_name"="mycluster".

É possível adicionar vários filtros no painel. Esses filtros são combinados com um AND lógico.

Antes de começar

Para receber as permissões necessárias para adicionar ou modificar filtros permanentes usando o console do Google Cloud, peça ao administrador para conceder a você o papel do IAM Editor do Monitoring (roles/monitoring.editor) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível receber as permissões necessárias com 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 um filtro permanente

Ao projetar um painel, é possível identificar várias maneiras de visualizar os dados que ele exibe. Por exemplo, quando um painel exibe métricas de instâncias de VM, talvez você queira visualizar métricas de todas as VMs e métricas de VMs em uma zona específica. É possível criar um filtro permanente para o rótulo zone com o padrão definido para todas as zonas, *. Ao visualizar o painel, é possível usar o menu no filtro zone para selecionar uma zona específica.

É possível restringir um filtro permanente a widgets específicos. Considere um cenário em que você quer uma visualização lado a lado das métricas de VMs em duas zonas diferentes. Você constrói duas coleções de gráficos e um filtro para cada uma. A configuração padrão satisfaz ao objetivo original. No entanto, ao visualizar o painel, a barra de ferramentas lista suas variáveis e inclui menus para permitir que você selecione valores diferentes. Você pode usar esses menus para exibir dados para diferentes zonas.

Os filtros permanentes que se aplicam apenas a widgets específicos às vezes são chamados de variáveis de modelo. Depois de criar um filtro desse tipo, ao adicionar um widget ao painel, também é possível aplicar o filtro a ele. Para mais informações, consulte Aplicar um filtro permanente a um widget.

Para criar um filtro permanente, faça o seguinte:

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

    Acessar Painéis

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

  2. Na barra de ferramentas do painel, clique em Configurações e, em seguida, selecione Gerenciar filtros.
  3. Clique em Marcador e selecione um marcador. Por exemplo, é possível selecionar zone.

  4. Clique em Valor padrão e selecione o valor padrão para o rótulo. Para corresponder 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 seleção no menu.

  5. Escolha uma destas opções:

    • Para aplicar o filtro a todos os widgets no painel, selecione Aplicar a todos e, em seguida, Aplicar.

    • Para aplicar o filtro a alguns widgets no painel:

      1. Desmarque Aplicar a tudo.
      2. No campo Nome da variável, insira o nome de exibição dela.

      3. Expanda o menu Aplicar aos gráficos, selecione os widgets a que o filtro se aplica e clique em OK.

      4. Clique em Aplicar.

Aplicar um filtro permanente a um widget

Para aplicar um filtro permanente a um widget, associe esse widget à variável:

  • Nos gráficos configurados usando menus, é possível realizar essa associação ao criar ou editar o filtro.

  • No painel de registros, edite o widget e configure a consulta padrão. Siga as orientações na seção Sintaxe para aplicar um filtro permanente.

  • No caso de gráficos e tabelas definidos por MQL ou PromQL, edite o gráfico ou a tabela e modifique o MQL ou o PromQL. Não deixe de seguir as orientações da seção Sintaxe para aplicar um filtro permanente.

Sintaxe para aplicar um filtro permanente

Por exemplo, o exemplo a seguir mostra a representação JSON parcial de um painel que define uma variável de modelo e um filtro em todo o painel:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

No JSON exibido, a primeira entrada na estrutura dashboardFilters é de uma variável de modelo com o nome iid e um filtro do painel com a chave de rótulo zone. A variável de modelo é um alias do rótulo instance_id.

A estrutura de dados de uma variável de modelo não lista os widgets a que ela se aplica. Em vez disso, você associa um widget a uma variável de modelo modificando a consulta do widget para incluir uma referência à variável. Quando o widget é exibido no painel, o valor da variável de modelo é resolvido.

Consulte as seções abaixo para saber como fazer anotações em painéis e gráficos de registros:

Painel de registros

Para configurar um painel de registros para filtrar a exibição com base no valor de uma variável de modelo, adicione a variável ao painel de consulta. O exemplo a seguir ilustra uma consulta que filtra pelo valor da variável de modelo iid:

${iid}

Antes que o painel de registros consulte a exibição dos registros, a variável de modelo é resolvida. Neste exemplo, se o valor da variável de modelo for "12345", ${iid} será substituído pela instrução resource.labels."instance_id"="12345".

Também é possível incluir apenas o valor de uma variável de modelo em uma consulta. Recomendamos que você use o valor apenas como parte de um filtro definido com uma expressão regular. Por exemplo, a consulta a seguir usa uma expressão regular para corresponder a entradas de registro que têm um payload JSON que contém a string descrita:

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

Se você configurou uma consulta para o painel de registros e selecionou o botão para abrir a Análise de registros, as variáveis de modelo serão resolvidas antes de abrir a Análise de registros.

A tabela a seguir mostra como a variável de modelo é resolvida pelo painel de registros:

Sintaxe Valor
selecionado		 Expressão do painel de registros resolvida
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

Gráficos e tabelas definidos pelo MQL

Ao usar a linguagem de consulta do Monitoring (MQL, na sigla em inglês) para configurar um gráfico, anexe um pipe e a variável à string de consulta:

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

Antes que o gráfico consulte a série temporal a ser exibida, a variável de modelo é resolvida. Neste exemplo, se o valor da variável de modelo for "12345", ${iid} será substituído pela instrução filter (resource.instance_id == '12345'). Esse filtro corresponde a séries temporais que têm um rótulo chamado resource.instance_id e somente quando o valor desse rótulo é exatamente 12345.

Quando você quiser filtrar série temporal usando uma expressão regular, configure a consulta para incluir apenas o valor da variável de modelo. Para ilustrar a sintaxe, veja a seguir como usar uma expressão regular para determinar se o valor do rótulo resource.instance_id contém o valor da variável de modelo iid:

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

A tabela a seguir mostra como a variável de modelo é resolvida em consultas MQL:

Sintaxe Valor
selecionado		 Expressão MQL resolvida
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

Gráficos e tabelas definidos pelo PromQL

Ao definir um gráfico com o PromQL, anexe à string de consulta a variável encapsulada por chaves:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Antes que o gráfico consulte a série temporal a ser exibida, a variável de modelo é resolvida. Neste exemplo, se o valor da variável de modelo for "12345", ${iid} será substituído pela instrução instance_id == '12345'.

Assim como no MQL, quando você define um widget com o PromQL, a consulta pode extrair apenas o valor da variável de modelo. Recomendamos que você use o valor apenas como parte de um filtro definido com uma expressão regular. Para ilustrar a sintaxe, veja a seguir como usar uma expressão regular para determinar se o valor do rótulo instance_id contém o valor da variável de modelo iid:

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

A tabela a seguir mostra como a variável de modelo é resolvida em consultas PromQL:

Sintaxe Valor
selecionado		 Expressão PromQL resolvida
${iid} 12345 instance_id == '12345'
${iid} * noop_filter=~".*"
${iid.value} 12345 12345
${iid.value} * .+

Gráficos e tabelas definidos com filtros de série temporal

Ao definir um gráfico usando filtros de série temporal, anexe a variável à string de filtro:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

Ao contrário dos gráficos definidos por MQL e PromQL, não é possível usar o valor de uma variável de modelo em um filtro de série temporal.

A tabela a seguir mostra como a variável de modelo é resolvida:

Sintaxe Valor
selecionado		 Expressão de filtro resolvida
${iid} 12345 resource.instance_id == "12345"
${iid} * Omitida
${iid.value} 12345 Sem suporte
${iid.value} * Sem suporte

Modificar um filtro permanente

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

Para alterar a configuração de um filtro permanente, faça o seguinte:

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

    Acessar Painéis

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

  2. Na barra de ferramentas do painel, clique em Configurações e, em seguida, selecione Gerenciar filtros.
  3. Encontre o filtro que você quer modificar e use os menus para fazer as modificações.
  4. Clique em Aplicar.

Excluir um filtro permanente

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

    Acessar Painéis

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

  2. Na barra de ferramentas do painel, clique em Configurações e, em seguida, selecione Gerenciar filtros.
  3. Encontre o filtro que você quer remover e clique em Excluir.
  4. Clique em Aplicar.

A seguir