Criar e gerenciar painéis por API

Neste documento, descrevemos como criar e gerenciar painéis personalizados e os widgets neles usando o recurso Dashboard na API Cloud Monitoring. Os exemplos aqui ilustram como gerenciar seus painéis usando curl para invocar a API e mostram como usar a Google Cloud CLI. Também é possível gerenciar seus painéis personalizados pelo Console do Google Cloud. No entanto, a API oferece uma maneira programática de gerenciar vários painéis ao mesmo tempo.

O endpoint é compatível com os métodos de gerenciamento e configuração de painéis a seguir:

É possível invocar a API diretamente usando o utilitário curl ou a CLI do Google Cloud.

Não é possível recuperar, editar ou excluir painéis predefinidos.

Sobre os painéis

Ao criar um painel, você precisa especificar quais componentes ou widgets serão exibidos e qual será o layout desses widgets. Também é possível adicionar rótulos e filtros ao painel. Os marcadores podem ajudar você a encontrar um painel ou indicar o tipo de conteúdo nele.

Layouts de painel

Os layouts definem como os componentes de um painel são ordenados. A API fornece os seguintes layouts:

  • GridLayout: divide o espaço disponível em colunas verticais com larguras iguais e organiza um conjunto de widgets usando uma estratégia de linha primeiro.

  • MosaicLayout: divide o espaço disponível em uma grade. Cada widget pode ocupar um ou mais blocos de grade.

  • RowLayout: divide o espaço disponível em linhas e organiza um conjunto de widgets na horizontal em cada uma delas.

  • ColumnLayout: divide o espaço disponível em colunas verticais e organiza um conjunto de widgets na vertical em cada uma delas.

Por exemplo, veja a seguir a representação JSON de um painel em RowLayout com três widgets Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widgets do painel

Um widget inclui um único componente de painel, além da configuração de como ele será apresentado nesse painel. Um painel pode ter mais de um widget. Há vários tipos de objetos Widget:

  • O widget XyChart mostra dados nos eixos X e Y.

    Esse widget mostra um conjunto de dados que pode ser de séries temporais ou gerado por uma consulta SQL. Esse widget permite associar os dados do gráfico ao eixo Y à esquerda ou à direita. Quando vários tipos de métricas são representados no gráfico, é possível usar os dois eixos Y. O widget XyChart oferece suporte aos seguintes estilos de exibição:

    • Gráficos de linhas
    • Gráficos de barras
    • Gráficos de área empilhadas
    • Mapas de calor

  • Widgets que aparecem em uma dimensão, como o valor mais recente:

    • PieChart: exibe os valores mais recentes de uma coleção de série temporal, em que cada série temporal contribui com uma fatia do gráfico de pizza.

    • Scorecard: exibe o valor mais recente de uma série temporal e como esse valor se relaciona a um ou mais limites.

    • TimeSeriesTable: mostra o valor mais recente ou um valor agregado para cada série temporal. As tabelas são compatíveis com a personalização. Por exemplo, é possível codificar células com cores e configurar nomes de colunas e alinhamento de dados.

  • Widgets que mostram informações sobre a política de alertas ou incidentes:

    • AlertChart: exibe um resumo de uma política de alertas de condição única. Esse widget exibe dados como um gráfico de linhas, mostra o limite e lista o número de incidentes abertos.

    • IncidentList: mostra uma lista de incidentes. É possível configurar o widget para mostrar incidentes de políticas de alerta ou de tipos de recursos específicos.

  • Widgets que mostram entradas de registro e erros:

  • Widgets de texto e organização:

    • CollapsibleGroup: exibe uma coleção de widgets. É possível ocultar a visualização de um grupo.

    • SingleViewGroup: exibe um widget em uma coleção de widgets. Você pode selecionar qual widget será exibido.

    • SectionHeader: cria um divisor horizontal no seu painel e uma entrada na tabela de conteúdo do painel.

    • Text: exibe o conteúdo textual como texto bruto ou string do Markdown.

    Para incluir os widgets de texto e organização em um painel, ele precisa ter um MosaicLayout.

Além desses objetos, é possível adicionar um marcador vazio a um painel.

O exemplo a seguir mostra a representação JSON de um widget XyChart com o eixo Y direito configurado:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Rótulos de painel

