Como usar o MQL da API Monitoring

Nesta página, descrevemos como fornecer consultas da linguagem de consulta do Monitoring (MQL) à API Cloud Monitoring.

Esta página não abrange a criação de consultas MQL. Para um conjunto de consultas de exemplo, consulte Exemplos. A referência de MQL fornece uma referência abrangente da linguagem.

Para informações gerais sobre políticas de alertas com base em MQL, consulte Políticas de alertas com MQL.

Como usar MQL da API

É possível fornecer consultas MQL nos seguintes locais na API Monitoring:

Para selecionar e manipular dados de série temporal usando MQL, chame o método timeSeries.query. Para exemplos, consulte Como usar timeSeries.query.
Para selecionar e manipular dados de série temporal para gráficos, forneça a consulta as especificações TimeSeriesQuery ao chamar o método dashboards.create. Por exemplo, consulte Como criar gráficos.
Para criar condições baseadas em MQL em políticas de alertas, descreva a condição da política de alertas com o tipo de condição MonitoringQueryLanguageCondition quando você chamar alertPolicies.create. Para exemplos, consulte Como criar condições para políticas de alertas.

Recuperação de dados com `timeSeries.query`

Para recuperar dados de série temporal da API com uma consulta MQL, use o método timeSeries.query.

O método timeSeries.query usa uma estrutura mínima como esta em JSON:

{
  "query": string
}

Para o valor do campo query, especifique uma string em MQL, conforme mostrado nestas consultas simples:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}

Se a consulta criar uma tabela de saída não alinhada, você precisará fornecer uma duração usando a operação de tabela within ao chamar a API diretamente. Ferramentas de gráficos, como o Metrics Explorer, fornecem uma duração de consulta padrão. A consulta no snippet JSON a seguir funciona no editor de código MQL no Metrics Explorer, mas falha quando fornecida diretamente à API:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}

Com a adição de uma operação de tabela within à consulta anterior, o exemplo anterior pode ser fornecido diretamente à API:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}

Para testar a API, use a ferramenta APIs Explorer na página de referência do timeSeries.query. Para ver uma introdução à ferramenta APIs Explorer, consulte APIs Explorer.

Outra maneira de testar a API é colocar a consulta em um arquivo de texto e, em seguida, executar a consulta usando curl. O exemplo a seguir passa a consulta no arquivo query.json para o método timeSeries.query:

curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query

Para ver mais informações sobre o uso de curl, consulte Como invocar curl.

Se for bem-sucedida, a consulta retornará uma tabela contendo a série temporal solicitada. A tabela é dividida em dois componentes:

O timeSeriesDescriptor descreve as chaves, os valores e os pontos de dados do rótulo na tabela. Ele não contém dados. Ele simplesmente descreve os dados.
O timeSeriesData contém os dados descritos no descritor de série temporal. Esses dados são apresentados como uma matriz de pares.
- O primeiro item do par, labelValues, registra um conjunto de valores para os rótulos listados no descritor de série temporal.
- O segundo, pointData, é uma matriz incorporada de pares de valor/carimbo de data/hora, que representam os dados coletados com o conjunto especificado de valores de rótulo.

A resposta, ligeiramente reformatada, tem esta aparência:

