Crie e faça a gestão de variáveis e filtros fixados

Este documento descreve como pode fixar filtros ao nível do painel de controlo para que estes filtros sejam permanentes. Os filtros fixos, que lhe permitem modificar os dados apresentados por um painel de controlo sem ter de modificar cada widget, têm um estado predefinido e aplicam-se a todo o painel de controlo. A barra de ferramentas do painel de controlo apresenta cada filtro afixado, juntamente com um menu que lhe permite alterar temporariamente o valor do filtro.

As variáveis são semelhantes aos filtros fixos, mas aplicam-se apenas a widgets específicos. Este documento descreve como criar variáveis e como aplicá-las com um widget. Uma variável pode modificar a consulta do widget ou pode controlar a visibilidade de um widget. A barra de ferramentas do painel de controlo apresenta cada variável por nome, juntamente com um menu que lhe permite alterar temporariamente o valor da variável. Para ajudar a distinguir os filtros das variáveis, na barra de ferramentas, o nome de uma variável tem um cifrão $ antes.

Este documento descreve como usar a consola Google Cloud para criar variáveis e filtros fixos. Para obter informações sobre a utilização da API Cloud Monitoring, consulte o artigo Crie e faça a gestão de painéis de controlo por API: filtros de painéis de controlo.

Para obter informações sobre como adicionar e modificar agrupamentos e filtros temporários, que se aplicam apenas à sessão atual, consulte o artigo Adicione filtros temporários a um painel de controlo personalizado.

Esta funcionalidade só é suportada para projetos do Google Cloud . Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

Acerca dos filtros fixados

Um filtro fixado contém uma etiqueta, um ou mais valores predefinidos e uma lista de todos os valores possíveis. A lista de todos os valores possíveis é derivada dinamicamente dos dados de séries cronológicas apresentados no painel de controlo. Para informações sobre a estrutura de um filtro, consulte DashboardFilter.

Não aplica um filtro fixo a widgets individuais. Em alternativa, são usadas as seguintes regras para determinar se o filtro fixo pode alterar os dados apresentados pelo widget:

  • Se o widget apresentar dados que incluem a chave de etiqueta especificada por um filtro fixo e se o widget não especificar um valor para essa chave de etiqueta, o filtro fixo pode alterar os dados apresentados.

    Por exemplo, suponhamos que adiciona o filtro fixo cluster_name: mycluster. Em seguida, os gráficos apresentam automaticamente apenas as séries cronológicas que têm uma etiqueta cluster_name com um valor de mycluster. Da mesma forma, as consultas nos widgets do painel de registos são modificadas para resource.labels."cluster_name"="mycluster", e os gráficos apresentam automaticamente apenas os intervalos temporais que incluem a etiqueta no filtro afixado.

  • Um filtro fixo é ignorado por um widget quando o widget inclui um filtro para a mesma chave de etiqueta ou quando os dados apresentados pelo widget não contêm a chave de etiqueta especificada no filtro fixo.

Acerca das variáveis

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

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

As variáveis podem basear-se em etiquetas ou ter apenas um valor:

  • As variáveis baseadas em etiquetas são como filtros fixos. Estas variáveis contêm uma chave de etiqueta, um ou mais valores de etiqueta predefinidos e uma lista de todos os valores de etiqueta possíveis. A lista de todos os valores possíveis é derivada dinamicamente dos dados de séries cronológicas apresentados no painel de controlo.

  • As variáveis apenas com valores contêm um ou mais valores predefinidos e podem apresentar todos os valores possíveis. Se não especificar um valor predefinido, o operador de carateres universais, (*), é selecionado para o valor predefinido. Para definir o conjunto de todos os valores possíveis, fornece uma matriz de valores ou escreve uma consulta SQL.

    Existem três tipos de variáveis apenas com valores: Personalizada, Introdução 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 predefinidos. Por exemplo, pode definir a lista de todos os valores possíveis como prod, staging, dev e o valor predefinido como prod.

    • Introdução de texto: use quando não souber todos os valores possíveis. Por exemplo, pode querer filtrar por URL, mas quando cria a variável, não conhece a lista exata de URLs. Em seguida, quando usa o menu de filtros do widget, pode introduzir novos URLs e, em seguida, guardar as alterações para a sessão atual ou para a definição da variável.

    • Consulta SQL: use quando quiser gerar a lista de valores possíveis através de uma consulta SQL. Estas variáveis destinam-se a ser aplicadas a gráficos criados através do Log Analytics.

      Para estas variáveis, certifique-se de que o resultado da consulta é uma tabela com uma coluna, que o tipo de dados dessa coluna é string e que cada linha na tabela contém um valor de string único:

      SELECT log_name
