API HTTP do Prometheus e PromQL

Suporte à API HTTP do Prometheus no ClickHouse: gravação remota, leitura remota e consultas PromQL em uma tabela TimeSeries.

O ClickHouse implementa a API HTTP do Prometheus em uma tabela TimeSeries. Um handler atende a gravação remota, a leitura remota, consultas PromQL instantâneas e consultas PromQL de intervalo.

Para expor as métricas do próprio ClickHouse para que um servidor Prometheus as colete, consulte o endpoint de métricas do Prometheus.

​

Pré-requisitos

As etapas de configuração diferem entre o ClickHouse Cloud e o ClickHouse autogerenciado. Siga a seção correspondente à sua implantação.

​

ClickHouse Cloud

O suporte a PromQL no ClickHouse Cloud está em private preview. Os serviços que participam do private preview já possuem a configuração enable_time_series_table e os endpoints da API do Prometheus configurados. Os demais serviços do ClickHouse Cloud não têm essa configuração, e não é possível habilitar o recurso por conta própria nesses serviços. O comando SET enable_time_series_table e a configuração http_handlers descritos nas próximas seções aplicam-se a implantações autogerenciadas.

Em um serviço que participa do private preview, prossiga para Criar uma tabela TimeSeries. O serviço disponibiliza os caminhos de endpoint listados na tabela de endpoints.

​

Autogerenciado: habilite a configuração TimeSeries

Habilite a configuração enable_time_series_table para o usuário que cria e acessa a tabela:

SET enable_time_series_table = 1;

Para solicitações à API HTTP, habilite enable_time_series_table no perfil do usuário da API.

​

Autogerenciado: configure os endpoints da API do Prometheus

Configure um handler roteado por prefixo na porta HTTP principal do ClickHouse:

<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>

<defaults/> preserva os handlers integrados para endpoints como /ping e solicitações SQL. O prefixo acima expõe esses endpoints por meio de um único handler:

Endpoint	Finalidade
/prometheus/api/v1/write	gravação remota do Prometheus
/prometheus/api/v1/read	leitura remota do Prometheus
/prometheus/api/v1/query	consultas PromQL instantâneas
/prometheus/api/v1/query_range	consultas PromQL de intervalo
/prometheus/api/v1/format_query	formatação de expressões PromQL
/prometheus/api/v1/series	Metadados de séries
/prometheus/api/v1/metadata	Metadados da família de métricas

O exemplo omite database e table do handler. Cada solicitação deve fornecer o parâmetro de consulta table (exceto para /format_query, que apenas analisa a expressão PromQL fornecida e não precisa de uma tabela). Ela também pode fornecer database, usar um nome de tabela qualificado, como prometheus.metrics, ou omitir o banco de dados para usar default. Isso permite que um único handler atenda a várias tabelas TimeSeries.

Para usar uma tabela fixa em todas as solicitações, configure-a no handler:

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

Uma tabela configurada no handler não pode ser substituída por parâmetros da solicitação.

Configurações de roteamento e do handler:

Nome	Padrão	Descrição
url_prefix	nenhum	Filtro de regras que corresponde a todos os caminhos de solicitação que começam com o prefixo configurado.
table	nenhum	O nome de uma tabela TimeSeries. Quando omitido, a solicitação deve fornecer o parâmetro de consulta table. O nome configurado pode incluir um banco de dados.
database	nenhum	O banco de dados que contém a tabela. Uma solicitação pode fornecê-lo como parâmetro de consulta. Quando omitido, o ClickHouse usa o banco de dados de um valor table qualificado ou recorre a default.

​

Crie uma tabela TimeSeries

Crie um banco de dados e uma tabela TimeSeries:

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

​

Faça a ingestão de métricas com gravação remota

O ClickHouse oferece suporte ao protocolo gravação remota do Prometheus. Configure o Prometheus para gravar no handler:

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

O Prometheus envia amostras para a tabela prometheus.metrics.

Para agrupar dados de várias solicitações simultâneas de gravação remota em menos partes, habilite as inserções assíncronas adicionando a configuração async_insert à URL (ou habilitando-a no perfil de usuário):

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

O ClickHouse confirma uma solicitação assíncrona de gravação remota somente depois que os dados são gravados em todas as tabelas internas da tabela TimeSeries, independentemente da configuração wait_for_async_insert: o protocolo de gravação remota considera uma gravação confirmada como durável. Se a gravação falhar, a solicitação retorna um erro e o Prometheus tenta novamente.

