Esta página foi traduzida pela API Cloud Translation.
Switch to English

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 baseadas 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:

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 semelhante a esta em JSON:

{
  "query": string
}

Para o valor do campo query, especifique uma string no MQL:

{

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

Para testar a API, use a ferramenta API Explorer na página de referência do timeSeries.query. Para uma introdução à ferramenta API Explorer, consulte API 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 mais informações sobre como usar 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 mais informações sobre como usar 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.

A consulta MQL usada em uma condição de alerta precisa estar em um formato restrito. É possível escrever a consulta de formulário restrito manualmente, mas é mais fácil usar o Editor de consultas e clicar em Adicionar como se fosse salvar a condição. A consulta de formulário restrito é fornecida para confirmação. Você pode copiar essa versão da consulta para usar com a API. Depois, clique em Cancelar para abandonar a condição na IU.

Veja mais informações em Consultas de formulário restrito.

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

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

Veja a seguir o formato rígido da consulta:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| align mean_aligner()
| window 5m
| condition value.utilization > .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 alerta MQL.

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 saber mais informações, consulte Comportamento do alerta. 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 de duration. O valor padrão é 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 | align mean_aligner() | window 5m | condition value.utilization > 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 | align mean_aligner() | window 5m | condition value.utilization > 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 mais informações sobre como usar 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:

  1. Crie uma variável de ambiente para manter o código do projeto de escopo de um escopo de métricas (ou o projeto host do espaço de trabalho). Estas etapas chamam a variável PROJECT_ID:

    PROJECT_ID=a-sample-project
    
  2. Faça a autenticação no SDK do Cloud:

    gcloud auth login
    
  3. Opcional. Para evitar a necessidade de especificar o código do projeto com cada comando gcloud, defina o código do projeto como padrão usando o SDK do Cloud:

    gcloud config set project ${PROJECT_ID}
    
  4. 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.

  5. Para verificar se você recebeu um token de acesso, faça o echo da variável TOKEN:

    echo ${TOKEN}
    ya29.GluiBj8o....