Compartilhar via

Consultar métricas do Prometheus com a API e o PromQL

O serviço gerenciado do Azure Monitor para Prometheus coleta métricas de clusters do Azure Kubernetes e as armazena em um espaço de trabalho do Azure Monitor. PromQL (Prometheus query language), é uma linguagem de consulta funcional que permite consultar e agregar dados de séries temporais. Use o PromQL para consultar e agregar métricas armazenadas em um espaço de trabalho do Azure Monitor.

Este artigo descreve como consultar um espaço de trabalho do Azure Monitor usando o PromQL por meio da API REST. Para obter mais informações sobre o PromQL, consulte Consultando prometheus.

Pré-requisitos

Para consultar um espaço de trabalho do monitor do Azure usando o PromQL, você precisa dos seguintes pré-requisitos:

  • Um cluster Kubernetes do Azure ou cluster Kubernetes remoto.
  • Serviço gerido do Azure Monitor para recolha de métricas com Prometheus de um cluster Kubernetes.
  • Um espaço de trabalho do Azure Monitor onde as métricas do Prometheus estão sendo armazenadas.

Autenticação

Para consultar seu espaço de trabalho do Azure Monitor, autentique-se usando a ID do Microsoft Entra. A API suporta a autenticação do Microsoft Entra usando credenciais de cliente. Registre um aplicativo cliente com o Microsoft Entra ID e solicite um token.

Para configurar a autenticação do Microsoft Entra, siga os passos abaixo:

  1. Registre um aplicativo com o Microsoft Entra ID.
  2. Conceda acesso para o aplicativo ao seu espaço de trabalho do Azure Monitor.
  3. Solicite um token.

Registar uma aplicação com o Microsoft Entra ID

  1. Para registrar um aplicativo, siga as etapas em Registrar um aplicativo para solicitar tokens de autorização e trabalhar com APIs.

Permitir que seu aplicativo acesse seu espaço de trabalho

Atribua a função Leitor de Dados de Monitoramento ao seu aplicativo para que ele possa consultar dados do seu espaço de trabalho do Azure Monitor.

  1. Abra seu espaço de trabalho do Azure Monitor no portal do Azure.

  2. Na página Visão geral, anote o seu endpoint de consulta para uso na sua solicitação REST.

  3. Selecione Controlo de acesso (IAM) .

  4. Selecione Adicionar e, em seguida , Adicionar atribuição de função na página Controle de Acesso (IAM).

    Uma captura de tela mostrando a página de visão geral do espaço de trabalho do Azure Monitor.

  5. Na página Atribuição de Função, procure Monitorização.

  6. Selecione Monitoring Data Reader e, em seguida, selecione a guia Membros.

    Uma captura de tela mostrando a página Adicionar atribuição de função.

  7. Selecione Selecionar membros.

  8. Procure a aplicação que registou e selecione-a.

  9. Escolha Selecionar.

  10. Selecione Analisar + atribuir.

    Uma captura de tela mostrando a página Adicionar atribuição de função, selecionar membros.

Criou o registo da sua aplicação e atribuiu-lhe acesso a dados de consulta a partir da sua área de trabalho do Azure Monitor. Agora você pode gerar um token e usá-lo em uma consulta.

Solicite um token

Envie a seguinte solicitação no prompt de comando ou usando um cliente como o Insomnia ou o do PowerShell.Invoke-RestMethod

curl -X POST 'https://login.microsoftonline.com/<tenant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

Corpo da resposta da amostra:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Salve o token de acesso da resposta para uso nas seguintes solicitações HTTP.

Endpoint de consulta

Encontre o ponto de extremidade de consulta do seu espaço de trabalho do Azure Monitor na página de visão geral do espaço de trabalho do Azure Monitor.

Uma captura de tela mostrando o endpoint da consulta na página de visão geral do espaço de trabalho do Azure Monitor.

APIs suportadas

As seguintes consultas são suportadas:

Consultas instantâneas

Para obter mais informações, consulte Consultas instantâneas.

Caminho: /api/v1/query

Exemplos:

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization: Bearer <access token>'

Consultas de intervalo

Para obter mais informações, consulte Consultas de intervalo.

Caminho: /api/v1/query_range

Exemplos:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Série

Para obter mais informações, consulte Série.

Caminho: /api/v1/series

Exemplos:

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Rótulos / Etiquetas

Para obter mais informações, consulte Rótulos.

Caminho: /api/v1/labels

Exemplos:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Valores do rótulo

Para obter mais informações, consulte Valores de rótulo.

Caminho: /api/v1/label/__name__/values.

Observação

__name__ é a única versão suportada desta API e devolve todos os nomes de métricas. Nenhum outro /api/v1/label/<label_name>/values é suportado.

Exemplo:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Para obter a especificação completa das APIs do SOA Prom, consulte Prometheus HTTP API.

Limitações da API