FROM `VIEW`
GROUP BY log_name

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

Para aplicar uma variável a um widget, atualiza a consulta emitida pelo widget ou atualiza a visibilidade do widget. Pode sempre editar o widget para atualizar a respetiva consulta. No entanto, para variáveis baseadas em etiquetas e alguns tipos de widgets, pode atualizar a consulta fazendo seleções no menu. Para controlar a visibilidade, tem de editar o widget. Para mais informações, consulte as seguintes secções deste documento:

Antes de começar

Conclua os passos seguintes para o Google Cloud projeto onde quer configurar filtros e variáveis:

Crie e afixe um filtro

Para criar e fixar um filtro que se aplica a todos os widgets do painel de controlo que suportam filtros, faça o seguinte:

  1. Na Google Cloud consola, aceda à página  Painéis de controlo:

    Aceda a Painéis de controlo

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
  3. Selecione um painel de controlo, aceda à barra de ferramentas do painel de controlo e, de seguida, clique em Definições.
  4. Na secção Filtros, clique em Adicionar um filtro.
  5. Clique em Etiqueta e, em seguida, selecione uma etiqueta. Por exemplo, pode selecionar zone.
  6. Para permitir que um utilizador selecione vários valores no menu de valores da variável, selecione Seleção múltipla. Quando a opção Seleção múltipla não está ativada, os utilizadores só podem selecionar uma opção no menu de valores.

  7. Clique em Valor predefinido e, de seguida, selecione o valor ou os valores predefinidos para a etiqueta. Para fazer corresponder todos os valores, selecione *.

    Depois de criar o filtro, este é adicionado à barra de ferramentas do painel de controlo. Para alterar temporariamente o valor do filtro, selecione o filtro e, de seguida, faça uma seleção no menu.

  8. Clique em Concluído e, de seguida, em Aplicar.

  9. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

Crie uma variável

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

  1. Na Google Cloud consola, aceda à página  Painéis de controlo:

    Aceda a Painéis de controlo

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
  3. Selecione um painel de controlo, aceda à barra de ferramentas do painel de controlo e, de seguida, clique em Definições.
  4. Na secção Variáveis, clique em Adicionar uma variável.

  5. Selecione o tipo de variável e, de seguida, conclua a caixa de diálogo.

    Para criar uma variável baseada em etiquetas, selecione Etiqueta. Use esta opção quando quiser uma variável com uma chave de etiqueta e um valor de etiqueta, e que possa ser usada como um filtro. A lista de todos os valores possíveis é derivada dinamicamente dos dados de séries cronológicas apresentados no painel de controlo. O menu Aplicar aos gráficos permite-lhe selecionar widgets cuja consulta vai ser modificada pela variável. Também pode atualizar a consulta editando o widget.

    Para variáveis apenas de valor, tem as seguintes opções:

    • SQL: use esta opção quando quiser que os resultados de uma consulta SQL gerem a lista de todos os valores possíveis.

      Introduza um ou mais valores predefinidos e introduza uma consulta SQL que gera a lista de todos os valores possíveis. Certifique-se de que o resultado da consulta é uma tabela com uma coluna, que o tipo de dados dessa coluna é uma string e que cada linha na tabela contém um valor de string único.

    • Personalizado: use esta opção quando quiser especificar a lista de valores possíveis e também um valor predefinido. Por exemplo, pode definir o campo Valores como prod, staging, dev e definir o Valor predefinido como prod.

    • Introdução de texto: use esta opção quando quiser especificar uma lista de valores que são aplicados como predefinições.

  6. Clique em Concluído e, de seguida, em Aplicar.

  7. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

  8. Aplique a variável aos widgets. Se atualizar a consulta de um widget, quando alterar o valor da variável, a consulta é modificada e os dados apresentados pelo widget são modificados. Também pode usar uma variável para controlar se um widget está visível. Para mais informações, consulte as seguintes secções deste documento:

