Introdução ao PromQL
O PromQL (Prometheus Query Language) é a linguagem de consulta usada no Prometheus, uma ferramenta popular de monitoramento e alertas para sistemas e serviços em tempo real. O Prometheus foi projetado para coletar métricas de sistemas e aplicações, armazená-las em uma base de dados de séries temporais e permitir análises flexíveis dessas métricas. O PromQL é a ferramenta central para realizar essas análises, permitindo que usuários explorem dados, criem painéis de visualização e configurem alertas com base em condições específicas.
As consultas no PromQL são expressões que geralmente começam com o nome de uma métrica e podem incluir modificadores, filtros por rótulos (labels) e operadores. Rótulos são metadados associados às métricas que ajudam a identificar a origem ou o contexto dos dados, como o nome de um serviço ou região geográfica. Por exemplo, uma métrica chamada http_requests_total pode ter rótulos como method="GET" e status="200", permitindo segmentar os dados de acordo com critérios específicos.
O PromQL também suporta funções poderosas para análise avançada, como rate() para calcular taxas de variação de métricas, avg_over_time() para calcular médias ao longo de um intervalo de tempo e histogram_quantile() para trabalhar com histogramas. Essas funcionalidades fazem do PromQL uma ferramenta robusta e flexível para explorar dados de monitoramento e diagnosticar problemas em sistemas complexos.
Tipos de Dados
No PromQL, os tipos de dados disponíveis são específicos para operar sobre séries temporais e oferecem a base para consultas e manipulações de métricas. Abaixo estão os principais tipos de dados usados no PromQL.
Séries Temporais Instantâneas (Instant Vector)
Um instant vector representa um conjunto de séries temporais no ponto de tempo atual ou em um momento específico. Cada série temporal no vetor é identificada por sua métrica e rótulos associados. Ele é o tipo mais básico e frequentemente utilizado em consultas. É utilizado para visualizar os valores atuais de métricas. É base para aplicar funções comorate(),avg(),sum()etc.
http_requests_totalEsse comando retorna todas as séries temporais da métrica
http_requests_totalno instante atual.
Séries Temporais em Intervalo (Range Vector)
Um range vector representa uma série temporal em um intervalo de tempo especificado. Em vez de capturar apenas o valor no momento atual, ele inclui todos os pontos de dados em um intervalo, com base na resolução de amostragem da métrica. Necessário para funções que analisam séries temporais ao longo do tempo, comorate(),increase()ouavg_over_time().
http_requests_total[5m]Esse comando retorna todas as séries temporais da métrica
http_requests_totalnos últimos 5 minutos.
Escalar (Scalar)
Um scalar é um valor numérico simples, que não está associado a nenhuma métrica ou série temporal. É usado em cálculos ou para comparar séries temporais com valores fixos.1 + 2Esse comando retorna o valor escalar
3.
- String
Uma string é um valor textual que aparece apenas em situações específicas, como em respostas de funções que retornam mensagens de erro ou na execução de operadores específicos. No PromQL, as strings são raramente usadas em consultas diretas.
Funções
Abaixo podemos conferir algumas das funções mais usadas:
rate()
Essa função calcula a taxa de variação por segundo de uma métrica cumulativa (ou counter), como o número total de requisições HTTP (http_requests_total). É amplamente usada para medir a frequência de eventos ao longo do tempo.
rate(http_requests_total[5m])
# Aqui, calcula-se a taxa média de requisições por segundo nos últimos 5 minutos.increase()
Similar aorate(), mas em vez de calcular a taxa, esta função calcula o aumento absoluto de uma métrica cumulativa em um intervalo de tempo.
increase(http_requests_total[1h])
# Esse comando mostra o número total de requisições realizadas na última hora.sum()
Realiza uma soma de valores de séries temporais, frequentemente agrupadas por rótulos. É útil para consolidar métricas de múltiplas fontes.
sum(rate(http_requests_total[5m]))
# Aqui, calcula-se a taxa total de requisições combinando todas as séries temporais.avg()
Calcula a média de valores de séries temporais, podendo ser agrupada por rótulos. É útil para avaliar métricas como carga média de CPU.
avg(rate(cpu_usage_seconds_total[5m]))max()emin()
Identificam o maior ou menor valor entre séries temporais. São úteis para encontrar picos ou valores mínimos em métricas.
max(rate(cpu_usage_seconds_total[5m]))histogram_quantile()
Trabalha com histogramas para calcular percentis, como tempo de resposta de uma API. Essa função é essencial para monitorar métricas de desempenho.
histogram_quantile(0.95, sum(rate(request_duration_seconds_bucket[5m])) by (le))
# Aqui, calcula-se o 95º percentil do tempo de resposta em um intervalo de 5 minutos.irate()
Parecida comrate(), mas calcula a taxa instantânea, ou seja, a derivada entre os dois últimos pontos da série temporal. É usada quando valores mais recentes são mais relevantes.
irate(http_requests_total[5m])avg_over_time()
Calcula a média de valores ao longo de um intervalo de tempo. É útil para analisar comportamento histórico.
avg_over_time(memory_usage_bytes[1h])sum_over_time()
Soma os valores de uma métrica ao longo de um intervalo de tempo.
sum_over_time(errors_total[30m])count()ecount_over_time()
Ocount()conta o número de séries temporais em uma consulta, enquantocount_over_time()conta os pontos de dados em um intervalo de tempo.
count_over_time(cpu_usage_seconds_total[10m])
Prometheus API
A API do Prometheus fornece uma interface para interação com os dados de séries temporais armazenados pelo Prometheus, além de informações sobre o servidor. Ela é baseada em REST e permite realizar consultas, recuperar metadados, explorar o estado atual e histórico das métricas e até configurar alertas ou regras (dependendo da implementação).
Querying Endpoints
Esses endpoints permitem executar consultas no PromQL e recuperar resultados de séries temporais. São os mais usados para integrar aplicações e painéis com o Prometheus. O path para esse endpont é /api/v1/query. Exemplo:
$ curl -gks http://localhost:9090/api/v1/query?query=node_disk_read_bytes_total | jq
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {
"__name__": "node_disk_read_bytes_total",
"device": "md127",
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"value": [
1737334984.673,
"0"
]
},
{
"metric": {
"__name__": "node_disk_read_bytes_total",
"device": "nvme0n1",
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"value": [
1737334984.673,
"16002048"
]
},
{
"metric": {
"__name__": "node_disk_read_bytes_total",
"device": "sda",
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"value": [
1737334984.673,
"3627627520"
]
},
{
"metric": {
"__name__": "node_disk_read_bytes_total",
"device": "sdb",
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"value": [
1737334984.673,
"8499200"
]
},
{
"metric": {
"__name__": "node_disk_read_bytes_total",
"device": "sdc",
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"value": [
1737334984.673,
"13655040"
]
}
]
}
}
# Obter o valor apenas para o SDA:
$ curl -gks "http://localhost:9090/api/v1/query?query=last_over_time(node_disk_read_bytes_total[1m])" | jq '.data.result[] | select(.metric.device == "sda") | .value[1]'
"3627627520"
Query_range
É usado no Querying Endpoint para executar consultas ao longo de um intervalo de tempo, retornando resultados de séries temporais completas. Exemplo:
# Apenas um exemplo de como usar:
$ curl -gks 'http://localhost:9090/api/v1/query_range?query=up&start=2025-01-19T19:00:30.781Z&end=2025-01-19T20:11:00.781Z&step=1m'
{"status":"success","data":{"resultType":"matrix","result":[{"metric":{"__name__":"up","instance":"localhost:9100","job":"my_linux_with_node_exporter"},"values":[[1737313230.781,"1"],[1737313290.781,"1"],[1737313350.781,"1"],[1737313410.781,"1"],[1737313470.781,"1"],[1737313530.781,"1"],[1737313590.781,"1"],[1737313650.781,"1"],[1737313710.781,"1"],[1737313770.781,"1"],[1737313830.781,"1"],[1737313890.781,"1"],[1737313950.781,"1"],[1737314010.781,"1"],[1737314070.781,"1"],[1737314130.781,"1"],[1737314190.781,"1"],[1737314250.781,"1"],[1737314310.781,"1"],[1737314370.781,"1"],[1737314430.781,"1"],[1737314490.781,"1"],[1737314550.781,"1"],[1737314610.781,"1"],[1737314670.781,"1"],[1737314730.781,"1"],[1737314790.781,"1"],[1737314850.781,"1"],[1737314910.781,"1"],[1737314970.781,"1"],[1737315030.781,"1"],[1737315090.781,"1"],[1737315150.781,"1"],[1737315210.781,"1"],[1737315270.781,"1"],[1737315330.781,"1"],[1737315390.781,"1"],[1737315450.781,"1"],[1737315510.781,"1"],[1737315570.781,"1"],[1737315630.781,"1"],[1737315690.781,"1"],[1737315750.781,"1"],[1737315810.781,"1"],[1737315870.781,"1"],[1737315930.781,"1"],[1737315990.781,"1"],[1737316050.781,"1"],[1737316110.781,"1"],[1737316170.781,"1"],[1737316230.781,"1"],[1737316290.781,"1"],[1737316350.781,"1"],[1737316410.781,"1"],[1737316470.781,"1"],[1737316530.781,"1"],[1737316590.781,"1"],[1737316650.781,"1"],[1737316710.781,"1"],[1737316770.781,"1"],[1737316830.781,"1"],[1737316890.781,"1"],[1737316950.781,"1"],[1737317010.781,"1"],[1737317070.781,"1"],[1737317130.781,"1"],[1737317190.781,"1"],[1737317250.781,"1"],[1737317310.781,"1"],[1737317370.781,"1"],[1737317430.781,"1"]]}]}
A query acima está consultando o estado da métrica up no Prometheus ao longo de um intervalo de tempo específico. O step representa o intervalo de tempo entre os pontos de amostragem dentro do período especificado. Ela retorna se os alvos monitorados estavam ativos (1) ou inativos (0) em cada ponto no tempo.
- Intervalo de tempo consultado: De
2025-01-19T19:00:30.781Zaté2025-01-19T20:11:00.781Z(horário em UTC). - Frequência de amostragem: A cada 1 minuto (
step=1m), será registrado o estado da métrica para cada alvo.
Metadata Endpoints
Esses endpoints fornecem informações sobre as métricas disponíveis, seus rótulos e outras informações associadas. O path para esse endpont é /api/v1/series. Ele lista todas as séries temporais que correspondem a um filtro de rótulos em um intervalo de tempo. Exemplo:
$ curl -ksg 'http://localhost:9090/api/v1/series?' --data-urlencode 'match[]=node_network_receive_bytes_total' --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
O parâmetro match[]=node_network_receive_bytes_total retorna todas as séries temporais associadas à métrica. Já match[]=process_start_time_seconds{job="prometheus"} vai retornar a série temporal da métrica process_start_time_seconds para o job prometheus. Essa métrica indica o momento em que o processo Prometheus foi iniciado (em segundos desde o Unix epoch).
Labels
Lista os nomes de todos os rótulos usados em métricas armazenadas pelo Prometheus. Exemplo:
$ curl 'localhost:9090/api/v1/labels'
{
"status": "success",
"data": [
"__name__",
"call",
"code",
"config",
"dialer_name",
"endpoint",
"event",
"goversion",
"handler",
"instance",
"interval",
"job",
"le",
"listener_name",
"name",
"quantile",
"reason",
"role",
"scrape_job",
"slice",
"version"
]
}
Obter o valor de um label
Lista todos os valores únicos de um rótulo específico. Exemplo:
# Sintaxe: /api/v1/label/<label_name>/values
$ curl -gks http://localhost:9090/api/v1/label/bios_version/values | jq
{
"status": "success",
"data": [
"5407"
]
}
$ curl -gks http://localhost:9090/api/v1/label/sysname/values | jq
{
"status": "success",
"data": [
"Linux"
]
}
Status Endpoints
Esse endpoint oferece informações sobre o status do servidor Prometheus. Abaixo podemos conferir alguns paths.
/api/v1/status/config
Retorna a configuração atual do Prometheus. Exemplo:
$ curl -gks http://localhost:9090/api/v1/status/config | jq
{
"status": "success",
"data": {
"yaml": "global:\n scrape_interval: 15s\n scrape_timeout: 10s\n scrape_protocols:\n - OpenMetricsText1.0.0\n - OpenMetricsText0.0.1\n - PrometheusText1.0.0\n - PrometheusText0.0.4\n evaluation_interval: 1m\nruntime:\n gogc: 75\nscrape_configs:\n- job_name: my_linux_with_node_exporter\n honor_timestamps: true\n track_timestamps_staleness: false\n scrape_interval: 15s\n scrape_timeout: 10s\n scrape_protocols:\n - OpenMetricsText1.0.0\n - OpenMetricsText0.0.1\n - PrometheusText1.0.0\n - PrometheusText0.0.4\n metrics_path: /metrics\n scheme: http\n enable_compression: true\n follow_redirects: true\n enable_http2: true\n static_configs:\n - targets:\n - localhost:9100\n"
}
}
/api/v1/status/flags
Mostra os flags de inicialização usados no servidor Prometheus. Exemplo:
$ curl -gks http://localhost:9090/api/v1/status/flags | jq
{
"status": "success",
"data": {
"agent": "false",
"alertmanager.drain-notification-queue-on-shutdown": "true",
"alertmanager.notification-queue-capacity": "10000",
"auto-gomaxprocs": "true",
"auto-gomemlimit": "true",
"auto-gomemlimit.ratio": "0.9",
"config.auto-reload-interval": "30s",
"config.file": "/etc/prometheus/prometheus.yml",
"enable-feature": "",
"log.format": "logfmt",
"log.level": "info",
"query.lookback-delta": "5m",
"query.max-concurrency": "20",
"query.max-samples": "50000000",
"query.timeout": "2m",
"rules.alert.for-grace-period": "10m",
"rules.alert.for-outage-tolerance": "1h",
"rules.alert.resend-delay": "1m",
"rules.max-concurrent-evals": "4",
"scrape.adjust-timestamps": "true",
"scrape.discovery-reload-interval": "5s",
"scrape.timestamp-tolerance": "2ms",
"storage.agent.no-lockfile": "false",
"storage.agent.path": "data-agent/",
"storage.agent.retention.max-time": "0s",
"storage.agent.retention.min-time": "0s",
"storage.agent.wal-compression": "true",
"storage.agent.wal-compression-type": "snappy",
"storage.agent.wal-segment-size": "0B",
"storage.agent.wal-truncate-frequency": "0s",
"storage.remote.flush-deadline": "1m",
"storage.remote.read-concurrent-limit": "10",
"storage.remote.read-max-bytes-in-frame": "1048576",
"storage.remote.read-sample-limit": "50000000",
"storage.tsdb.allow-overlapping-compaction": "true",
"storage.tsdb.delayed-compaction.max-percent": "10",
"storage.tsdb.head-chunks-write-queue-size": "0",
"storage.tsdb.max-block-chunk-segment-size": "0B",
"storage.tsdb.max-block-duration": "1d12h",
"storage.tsdb.min-block-duration": "2h",
"storage.tsdb.no-lockfile": "false",
"storage.tsdb.path": "data/",
"storage.tsdb.retention.size": "0B",
"storage.tsdb.retention.time": "15d",
"storage.tsdb.samples-per-chunk": "120",
"storage.tsdb.wal-compression": "true",
"storage.tsdb.wal-compression-type": "snappy",
"storage.tsdb.wal-segment-size": "0B",
"web.config.file": "",
"web.console.libraries": "console_libraries",
"web.console.templates": "consoles",
"web.cors.origin": ".*",
"web.enable-admin-api": "false",
"web.enable-lifecycle": "false",
"web.enable-otlp-receiver": "false",
"web.enable-remote-write-receiver": "false",
"web.external-url": "",
"web.listen-address": "0.0.0.0:9090",
"web.max-connections": "512",
"web.max-notifications-subscribers": "16",
"web.page-title": "Prometheus Time Series Collection and Processing Server",
"web.read-timeout": "5m",
"web.remote-write-receiver.accepted-protobuf-messages": "prometheus.WriteRequest,io.prometheus.write.v2.Request",
"web.route-prefix": "/",
"web.user-assets": "",
"write-documentation": "false"
}
}
/api/v1/status/runtimeinfo
Exibe informações em tempo de execução, como uso de memória e tempo de atividade. Exemplo:
$ curl -gks http://localhost:9090/api/v1/status/runtimeinfo | jq
{
"status": "success",
"data": {
"startTime": "2025-01-20T00:31:54.113414545Z",
"CWD": "/prometheus",
"reloadConfigSuccess": true,
"lastConfigTime": "2025-01-20T00:31:54Z",
"corruptionCount": 0,
"goroutineCount": 31,
"GOMAXPROCS": 6,
"GOMEMLIMIT": 22605377126,
"GOGC": "75",
"GODEBUG": "",
"storageRetention": "15d"
}
}
/api/v1/status/targets
Retorna os alvos monitorados pelo Prometheus, incluindo quais estão ativos ou inativos.
$ curl -ks http://localhost:9090/api/v1/targets | jq
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "localhost:9100",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"__scrape_interval__": "15s",
"__scrape_timeout__": "10s",
"job": "my_linux_with_node_exporter"
},
"labels": {
"instance": "localhost:9100",
"job": "my_linux_with_node_exporter"
},
"scrapePool": "my_linux_with_node_exporter",
"scrapeUrl": "http://localhost:9100/metrics",
"globalUrl": "http://chireadan:9100/metrics",
"lastError": "",
"lastScrape": "2025-01-20T01:26:26.733636176Z",
"lastScrapeDuration": 0.11509056,
"health": "up",
"scrapeInterval": "15s",
"scrapeTimeout": "10s"
}
],
"droppedTargets": [],
"droppedTargetCounts": {
"my_linux_with_node_exporter": 0
}
}
}
Rules and Alerts Endpoints
Esses endpoints são usados para consultar regras de gravação e alertas configurados no Prometheus.
/api/v1/rules
Retorna todas as regras configuradas, incluindo regras de gravação e de alertas./api/v1/alerts
Lista todos os alertas atualmente em estado firing.