As limitações a seguir são adicionais às detalhadas na especificação Prometheus.

  • A consulta deve ter como escopo uma métrica.

    Todas as consultas de busca de séries temporais (/series ou /query ou /query_range) devem conter um correspondente de rótulo __name__. Ou seja, cada consulta deve ter um escopo relacionado a uma métrica. Só pode haver uma etiqueta __name__ numa consulta.

  • A consulta /series não suporta o filtro de expressão regular

  • Intervalo de tempo suportado

    • /query_range API suporta um intervalo de tempo de 32 dias. Este é o intervalo de tempo máximo permitido, incluindo seletores de intervalo especificados na própria consulta. Por exemplo, a consulta rate(http_requests_total[1h] para as últimas 24 horas significaria, na verdade, que os dados estão sendo consultados por 25 horas. Isso vem do intervalo de 24 horas mais a 1 hora especificada na própria consulta.
    • A API /series busca dados para um intervalo de tempo máximo de 12 horas. Se endTime não for fornecido, endTime = time.now(). Se o intervalo de tempo for maior que 12 horas, o startTime é definido como endTime – 12h.

  • Intervalo de tempo ignorado

    A hora de início e a hora de término fornecidas com /labels e /label/__name__/values são ignoradas, e todos os dados retidos no espaço de trabalho do Azure Monitor são consultados.

  • Características experimentais

    Funcionalidades experimentais, como exemplos, não têm suporte.

Para obter mais informações sobre os limites das métricas Prometheus, consulte Prometheus metrics.

Sensível às maiúsculas e minúsculas

O serviço gerenciado do Azure Monitor para Prometheus é um sistema que não diferencia maiúsculas de minúsculas. Ele trata cadeias de caracteres (como nomes de métricas, nomes de rótulos ou valores de rótulo) como a mesma série temporal se elas diferirem de outra série temporal apenas pelo caso da cadeia de caracteres.

Observação

Esse comportamento é diferente do Prometheus nativo de código aberto, que é um sistema que diferencia maiúsculas de minúsculas. As instâncias autogeridas do Prometheus em execução em máquinas virtuais do Azure, conjuntos de dimensionamento de máquinas virtuais ou clusters Azure Kubernetes Service são sistemas que distinguem maiúsculas de minúsculas.

No serviço gerenciado para Prometheus, as seguintes séries temporais são consideradas as mesmas:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Os exemplos anteriores são uma única série temporal numa base de dados de séries temporais. As seguintes considerações são aplicáveis:

  • Todas as amostras ingeridas para eles são armazenadas como se fossem coletadas ou processadas para uma série temporal única.
  • Se os exemplos anteriores forem ingeridos com a mesma marca temporal, um deles será descartado aleatoriamente.
  • O invólucro armazenado no banco de dados de séries temporais e retornado por uma consulta é imprevisível. A mesma série temporal pode retornar invólucros diferentes em momentos diferentes.
  • Qualquer nome de métrica ou correspondente de nome/valor de rótulo presente na consulta é recuperado do banco de dados de séries temporais por meio de uma comparação que não diferencia maiúsculas de minúsculas. Se houver um correspondente que diferencia maiúsculas de minúsculas numa consulta, ele será automaticamente tratado como um correspondente que não diferencia maiúsculas de minúsculas em comparações de cadeias textuais.

É uma prática recomendada usar um formato consistente para produzir ou extrair dados de uma série temporal.

O Prometheus de código aberto trata os exemplos anteriores como duas séries temporais diferentes. Todas as amostras raspadas ou ingeridas relativamente a eles são armazenadas separadamente.

Perguntas frequentes

Esta secção fornece respostas a perguntas comuns.

Estou perdendo todas ou algumas das minhas métricas. Como posso solucionar problemas?

Você pode usar o guia de solução de problemas para ingestão de métricas de Prometheus do agente gerenciado.

Por que estou perdendo métricas que têm dois rótulos com o mesmo nome, mas caixa diferente?

O Prometheus gerido pela Azure é um sistema que não distingue maiúsculas de minúsculas. Trata cadeias de caracteres, como nomes de métricas, nomes de etiquetas ou valores de etiquetas, como sendo a mesma série temporal, caso se diferenciem de outra série temporal apenas pela diferença de maiúsculas e minúsculas da cadeia de caracteres. Para obter mais informações, consulte Visão geral das métricas do Prometheus.

Vejo algumas lacunas nos dados métricos, por que isso está ocorrendo?

Durante as atualizações dos nós, pode ver um intervalo de 1 a 2 minutos nos dados métricos para métricas recolhidas pelos nossos coletores ao nível do cluster. Essa lacuna ocorre porque o nó no qual os dados são executados está sendo atualizado como parte de um processo de atualização normal. Esse processo de atualização afeta destinos em todo o cluster, como kube-state-metrics e destinos de aplicativos personalizados especificados. Isso ocorre quando o cluster é atualizado manualmente ou por meio da atualização automática. Este comportamento é esperado e ocorre porque o nó em que é executado está a ser atualizado. Esse comportamento não afeta nenhuma das nossas regras de alerta recomendadas.

Próximos passos

Visão geral do espaço de trabalho do Azure MonitorGerir um espaço de trabalho do Azure MonitorVisão geral do Serviço Gerido para Prometheus do Azure MonitorConsultar métricas do Prometheus usando folhas de trabalho do Azure