Defina a visibilidade de um widget

Quando um widget consulta dados, pode usar uma variável para controlar se o widget está visível num painel de controlo. Por exemplo, suponha que um painel de controlo contém widgets que apresentam dados para os seus sistemas de produção e outro conjunto de widgets que apresentam dados para os seus sistemas de preparação. Quando depura durante o desenvolvimento, pode querer ver apenas os dados de preparação. Ao configurar a visibilidade dos widgets do painel de controlo com uma variável, pode alternar entre apenas dados de produção, apenas dados de preparação 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. Na Google Cloud consola, aceda à página  Painéis de controlo:

    Aceda a Painéis de controlo

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Selecione um painel de controlo.
  3. Aceda à barra de ferramentas do widget cuja visibilidade quer configurar e, em seguida, clique em Editar.
  4. No painel Apresentação, expanda Visibilidade do widget.

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

  6. Clique em Concluído e, de seguida, em Aplicar.

  7. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

    O painel de controlo é atualizado. Quando, pelo menos, um widget no painel de controlo está oculto devido aos controlos de visibilidade, o painel de controlo apresenta uma faixa. Para ver todos os widgets, clique em Mostrar todos os widgets.

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

Limitações

Aplicam-se as seguintes limitações quando configura a visibilidade de um widget:

  • Os widgets organizacionais, como o grupo redutível, o cabeçalho de secção e os widgets de vista única, estão sempre visíveis.

  • Pode eliminar uma variável referenciada pelos controlos de visibilidade de um widget. A ação de eliminação de variáveis também remove qualquer referência à variável.

  • Nem todos os painéis de controlo suportam a criação de variáveis. No entanto, se um painel de controlo contiver variáveis, pode usar essas variáveis para gerir a visibilidade dos widgets no painel de controlo.

Atualize a consulta de um widget

Esta secção descreve como incluir variáveis na consulta emitida pelo widget. Como resultado, quando altera o valor da variável, a consulta é modificada e os dados apresentados pelo widget são modificados:

  • Para gráficos que usam consultas SQL ou PromQL e para widgets do painel de registos, tem de editar o widget e modificar a consulta. Esta secção descreve como fazer essas edições.

  • Para gráficos que configurou através de menus ou do modo de filtro direto, o Monitoring edita a consulta quando seleciona o widget através do menu Aplicar a gráficos. Em alternativa, pode editar o widget, aceder ao campo Filtro e, de seguida, selecionar a variável.

Para saber como atualizar a consulta de um widget com uma variável baseada em etiqueta ou uma variável apenas com valor, consulte as seguintes secções:

Crie filtros e variáveis

Consola

Para obter informações sobre como usar a Google Cloud consola para criar filtros fixos e variáveis, consulte os seguintes documentos:

API

