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

Artigo
10/15/2024

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 gerenciado do Azure Monitor para métricas de raspagem 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:

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

Registar uma aplicação com o Microsoft Entra ID

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.

Abra seu espaço de trabalho do Azure Monitor no portal do Azure.
Na página Visão geral, anote seu ponto de extremidade de consulta para uso em sua solicitação REST.
Selecione Controlo de acesso (IAM) .
Selecione Adicionar e, em seguida , Adicionar atribuição de função na página Controle de Acesso (IAM).
Na página Adicionar Atribuição de Função, procure Monitoramento.
Selecione Monitoring Data Reader e, em seguida, selecione a guia Membros.
Selecione Selecionar membros.
Procure a aplicação que registou e selecione-a.
Escolha Selecionar.
Selecione Rever + atribuir.

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.

Pedir tokens

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

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.

Ponto de extremidade 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.

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"}'

Etiquetas

Para obter mais informações, consulte Caminho de rótulos : /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.

Nota

__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 baile de formatura OSS, 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 o escopo definido como 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 para uma métrica. Só pode haver um __name__ correspondente de rótulo em uma 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 tempo de raiva for superior a 12 horas, o startTime é definido como endTime – 12h
Intervalo de tempo ignorado
A hora de início e a hora de término são fornecidas e /labels /label/__name__/values ignoradas, e todos os dados retidos no espaço de trabalho do Azure Monitor são consultados.
Funcionalidades experimentais
Recursos experimentais, como exemplares, não são suportados.

Para obter mais informações sobre os limites de métricas do Prometheus, consulte Métricas do Prometheus

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

O Azure managed Prometheus é um sistema que não diferencia maiúsculas de minúsculas. Trata cadeias de carateres, como nomes de métricas, nomes de etiquetas ou valores de etiquetas, como a mesma série temporal, caso se diferenciem de outra série temporal apenas pelas maiúsculas/minúsculas da cadeia de carateres.

Nota

Este comportamento é diferente do Prometheus nativo open source que é um sistema sensível a maiúsculas e minúsculas.
As instâncias autogerenciadas do Prometheus em execução em VMs do Azure, VMSSs ou clusters do Serviço Kubernetes do Azure (AKS) são sistemas que diferenciam maiúsculas de minúsculas.

No Azure managed Prometheus, as seguintes séries temporais são consideradas iguais:

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

Os exemplos acima são uma única série temporal em um banco de dados de séries temporais.

Todas as amostras ingeridas contra eles são armazenadas como se fossem raspadas/ingeridas contra uma única série temporal.
Se os exemplos anteriores forem ingeridos com o mesmo carimbo de data/hora, um deles será descartado aleatoriamente.
O invólucro armazenado no banco de dados de séries temporais e retornado por uma consulta é imprevisível. Invólucros diferentes podem ser devolvidos em momentos diferentes para a mesma série temporal.
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 fazendo uma comparação que não diferencia maiúsculas de minúsculas. Se houver um correspondente que diferencia maiúsculas de minúsculas em uma consulta, ele será automaticamente tratado como um correspondente que não diferencia maiúsculas de minúsculas ao fazer comparações de cadeia de caracteres.

É uma prática recomendada garantir que uma série temporal seja produzida ou raspada usando um único caso consistente.

Em Prometheus de código aberto, as séries temporais acima são tratadas como duas séries temporais diferentes. Todas as amostras raspadas/ingeridas contra eles são armazenadas separadamente.

Perguntas mais 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 ingerir métricas do Prometheus do agente gerenciado aqui.

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

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

Durante as atualizações de nó, você pode ver um intervalo de 1 minuto a 2 minutos nos dados métricos para métricas coletadas de nossos coletores de nível de 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 devido ao nó em que é executado estar a ser atualizado. Esse comportamento não afeta nenhuma das nossas regras de alerta recomendadas.

Próximos passos

Descrição geral da área de trabalho do Azure Monitor
Gerenciar um espaço de trabalho do Azure Monitor
Visão geral do Azure Monitor Managed Service for Prometheus
Consultar métricas do Prometheus usando pastas de trabalho do Azure

Partilhar via