​

Consulta com PromQL

Use o endpoint de consulta instantânea para avaliar uma expressão PromQL em um momento específico:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

Use o endpoint de consulta por intervalo para avaliar uma expressão em um intervalo de tempo:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

Os endpoints de consulta também aceitam os parâmetros no corpo de um formulário. Sem --get, o curl envia os parâmetros como application/x-www-form-urlencoded via POST:

curl --user default:<password> \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

Use o endpoint de formatação de consulta para analisar e formatar uma expressão PromQL sem avaliá-la:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"

A expressão é retornada serializada a partir da consulta analisada sintaticamente, com os espaços em branco normalizados, os comentários removidos, os parênteses redundantes descartados e as durações convertidas em números de segundos: sum by (job) (http_requests_total{code="200"}) / 2. Esse endpoint não avalia a expressão, portanto não precisa dos parâmetros database e table.

Consulte os recursos do PromQL compatíveis para ver a lista de funções e operadores de agregação usados pela API HTTP, pelo dialeto promql e pelas funções de tabela.

​

Grafana

Configure uma fonte de dados do Prometheus com a URL base terminando antes de /api/v1:

apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

O Grafana acrescenta /api/v1/query ou /api/v1/query_range a esta URL base e adiciona customQueryParameters a cada solicitação.

Com httpMethod: POST, o Grafana envia os parâmetros da consulta no corpo da requisição. O ClickHouse lê o corpo da requisição e a string de consulta da URL, portanto customQueryParameters continua se aplicando. Use POST para expressões PromQL longas, porque uma URL tem limite de comprimento.

Apenas os endpoints de consulta /api/v1/query, /api/v1/query_range e /api/v1/format_query e os endpoints de metadados /api/v1/series, /api/v1/labels, /api/v1/label/<name>/values e /api/v1/metadata estão implementados. /api/v1/series requer pelo menos um seletor de séries match[], oferece suporte aos parâmetros opcionais start, end e limit e retorna a união das séries correspondentes a cada seletor. /api/v1/labels aceita os mesmos parâmetros, com match[] sendo opcional, e retorna os nomes de rótulos ordenados das séries correspondentes (ou de todas as séries quando nenhum seletor é informado). /api/v1/label/<name>/values aceita os mesmos parâmetros que /api/v1/labels e retorna os valores ordenados de um rótulo, sendo que <name> pode opcionalmente usar o escaping U__... do Prometheus para nomes de rótulos que contenham caracteres fora de [a-zA-Z0-9_]. Esses endpoints cobrem o que uma fonte de dados Prometheus no Grafana usa para navegar por rótulos, variáveis de Template e preenchimento automático no construtor de consultas.

​

Pontos de entrada SQL

O ClickHouse usa o mesmo conversor de PromQL para a API HTTP, o dialeto promql e as funções de tabela prometheusQuery e prometheusQueryRange.

Execute PromQL diretamente com o clickhouse-client:

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

Use as funções de tabela para incorporar PromQL a uma consulta SQL:

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

​

Consultar metadados de métricas

O endpoint /prometheus/api/v1/metadata retorna os metadados das métricas armazenados na tabela de destino Metrics da tabela TimeSeries: o tipo, o texto de ajuda e a unidade de cada família de métricas. Ele aceita os seguintes parâmetros do Prometheus na string de consulta da URL:

Parâmetro	Descrição
metric	Retorna metadados apenas para esta família de métricas.
limit	Limita o número de famílias de métricas retornadas. Um valor negativo significa sem limite; zero não retorna nenhuma família de métricas.
limit_per_metric	Limita o número de objetos de metadados retornados para cada família de métricas. Valores zero e negativos significam sem limite.

A tabela de destino Metrics padrão é uma ReplacingMergeTree ordenada pelo nome da família de métricas: ela mantém a entrada de metadados gravada mais recentemente para cada família de métricas. Várias entradas por família são retornadas apenas enquanto a tabela de destino as armazena — antes da mesclagem de suas partes ou quando a tabela é definida com um mecanismo que as preserva.

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

​

Leia métricas com leitura remota

O ClickHouse oferece suporte ao protocolo de leitura remota do Prometheus em /prometheus/api/v1/read.

Configure um servidor Prometheus para ler da mesma tabela TimeSeries:

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>