Os rótulos ajudam a gerenciar e organizar os painéis. Por exemplo, você pode adicionar um rótulo chamado prod para indicar que o painel mostra dados de séries temporais e de registros dos seus recursos de produção. Como alternativa, adicione o rótulo playbook para indicar que o painel contém informações para ajudar a resolver falhas.

Adicionar rótulos a um painel é opcional.

Por exemplo, o exemplo a seguir mostra um objeto Dashboard que especifica o rótulo chamado playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Como o exemplo anterior ilustra, o campo labels é implementado como um map, em que os campos key e value são strings. Ao adicionar um rótulo a um painel, defina key como o nome do rótulo e o campo value como uma string vazia.

Filtros e variáveis do painel

Ao projetar um painel, você pode identificar várias maneiras de visualizar os dados que ele mostra. Por exemplo, suponha que um painel mostre dados de séries temporais para suas instâncias de máquina virtual (VM). Talvez você queira acessar os dados de série temporal de todas as VMs e conferir apenas os dados que estão em uma zona específica. Nessa situação, recomendamos que você crie um filtro fixado ou uma variável e defina o valor padrão desse filtro para a zona mais visualizada.

Os filtros fixados são aplicados a todos os widgets do painel que oferecem suporte ao rótulo especificado no filtro, a menos que o widget contenha um filtro com a mesma chave de rótulo. Por exemplo, quando um gráfico inclui o filtro zone = us-central1-a, ele ignora um filtro fixado com a chave de rótulo zone. Da mesma forma, esse filtro é ignorado por gráficos que não têm um rótulo com uma chave de zone.

As variáveis são como filtros fixados, mas se aplicam apenas a widgets específicos. As variáveis podem ser baseadas em rótulos, como os filtros fixados, ou podem ter apenas um valor. As variáveis somente de valor contêm um ou mais valores padrão e uma lista de todos os valores possíveis. Se você não especificar um valor padrão, o padrão será definido como o operador curinga (*). Para definir o conjunto de todos os valores possíveis, forneça uma matriz de valores ou escreva uma consulta SQL.

Para filtros e variáveis fixadas, a barra de ferramentas do painel mostra cada variável com um menu que permite mudar temporariamente o valor da variável. A mesma estrutura de dados é usada para representar filtros e variáveis fixados. Para ver mais informações, consulte DashboardFilter.

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 somente 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 derefernciar 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 fazer referência ao 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 abaixo é 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 no formato 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} * ".*"

Crie um painel

Para criar um novo painel personalizado, invoque o método dashboards.create e inclua nele o layout e os widgets a serem exibidos no painel.

Quando você cria um painel, a API gera o dashboard_id automaticamente. Se você quiser especificar um dashboard_id personalizado, defina o campo name de um objeto Dashboard. O formato do campo de nome é assim:

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

API

Para criar um novo painel, envie uma solicitação POST para o endpoint Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Para criar um painel em um projeto, use o comando gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

Por exemplo, se você quiser duplicar um painel, faça o seguinte:

  1. Siga as etapas em Acessar o painel para fazer o download da definição do painel original.
  2. Edite o JSON retornado para remover os campos etag e name e mude o valor do campo displayName.
  3. Execute o comando para criar o painel.

Para mais informações, consulte a referência de gcloud monitoring dashboards create.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para criar um painel usando o Terraform, use o recurso google_monitoring_dashboard.

No comando, defina os seguintes campos:

  • dashboard_json: a representação JSON do painel, usando o formato Dashboards.

    Para conferir exemplos desse formato, liste seus painéis usando o APIs Explorer ou abra um painel no console do Google Cloud e confira as representações JSON.

  • parent: o nome totalmente qualificado do projeto. Por exemplo, você pode definir esse campo como "projects/PROJECT_ID", em que PROJECT_ID é o ID do seu projeto do Google Cloud.

Os exemplos criam um painel de amostra usando o arquivo my-dashboard.json. É possível gerenciar seu painel pelo console do Google Cloud.

Para outras configurações do painel, consulte Exemplos de painéis e layouts.

Excluir painéis

Para excluir um painel personalizado, invoque o método dashboards.delete e especifique o painel que você quer excluir.

API