Para definir filtros e variáveis fixos, use a estrutura de dados dashboardFilters.

  • Para criar uma variável, defina o valor do campo templateVariable para o nome da variável. Omita este campo ou defina o valor como uma string vazia quando quiser criar um filtro fixo.
  • Para criar um filtro fixo ou uma variável baseada em etiquetas, tem de especificar o campo labelKey. Omita este campo quando quiser uma variável apenas com valor.

  • Defina o valor predefinido para o filtro ou a variável. A configuração deste campo determina se um utilizador pode selecionar exatamente uma opção no menu de valores ou se pode selecionar vários valores.

    • Para definir um único valor predefinido e restringir os utilizadores à seleção de 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 predefinido e permitir que os utilizadores selecionem várias opções no menu de valores, defina o campo valueType como STRING_ARRAY e defina também o campo stringArrayValue. No exemplo seguinte, existem três valores predefinidos.
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Opcional: para especificar a lista de todos os valores possíveis para uma variável apenas de valor, defina o campo stringArray ou o campo timeSeriesQuery. Se especificar uma consulta, tem de ser uma consulta de estatísticas.

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 fixo e duas variáveis:

  • O filtro fixo tem a chave da etiqueta zone, que é apresentada na barra de ferramentas. Os campos valueType e stringValue especificam o valor predefinido único. Para mais informações, consulte a página de referências da API para a estrutura de dados dashboardFilters.

  • A variável baseada em etiquetas tem o nome my_label_based_variable e a respetiva chave de etiqueta é instance_id. O valor predefinido desta variável está definido como um ID de instância específico. Também pode configurar o valor predefinido através de uma matriz. Na barra de ferramentas, o filtro é apresentado com o nome my_label_based_variable.

  • A variável apenas com valor tem o nome my_value_only_variable. Esta entrada não especifica um valor predefinido, pelo que o operador universal, (*), é aplicado automaticamente. Além disso, esta variável usa uma consulta SQL para gerar a lista de valores possíveis para a variável.

Tenha em atenção que o objeto dashboardFilters não apresenta os widgets aos quais a variável se aplica. Em alternativa, atualize a consulta de um widget para depender 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 baseada em etiquetas e ter a chave da etiqueta e o valor da etiqueta resolvidos numa 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 etiquetas, use ${my_label_based_variable.value}. A comparação tem de usar uma expressão regular.

  • Para aplicar apenas o valor de uma variável apenas de valor, use ${my_value_only_variable}. Para variáveis apenas com valores, não inclua uma cláusula .value. A comparação tem de usar uma expressão regular.

Widgets do painel de registos

Para aplicar uma variável a um widget do painel Registos, atualize o painel de consultas. A sintaxe destes widgets segue a especificada em Sintaxe geral.

Consola

Por exemplo, a seguinte consulta 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 etiquetas:

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

Como outro exemplo, considere uma variável apenas com valores, value_only_severity_variable, e suponha que, no menu de valores, estão selecionados três valores: ERROR, INFO e NOTICE. Em seguida, adicione o seguinte ao painel de consulta do widget do painel de registos:

severity =~ "${value_only_severity_variable}"

A imagem seguinte ilustra o formulário renderizado:

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

API

Por exemplo, o JSON seguinte ilustra como atualizar a consulta de um widget do painel de registos com uma variável baseada em etiquetas:

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

Por exemplo, a seguinte consulta 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 etiquetas:

"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 apenas com valores, value_only_severity_variable, e suponha que são selecionados três valores no menu: ERROR, INFO e NOTICE. Em seguida, adicione o seguinte ao painel de consulta do widget do painel de registos:

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

A imagem seguinte ilustra a consulta conforme executada pelo widget do painel de registos:

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

Se tiver configurado uma consulta para o painel de registos e, em seguida, selecionar o botão para abrir o Explorador de registos, as variáveis são resolvidas antes de o Explorador de registos ser aberto.

A tabela seguinte ilustra como as variáveis de exemplo são resolvidas pelo painel de registos. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão do painel de registos resolvida
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

A variável de exemplo baseia-se na etiqueta do 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 tenha uma consulta PromQL para depender de uma variável baseada em etiquetas, siga as orientações indicadas em Sintaxe geral.

Consola

Por exemplo, a seguinte consulta baseia-se na variável baseada em etiquetas my_label_based_variable, que é resolvida numa expressão de filtro:

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

Também pode modificar a consulta para resolver apenas o valor de uma variável. O exemplo seguinte usa uma expressão regular para comparar o valor de uma consulta baseada em etiquetas com instance_id:

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

