Adicionar filtros permanentes a um painel personalizado

Neste documento, descrevemos como adicionar filtros permanentes no nível do painel. aos seus painéis personalizados. Filtros permanentes, que permitem modificar os dados exibidas por um painel sem ter que modificar cada widget. Tenha um estado padrão e podem ser aplicados a todo o painel ou apenas a modelos widgets. A barra de ferramentas do painel exibe cada filtro permanente, além de um menu que permite mudar temporariamente o valor do filtro.

Quando você quer definir uma apresentação padrão de dados em um painel junto com com opções orientadas pelo menu para modificar essa exibição e adicionar filtros permanentes. Para exemplo, se você quiser exibir as métricas de todas as zonas e também para uma zona específica e, em seguida, 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 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 informações 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 mostra determina os rótulos disponíveis para filtragem. A compatibilidade de um widget com um filtro em todo o painel depende do tipo de dados que ele exibe e da configuração dele:

  • Para widgets que mostram dados de séries temporais, como gráficos de linhas, as seguintes regras se aplicam:

    • Se a série temporal exibida pelo widget não for compatível com o rótulo em um filtro, o filtro do painel inteiro 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 mostrar dados com um rótulo instance_id, então o filtro não altera os dados exibidos.

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

      Por exemplo, se você adicionar um filtro no rótulo instance_id, mas um gráfico no painel incluir um filtro com base no rótulo instance_id, o filtro em todo o painel não vai mudar os dados mostrados.

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

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

É possível adicionar vários filtros em todo o painel. Esses filtros são unidos por uma 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, faça o seguinte: peça ao administrador para conceder a você Papel do IAM Editor do Monitoring (roles/monitoring.editor) no 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 Controle o acesso com o Identity and Access Management.

Criar um filtro permanente

Ao projetar um painel, você pode identificar várias maneiras de visualizar as que o painel exibe. Por exemplo, quando um painel exibe métricas para instâncias de VM, convém conferir as métricas de todas as VMs e talvez você queira conferir 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, você pode usar o 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 crie um filtro para cada coleção. Sua configuração padrão satisfaz seu objetivo original. No entanto, ao visualizar o painel, lista suas variáveis e inclui menus para permitir que você selecione diferentes valores. Você pode usar esses menus para conferir dados de diferentes zonas.

Os filtros permanentes que se aplicam apenas a widgets específicos às vezes são chamados variáveis de modelo. Depois de criar um filtro desse tipo, ao adicionar um widget ao painel, você também pode 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:

    Ir para 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 selecione Gerenciar filtros.
  3. Clique em Marcador e selecione um marcador. Por exemplo, selecione zone.

  4. Clique em Valor padrão e selecione o valor padrão do marcador. Para corresponder todos os valores, selecione *.

    Depois que o filtro é criado, ele é adicionado à barra de ferramentas do painel. Para alterar temporariamente o valor do filtro, selecionar o filtro e fazer uma no menu.

  5. Escolha uma destas opções:

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

    • Para criar uma variável ou aplicar o filtro a alguns widgets na painel de controle:

      1. Limpe Aplicar a todos.
      2. No campo Nome da variável, insira um nome de exibição para a variável.

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

      4. Clique em Aplicar.

Aplicar um filtro permanente a um widget

Para aplicar um filtro permanente a um widget, você precisa associar esse widget à variável:

  • Para gráficos configurados usando menus, é possível associar o filtro 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 intitulada Sintaxe para aplicar um filtro permanente.

  • Para gráficos e tabelas definidos por MQL ou PromQL, edite o gráfico ou tabela e, em seguida, modificar o MQL ou o PromQL. Siga as orientações da seção chamada 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 é para uma variável de modelo com o nome iid e um filtro em todo o painel com a chave de rótulo zone. A variável do 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 a modificação da consulta do widget para incluir uma referência à variável. Quando o widget for exibido no painel, o valor da variável de modelo é resolvido.

Consulte as seções a seguir para saber como anotar painéis de registros e gráficos:

Painel de registros

Para configurar um painel de registros a fim de 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 de o painel de registros consultar os registros para exibição, a variável de modelo é resolvido. Neste exemplo, se o valor da variável de modelo for "12345", então ${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ê tiver configurado uma consulta para o painel de registros e selecionar o botão para abrir a Análise de registros, as variáveis do modelo serão resolvidas antes da abertura da Análise de registros.

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

Sintaxe Valor
selecionado		 Expressão do painel de registros resolvidos
${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 à 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 para exibição, a variável do modelo é resolvida. Neste exemplo, se o valor da variável de modelo for "12345", então ${iid} será substituído pela instrução filter (resource.instance_id == '12345') Este filtro corresponde ao horário séries com 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, o exemplo a seguir mostra 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 para consultas MQL:

Sintaxe Selected
Value		 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 por PromQL

Ao definir um gráfico usando PromQL, anexe à string de consulta a variável envolvida por colchetes:

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

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

Assim como no MQL, quando você define um widget com PromQL, a consulta só pode extrair 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, o exemplo a seguir mostra 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 para o PromQL consultas:

Sintaxe Selected
Value		 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 do 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 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 mostra dados de séries temporais, 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 existente. Filtros e variáveis atuais são atualizadas quando a chave do rótulo da coluna da tabela corresponde à chave do rótulo para um filtro ou uma variável.

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

  1. No console do 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 Monitoramento.

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

Excluir um filtro permanente

  1. No console do 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 Monitoramento.

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

A seguir