Para excluir um painel personalizado, envie uma solicitação DELETE para o endpoint Dashboard, qualificado com o código do painel a ser excluído.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Se for bem-sucedido, o método retornará uma resposta vazia. Caso contrário, um erro será exibido.

gcloud

Para excluir um painel personalizado, use gcloud monitoring dashboards delete e especifique o ID totalmente qualificado do painel a ser excluído:

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Para mais informações, consulte a referência de gcloud monitoring dashboards delete.

Terraform

Você pode excluir recursos usando o Terraform. Para informações sobre como excluir recursos, consulte o comando destroy do Terraform.

Listar painéis

Para listar todos os painéis que pertencem a um projeto, invoque o método dashboards.list e especifique o ID do projeto.

API

Para listar todos os painéis personalizados de um projeto, envie o código do projeto para o endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Para listar todos os painéis personalizados de um projeto, use o comando gcloud monitoring dashboards list:

gcloud monitoring dashboards list

Para mais informações, consulte a referência gcloud monitoring dashboards list.

Terraform

Não é possível usar o Terraform para enviar uma consulta ao seu projeto com a resposta sendo uma lista de painéis. No entanto, é possível visualizar esses painéis usando o console do Google Cloud.

Os exemplos retornam os painéis personalizados associados ao seu projeto.

Paginar a resposta da lista

O método dashboards.list suporta paginação. Com ela, em vez de ver todos os resultados ao mesmo tempo, você os visualiza em uma página de cada vez.

API

Na página inicial da lista de resultados, especifique o parâmetro de consulta pageSize com a solicitação:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

O método retorna a primeira página da lista e o nextPageToken. Exemplo:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Em cada página restante, você precisa incluir o nextPageToken correspondente na solicitação.

gcloud

Para especificar o número de recursos por página, passe a sinalização --page-size com o comando. Exemplo:

gcloud monitoring dashboards list --page-size=1

Terraform

Não é possível usar o Terraform para enviar uma consulta ao seu projeto com a resposta sendo uma lista paginada de painéis. No entanto, é possível visualizar esses painéis usando o console do Google Cloud.

Acessar painel

Para receber um painel personalizado específico para um projeto, invoque o método dashboards.get, qualificado com o código do painel.

API

Para receber um painel personalizado específico, envie o código dele para o endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

O método retorna uma resposta semelhante ao exemplo a seguir:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

Para receber um painel personalizado específico, use o comando gcloud monitoring dashboards describe e especifique o ID do painel:

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

O comando retorna o painel solicitado:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Para mais informações, consulte a referência gcloud monitoring dashboards describe.

Terraform

Não é possível usar o Terraform para enviar uma consulta ao seu projeto com a resposta sendo um painel individual. No entanto, é possível visualizar esses painéis usando o console do Google Cloud.

Atualizar painel

Para atualizar um painel personalizado existente, invoque o método dashboards.patch. Para receber o valor etag atual, invoque o método dashboards.get, e ele estará incluído na resposta.

API

Para atualizar um painel personalizado, envie uma solicitação PATCH para o endpoint Dashboard e forneça o objeto Dashboard revisado e o valor etag da resposta dashboards.get mais recente.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

O exemplo anterior atualiza um painel personalizado existente usando o arquivo my-updated-dashboard.json. A resposta, que inclui um novo valor de etag, é uma cópia da listagem de painéis atualizada.

gcloud

Para atualizar um painel personalizado, use gcloud monitoring dashboards update, especifique o ID do painel a ser atualizado e forneça as alterações no painel.

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

Para mais informações, consulte a referência gcloud monitoring dashboards update.

O exemplo anterior atualiza um painel personalizado usando o arquivo my-updated-dashboard.json. A resposta, que inclui um novo valor de etag, é uma cópia da listagem de painéis atualizada.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para atualizar um painel usando o Terraform, use o recurso Terraform google_monitoring_dashboard.

No comando, defina os seguintes campos:

  • dashboard_json: a representação JSON do painel, usando o formato Dashboards.

  • parent: o nome totalmente qualificado do projeto. Por exemplo, você pode definir esse campo como "projects/PROJECT_ID", em que PROJECT_ID é o ID do seu projeto do Google Cloud.

A seguir