Se tiver uma variável apenas com valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável apenas com valor, a consulta incluiria algo como o seguinte:

zone=~"${my_value_only_variable}"

API

Por exemplo, o JSON seguinte ilustra uma consulta que depende da variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa 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 pode modificar a consulta para resolver apenas o valor de uma variável. O exemplo seguinte usa uma expressão regular para comparar o valor de uma consulta baseada em etiquetas com 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 tiver uma variável apenas com valor, omita a cláusula .value. Por exemplo, para filtrar por zona usando uma variável apenas com valor, a consulta incluiria algo como o seguinte:

zone=~\"${my_value_only_variable}\"

A tabela seguinte ilustra como as variáveis de exemplo são resolvidas pelo PromQL. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão PromQL resolvida
${my_label_based_variable} 12345 instance_id == '12345'

A variável de exemplo baseia-se na etiqueta do 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 quiser atualizar um widget definido por 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 símbolo "@" antes do nome da variável, por exemplo: @variable_name. Para variáveis baseadas em etiquetas, acrescente .value ao nome da variável, @my_label_based_variabe.value.

Para consultas SQL, a substituição de variáveis baseia-se no BigQuery e é segura contra injeção de SQL. Para mais informações, consulte o artigo Executar consultas parametrizadas.

Consola

Uma vez que o SQL não interpreta o operador de carateres universais como "qualquer valor", recomendamos que use sempre uma declaração IF quando usar variáveis numa consulta SQL. O exemplo seguinte ilustra a utilização de uma variável apenas 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 aos utilizadores selecionar vários valores, tem de converter o valor da variável num tipo de dados GoogleSQL através da função CAST. A seguinte consulta ilustra esta sintaxe:

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

A declaração IF apresentada nos exemplos anteriores é recomendada porque o SQL não interpreta o operador de carateres universais como "qualquer valor". Por conseguinte, se omitir a declaração IF e selecionar o operador de carateres universais, o resultado da consulta é uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz numa 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, de seguida, selecione a variável cuja cláusula WHERE quer atualizar.
  3. Na caixa de diálogo apresentada, reveja o código gerado e, de seguida, clique em Copiar e fechar.

  4. Cole o código copiado no painel Consulta e faça as edições necessárias.

    Por exemplo, suponhamos que cria uma variável denominada LogName que gera uma lista de nomes de registos e produz o resultado numa tabela com uma única coluna denominada log_name. Em seguida, cria um gráfico, seleciona Inserir filtro de variável e, de seguida, seleciona a variável LogName. É gerado o seguinte código:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    Neste exemplo, tem de editar o código gerado e substituir LogName = por log_name = para que a junção de tabelas possa ocorrer:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Clique em Executar e, de seguida, em Aplicar.

  6. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

API

Uma vez que o SQL não interpreta o operador de carateres universais como "qualquer valor", recomendamos que use sempre uma declaração IF quando usar variáveis numa consulta SQL. O exemplo seguinte ilustra a utilização de uma variável apenas de valor cujo tipo de dados é uma string:

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

Por exemplo, o seguinte mostra uma representação JSON parcial de um gráfico que apresenta os resultados de uma consulta SQL. Para suportar a filtragem dos resultados pelo nome de um registo, foi adicionada uma cláusula WHERE que faz referência à variável denominada 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 envia uma consulta para determinar a lista de nomes de registos 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
    }
  }
],

Quando a opção de menu da variável permite aos utilizadores selecionar vários valores, tem de converter o valor da variável num tipo de dados GoogleSQL através da função CAST. A seguinte consulta ilustra esta sintaxe:

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

A declaração IF apresentada nos exemplos anteriores é recomendada porque o SQL não interpreta o operador de carateres universais como "qualquer valor". Por conseguinte, se omitir a declaração IF e selecionar o operador de carateres universais, o resultado da consulta é uma tabela vazia. No segundo exemplo, a função UNNEST converte a matriz numa tabela.

Gráficos com consultas de filtros de monitorização