[{
  "timeSeriesTable": {
    "timeSeriesDescriptor": {
      "labelDescriptors": [
        { "key": "resource.project_id" },
        { "key": "resource.zone" },
        { "key": "resource.instance_id" },
        { "key": "metric.instance_name" }
      ],
      "valueDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ],
      "pointDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ]
    },
    "timeSeriesData": [
      {
        "labelValues": [
          { "stringValue": "632526624816" },
          { "stringValue": "us-central1-a" },
          { "stringValue": "5106847938297466291" },
          { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
        ],
        "pointData": [
          {
            "values": [
              {
                "doubleValue": 0.063896992710942874
              }
            ],
            "timeInterval": {
              "startTime": "1969-12-31T23:59:59.999999Z",
              "endTime": "2020-03-02T20:17:00Z"
            }
          },
          { ... additional value/timestamp pairs ...}
        ]
      },
      { ... additional labelValue/pointData pairs ...},
    ]
  }

Como criar gráficos

É possível usar o método dashboards.create para criar painéis de forma programática e os gráficos que eles contêm.

A única diferença entre a criação de gráficos baseados em MQL e outros gráficos é o tipo de consulta TimeSeriesQuery usado para preencher o conjunto de dados do gráfico.

Como criar um gráfico baseado em MQL

Para consultas do MQL, use a consulta como o valor do campo de string timeSeriesQueryLanguage na matriz DataSet do gráfico.

Veja a seguir a definição de painel simples que inclui o MQL:

{
  "displayName": "Dashboard for MQL chart (API)",
  "gridLayout": {
    "widgets": [
      {
        "title": "Min/Max Compute Engine CPU utilization",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
              },
              "plotType": "LINE",
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Isso cria um painel intitulado "Painel para gráfico MQL (API)" no projeto. O painel contém um gráfico chamado "Utilização mín/máx de CPU do Compute Engine", que mostra duas linhas, uma para os valores mais altos e outra para os mais baixos.

O gráfico mostra a série temporal com os valores mais altos e mais baixos.

Para mais informações sobre esse exemplo de consulta, consulte Como combinar seleções com union.

Como criar um gráfico

É possível colocar o JSON do painel em um arquivo e, em seguida, transmitir o arquivo para gcloud beta monitoring dashboards create ou usar curl para postá-lo em https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. Para mais exemplos, consulte Como criar um painel. Para ver mais informações sobre o uso de curl, consulte Como invocar curl.

Para informações gerais sobre como criar gráficos e painéis, consulte Como gerenciar painéis pela API. Para ver o material de referência, consulte Dashboards.

Como criar condições para políticas de alertas

Use o método alertPolicies.create para criar políticas de alerta programaticamente.

A única diferença entre a criação de políticas de alertas baseadas em MQL e outras políticas de alerta é o tipo de Condition usado. Caso contrário, você criará essas políticas como qualquer outra.

Veja a seguir uma consulta MQL simples para uma condição da política de alertas que testa a utilização de CPU do Compute Engine superior a 15%:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by sliding(5m), mean(val())
| condition val() > 0.15 '10^2.%'

Para mais informações sobre a operação de alerta condition com o MQL, consulte Políticas de alertas com o MQL.

Como criar a política de alertas

Para criar uma política de alertas baseada em uma consulta MQL, use o tipo de condição AlertPolicy MonitoringQueryLanguageCondition. O MonitoringQueryLanguageCondition tem a seguinte estrutura:

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

O valor do campo query é uma string de consulta de alertas MQL em formato conciso ou rígido. Os exemplos neste documento estão em formato conciso. Para mais informações sobre formas rígidas, consulte Consultas de formato rígido.

O campo duration especifica o período em que cada avaliação da consulta precisa gerar um valor true antes que a política de alertas seja acionada. Para mais informações, consulte Comportamento de políticas de alertas com base em métricas. O valor precisa ser um número de minutos, expresso em segundos; por exemplo, 600s para uma duração de 10 minutos.

O campo trigger especifica quantas séries temporais precisam atender à condição durante o período duration, expressas como uma contagem ou uma porcentagem. O valor padrão é uma contagem de 1. Para mais informações, consulte Trigger.

No exemplo de consulta de alertas, com duração de 10 minutos e uma contagem de acionadores de 1, a estrutura tem esta aparência:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
  "duration": "600s",
  "trigger" : {
     "count": 1
  }
}

Use essa estrutura como o valor de um campo conditionMonitoringQueryLanguage em uma condição que, por sua vez, é incorporada em uma estrutura de política de alertas. Para mais informações sobre essas estruturas, consulte AlertPolicy.

Veja a seguir uma política mínima completa com uma condição MonitoringQueryLanguageCondition em JSON:

{
  "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
  "combiner":"OR",
  "conditions":[
    {
      "displayName":"MQL-based utilization condition, API",

      "conditionMonitoringQueryLanguage":
      {
        "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
        "duration": "600s",
        "trigger" : {
           "count": 1
        },
     },
   }
  ],
}

Como criar uma política de alertas

Para criar a política, coloque o JSON da política de alertas em um arquivo e passe o arquivo para gcloud alpha monitoring policies create ou use curl para postá-lo em https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

Para mais informações sobre a API Monitoring para políticas de alertas, consulte Como gerenciar políticas de alertas por API.

Para ver mais informações sobre o uso de curl, consulte Como invocar curl.

Como invocar o `curl`

Cada invocação curl inclui um conjunto de argumentos, seguido pelo URL de um recurso da API. Os argumentos comuns incluem um código de projeto do Google Cloud e um token de autenticação. Esses valores são representados aqui pelas variáveis de ambiente PROJECT_ID e TOKEN.

Talvez você também precise especificar outros argumentos para elementos diferentes, como o tipo da solicitação HTTP. Por exemplo, -X DELETE. Como a solicitação padrão é GET, os exemplos não fazem essa especificação.

Cada invocação do curl tem esta estrutura geral:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Para usar curl, especifique o código do projeto e um token de acesso. Para reduzir a digitação e os erros, é possível colocá-los em variáveis de ambiente e passá-los para curl dessa maneira.

Para definir essas variáveis, faça o seguinte:

Crie uma variável de ambiente para manter o ID do projeto de escopo de um escopo de métricas. Estas etapas chamam a variável PROJECT_ID:
```
PROJECT_ID=a-sample-project
```
Faça a autenticação na Google Cloud CLI:
```
gcloud auth login
```
Opcional. Para não precisar especificar o ID do projeto com cada comando gcloud, defina-o como o padrão usando a CLI gcloud:
```
gcloud config set project ${PROJECT_ID}
```
Crie um token de autorização e colete-o em uma variável de ambiente. Estas etapas chamam a variável TOKEN:
```
TOKEN=`gcloud auth print-access-token`
```
É necessário atualizar o token de acesso periodicamente. Se algum comando parar de funcionar com um erro de falta de autenticação, será necessário emiti-lo novamente.
Para verificar se você recebeu um token de acesso, faça o echo da variável TOKEN:
```
echo ${TOKEN}
ya29.GluiBj8o....
```