Compartilhar via

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

  • Artigo

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

Este artigo descreve como consultar um workspace do Azure Monitor usando o PromQL por meio da API REST. Para saber mais sobre PromQL, confira Consultando Prometheus.

Pré-requisitos

Para consultar um workspace do Azure Monitor usando o PromQL, você precisa dos seguintes pré-requisitos:

  • Um cluster do Azure Kubernetes ou um cluster de Kubernetes remoto.
  • Serviço gerenciado para Prometheus do Azure Monitor para extração de métricas de um cluster do 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 Monitor do Azure, autentique-se usando o Microsoft Entra ID. A API oferece suporte à 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 as etapas abaixo:

  1. Registre um aplicativo com o Microsoft Entra ID.
  2. Conceda ao aplicativo acesso ao workspace do Azure Monitor.
  3. Solicitar um token.

Registrar um aplicativo 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

Conceda ao aplicativo acesso ao workspace

Atribua a função de Leitor de dados de monitoramento ao seu aplicativo para que ele possa consultar os dados do workspace do Azure Monitor.

  1. Abra o workspace do Azure Monitor no portal do Azure.

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

  3. Selecione IAM (Controle de acesso) .

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

    Captura de tela mostrando a página de visão geral do workspace do Azure Monitor

  5. Na página Adicionar página de atribuição de função, pesquise Monitoramento.

  6. Selecione Monitoramento de Leitor de Dados e selecione a guia Membros.

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

  7. Selecione Selecionar membros.

  8. Pesquise pelo aplicativo que você registrou e selecione-o.

  9. Escolha Selecionar.

  10. Selecione Examinar + atribuir.

    Captura de tela mostrando a página “Adicionar atribuição de função” e a seleção de membros.

Você criou o registro do seu aplicativo e atribuiu a ele acesso para consultar dados do seu espaço de trabalho do Azure Monitor. Agora você pode gerar um token e usá-lo em uma consulta.

Solicitar um token

Enviar a solicitação a seguir 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'

Amostra de corpo de resposta:

{
    "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 solicitações HTTP a seguir.

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.

Uma captura de tela mostrando o ponto de extremidade de consulta na página de visão geral do workspace do Azure Monitor.

APIs com suporte

As seguintes consultas são compatíveis:

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, confira 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, confira 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

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 de rótulo

Para obter mais informações, confira Valores de rótulo
Caminho: /api/v1/label/__name__/values.

Observação

__name__ é a única versão com suporte dessa API e retorna todos os nomes de métrica. Outros /api/v1/label/<label_name>/valores não têm suporte.

Exemplo:

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

Para ver a especificação completa das APIs Prom do OSS, confira API HTTP do Prometheus.

Limitações de API

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

  • O escopo da consulta deve ser uma métrica
    Todas as consultas de busca de série temporal (/series ou /query ou /query_range) devem conter um __name__ correspondente de rótulo. Ou seja, cada consulta deve ter como escopo uma métrica. Só pode haver um __name__ correspondente de rótulo em uma consulta.
  • A consulta /series não dá suporte ao filtro de expressão regular
  • Intervalo de tempo com suporte
    • A API /query_range dá suporte a 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. Isto 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 será 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.
  • Recursos experimentais
    Não há suporte para recursos experimentais, como exemplares.

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

Diferenciar maiúsculas de minúsculas

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

Observação

Esse comportamento é diferente do Prometheus de código aberto nativo, que é um sistema que diferencia maiúsculas de minúsculas.
Instâncias do Prometheus autogerenciadas em execução em VMs do Azure, VMSSs ou clusters do Serviço de Kubernetes do Azure (AKS) são sistemas que diferenciam maiúsculas de minúsculas.

No Prometheus gerenciado do Azure, 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 acima são uma única série temporal em um banco de dados de séries temporais.

  • Todas as amostras ingeridas contra elas são armazenadas como se fossem extraída/ingeridas em uma única série temporal.
  • Se os exemplos acima forem ingeridos com o mesmo carimbo de data/hora, um deles será removido aleatoriamente.
  • O uso de letras maiúsculas e minúsculas armazenadas no banco de dados de séries temporais e retornadas por uma consulta é imprevisível. Maiúsculas e minúsculas diferentes podem ser retornadas em momentos diferentes na 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 cadeias de caracteres.

É uma melhor prática garantir que uma série temporal seja produzida ou extraída usando um único caso consistente.

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

Perguntas frequentes

Esta seção fornece respostas para 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 a partir do agente gerenciado aqui.

Por que faltam métricas que têm dois rótulos com o mesmo nome, mas com maiúsculas e minúsculas diferentes?

O Prometheus gerenciado pelo Azure é um sistema que não diferencia maiúsculas de minúsculas. Ele trata as cadeias de caracteres, como nomes de métricas, nomes de rótulos ou valores de rótulos, como a mesma série temporal se elas diferirem de outra série temporal apenas pelo caso da cadeia de caracteres. Para obter mais informações, consulte Visão geral das métricas do Prometheus.

Vejo algumas lacunas nos dados de métrica. Por que isso está ocorrendo?

Durante as atualizações de nó, você pode ver uma lacuna de 1 minuto a 2 minutos nos dados de métrica para métricas coletadas de nossos coletores de nível de cluster. Essa lacuna ocorre porque o nó em que os dados são executados está sendo atualizado como parte de um processo normal de atualização. 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 autenticação automática. Esse comportamento é esperado e ocorre devido à atualização do nó em que ele é executado. Esse comportamento não afeta nenhuma das nossas regras de alerta recomendadas.

Próximas etapas

Visão geral do workspace do Azure Monitor
Gerenciar um workspace do Azure Monitor
Visão Geral do serviço gerenciado do Azure Monitor para Prometheus
Consultar métricas do Prometheus usando pastas de trabalho do Azure