Para atualizar um gráfico que tenha uma consulta sob a forma de um filtro de monitorização para depender de uma variável baseada em etiquetas, siga as orientações indicadas na secção Sintaxe geral.

Consola

Se usar a Google Cloud consola para criar os gráficos e usar a interface orientada por menus, pode atualizar a consulta do gráfico usando o campo Aplicar a gráficos da variável ou editando o widget e selecionando a variável baseada em etiquetas no menu Filtro. O menu Filtro apresenta todas as variáveis baseadas em etiquetas e todas as chaves de etiquetas.

Para atualizar a consulta de um gráfico de modo a depender de uma variável baseada em valor, faça o seguinte:

  1. Edite o gráfico.
  2. No painel de consulta, clique em Adicionar filtro e selecione uma chave de etiqueta. Por exemplo, pode selecionar zona.
  3. No menu Valor, selecione a variável apenas de valor.
  4. Clique em Aplicar.
  5. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

Por exemplo, o JSON seguinte ilustra uma consulta que depende de uma variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa 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 sob a forma de um filtro de monitorização não podem filtrar a série cronológica pelo valor numa variável baseada em etiquetas; no entanto, pode filtrar por variáveis apenas de valor. Por exemplo, a consulta seguinte mostra o valor do campo Filtros de uma consulta que filtra por zone, com base no valor de uma variável apenas 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 seguinte ilustra uma consulta que depende de uma variável baseada em etiquetas, my_label_based_variable, a ser resolvida numa 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 sob a forma de um filtro de monitorização não podem filtrar a série cronológica pelo valor numa variável baseada em etiquetas; no entanto, pode filtrar por variáveis apenas de valor. Por exemplo, a seguinte consulta mostra o campo "filter" de uma consulta que filtra por zone, com base no valor de uma variável apenas 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 seguinte ilustra como as variáveis de exemplo são resolvidas pelo filtro de monitorização. Conforme mencionado anteriormente, quando apenas o valor de uma variável é usado, tem de usar uma expressão regular como o operador de comparação:

Sintaxe Selected
Value		 Expressão de filtro resolvida
${my_label_based_variable} 12345 resource.instance_id == "12345"

A variável de exemplo baseia-se na etiqueta do recurso instance_id.
${my_label_based_variable} * Omitido
${my_label_based_variable.value} 12345 Não suportado
${my_label_based_variable.value} * Não suportado
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Modifique um filtro ou uma variável fixada

Para alterar temporariamente o valor de qualquer filtro apresentado na barra de ferramentas do painel de controlo, clique no nome do filtro e introduza um valor ou faça uma seleção no menu.

Se o painel de controlo contiver uma tabela que apresenta dados de séries cronológicas, pode adicionar filtros temporários ou modificar filtros e variáveis permanentes através do botão Filtrar painel de controlo para este valor de uma célula. Quando selecionado, este botão aplica um novo filtro temporário ou atualiza o valor de um filtro ou uma variável existente. Os filtros e as variáveis existentes são atualizados quando a chave da etiqueta da coluna da tabela corresponde à chave da etiqueta de um filtro ou de uma variável.

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

  1. Na Google Cloud consola, aceda à página  Painéis de controlo:

    Aceda a Painéis de controlo

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
  3. Na barra de ferramentas do painel de controlo, clique em Definições.
  4. Encontre o filtro ou a variável que quer modificar e expanda a respetiva definição.
  5. Depois de concluir as modificações, clique em Aplicar.
  6. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

Elimine um filtro ou uma variável fixada

Para eliminar um filtro fixo ou uma variável, faça o seguinte:

  1. Na Google Cloud consola, aceda à página  Painéis de controlo:

    Aceda a Painéis de controlo

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
  3. Na barra de ferramentas do painel de controlo, clique em Definições.
  4. Encontre o filtro ou a variável que quer remover e, de seguida, clique em Eliminar.
  5. Clique em Aplicar.
  6. Para guardar o painel de controlo modificado, clique em Guardar na barra de ferramentas.

O que se segue?