Criar e gerenciar variáveis e filtros fixados

Neste documento, descrevemos como fixar filtros no painel para que eles sejam permanentes. Os filtros fixados, que permitem modificar os dados exibidos por um painel sem precisar 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 fixado e 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. A barra de ferramentas do painel exibe cada variável, junto com um menu que permite mudar temporariamente o valor da variável.

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.

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

Não é possível aplicar um filtro fixado com widgets individuais. Em vez disso, as seguintes regras são usadas para determinar se o filtro fixado pode mudar os dados exibidos 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 exibidos.

    Por exemplo, suponha que você adicione o filtro fixado cluster_name: mycluster. Em seguida, os gráficos mostram automaticamente apenas as séries temporais com um rótulo cluster_name com um valor de 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éries temporais 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 as 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.

As variáveis 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.

    Existem três tipos de variáveis somente de valor: Personalizada, Entrada de texto e Consulta SQL.

    • Personalizado: use quando você quiser enumerar a lista de todos os valores possíveis e também definir um ou mais valores padrão. Por exemplo, você pode 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. O objetivo dessas variáveis é aplicá-las aos 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 na tabela contém um valor de string exclusivo:

      SELECT log_name
FROM `TABLE_NAME_OF_LOG_VIEW`
GROUP BY log_name

      A variável precisa consultar a mesma tabela que o gráfico.

Para aplicar uma variável a um widget, atualize a consulta contida nele. Se você usa o console do Google Cloud, para variáveis baseadas em rótulos e alguns tipos de widget, é possível realizar essa associação usando uma seleção de menu. No entanto, você sempre pode editar a consulta do widget para aplicar uma variável. Para mais informações, consulte Aplicar uma variável a um widget.

Antes de começar

Para ter 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 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 de painel compatíveis com filtros, 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.
  3. Na seção Filtros, clique em Adicionar um filtro.
  4. Clique em Rótulo e selecione um rótulo. Por exemplo, selecione zone.
  5. 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.

  6. Clique em Valor padrão e selecione o valor padrão ou os valores para o 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 filtro e faça uma seleção no menu.

  7. Clique em Concluído e em Aplicar.

  8. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Crie uma variável

Para criar uma variável que se aplica a widgets específicos do painel, 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.
  3. Na seção Variáveis, clique em Adicionar uma variável.

  4. Selecione o tipo de variável e conclua a caixa de diálogo.

    Para criar uma variável baseada em rótulo, selecione Rótulo. Use essa opção quando você 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 exibidos no painel.

    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 aplicados como padrão.

  5. Insira um nome para a variável. O nome é exibido na barra de ferramentas do painel.

  6. Clique em Concluído e em Aplicar.

  7. Aplique a variável aos widgets do painel de registros e aos widgets configurados com SQL, MQL ou PromQL. Para mais informações, consulte Aplicar uma variável a um widget.

  8. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Aplicar uma variável a um widget

Para aplicar uma variável a um widget, a consulta usada por ele precisa ser editada:

  • Para gráficos que usam consultas SQL, PromQL ou MQL e para widgets do painel de registros, é necessário editar o widget e modificar 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.

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

Criar filtros e variáveis

Console

Para informações sobre como usar o console do Google Cloud para criar filtros e variáveis fixados, consulte estes documentos:

API

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 do filtro ou da variável. A configuração desse campo determina se um usuário pode selecionar exatamente uma opção do menu de valor 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 defina 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 defina o campo stringArrayValue. No exemplo a seguir, há três valores padrão.
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Opcional: para especificar a lista de todos os valores possíveis de uma variável de valor, defina o campo stringArray ou o campo timeSeriesQuery. Se você especificar uma consulta, ela precisa ser uma consulta de análise.

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 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 valor é chamada 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.

O objeto dashboardFilters não lista os widgets aos quais a variável se aplica. Para aplicar uma variável a um widget, modifique a consulta dele.

Sintaxe geral para remover a referência de uma variável

Para todos os widgets, exceto aqueles definidos pelo SQL, use a seguinte sintaxe para aplicar uma variável a uma consulta:

  • Para aplicar uma variável baseada 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 de valor único, 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}"

Confira abaixo a forma renderizada:

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

API

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

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

A consulta executada pelo widget do painel de registros é ilustrada abaixo:

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 resolução pelo painel de registros. Como mencionado anteriormente, quando apenas o valor de uma variável é usado, é necessário usar uma expressão regular como o 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 aplicar uma variável baseada em rótulo a um gráfico com uma consulta PromQL, 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, sendo 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 o 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 o seguinte:

zone=~"${my_value_only_variable}"

API

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

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 o instance_id:

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

zone=~\"${my_value_only_variable}\"

A tabela a seguir ilustra como as variáveis de exemplo são resoluçãos pelo PromQL. Como mencionado anteriormente, quando apenas o valor de uma variável é usado, é necessário usar uma expressão regular como o 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

Quando você quiser aplicar uma variável a um widget definido por SQL, atualize a cláusula WHERE para referenciar o valor da variável. Para todas as variáveis, atribua um prefixo ao nome da variável com o sinal "at", 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.

Console

Como o SQL não interpreta o operador curinga como "qualquer valor", recomendamos que você sempre use uma instrução IF ao aplicar variáveis a uma consulta SQL. O exemplo a seguir ilustra o uso de uma variável somente de valor cujo tipo de dados é uma 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:

  1. Edite o widget.
  2. Na barra de ferramentas, selecione Inserir filtro de variável e selecione a variável que você quer aplicar à cláusula WHERE.
  3. Na caixa de diálogo que aparece, analise o código gerado e clique em Copiar e fechar.

  4. Cole o código copiado no painel Query 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 registros 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 código a seguir é 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)

  5. Clique em Run e em Apply.

  6. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

API

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

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

Por exemplo, o exemplo a seguir mostra uma representação JSON parcial de um gráfico que mostra os resultados de uma consulta SQL. Para oferecer suporte à filtragem dos resultados pelo nome de um registro, uma cláusula WHERE foi adicionada 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 possíveis nomes de registro:

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

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 curinga, o resultado da consulta será uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz em uma tabela.

Gráficos com consultas MQL

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

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

Console

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${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 o instance_id:

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

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 o seguinte:

resource.zone=~'${my_value_only_variable}'

API

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

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 o instance_id:

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

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 o seguinte:

resource.zone=~'${my_value_only_variable}'

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

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

A variável de exemplo é baseada no rótulo de recurso instance_id.
${my_label_based_variable} * filter (true)
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Gráficos com consultas de filtro de monitoramento

Para aplicar uma variável com base em rótulo a um gráfico que tenha uma consulta na forma de um filtro de monitoramento, siga as orientações listadas em Sintaxe geral.

Console

Se você usa o console do Google Cloud para criar seus gráficos e a interface de menu, é possível aplicar uma variável baseada em rótulo a um gráfico usando o campo Aplicar a gráficos da variável ou editando o widget e selecionando a variável baseada em rótulo no menu Filtrar. O menu Filtrar lista todas as variáveis com base em rótulos e todas as chaves de rótulo.

Para aplicar uma variável baseada em valor a esses tipos de gráficos, faça o seguinte:

  1. Edite o gráfico.
  2. No painel de consulta, clique em Adicionar filtro e selecione uma chave de rótulo. Por exemplo, você pode selecionar zona.
  3. No menu Valor, selecione a variável somente de valor.
  4. Clique em Aplicar.
  5. 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 de monitoramento não podem filtrar a série temporal pelo valor em variáveis com base em rótulos. 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})

API

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 de monitoramento não podem filtrar a série temporal pelo valor em variáveis com base em rótulos. 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 de monitoramento. Como mencionado anteriormente, quando apenas o valor de uma variável é usado, é necessário usar uma expressão regular como o 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 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 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. 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 uma variável, 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.
  3. Encontre o filtro ou a variável que você quer modificar e abra a definição.
  4. Depois de concluir as modificações, clique em Aplicar.
  5. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Excluir um filtro ou variável fixada

Para excluir um filtro ou uma variável fixada, 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.
  3. Encontre o filtro ou a variável que você quer remover e clique em Excluir.
  4. Clique em Aplicar.
  5. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

A seguir