Protocolos do Prometheus e PromQL

Suporte à API HTTP do Prometheus no ClickHouse: gravação remota, leitura remota, consultas PromQL e métricas do servidor.

​

Exponha métricas do servidor ClickHouse

Se você estiver usando o ClickHouse Cloud, poderá expor métricas para o Prometheus usando a integração com o Prometheus.

Configure uma porta dedicada quando um servidor Prometheus precisar coletar as próprias métricas do ClickHouse:

<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
    <histograms>true</histograms>
    <dimensional_metrics>true</dimensional_metrics>
</prometheus>

A seção <prometheus.handlers> pode ser usada para criar handlers mais avançados na mesma porta. Esta seção é semelhante a <http_handlers>, mas funciona com protocolos Prometheus:

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

Configurações:

Name	Default	Description
port	nenhum	Porta que serve métricas do ClickHouse.
endpoint	/metrics	Endpoint HTTP para a coleta de métricas. Começa com /. Não deve ser usado com a seção <handlers>.
url / headers / method	nenhum	Filtros usados para encontrar um handler correspondente para uma requisição. Semelhantes aos campos com os mesmos nomes na seção <http_handlers>.
info	true	Expõe o gauge ClickHouse_Info com rótulos de identidade do servidor (name, version, version_describe, version_major, version_minor, version_patch).
metrics	true	Expõe métricas de system.metrics.
asynchronous_metrics	true	Expõe métricas de system.asynchronous_metrics.
events	true	Expõe métricas de system.events.
errors	true	Expõe contagens de erros de system.errors.
histograms	true	Expõe métricas de system.histogram_metrics.
dimensional_metrics	true	Expõe métricas de system.dimensional_metrics.
labels	nenhum	Rótulos constantes adicionados a cada métrica exposta. Cada elemento filho define um rótulo: o nome do elemento é o nome do rótulo (que deve corresponder a [a-zA-Z_][a-zA-Z0-9_]*) e o valor do elemento é o valor do rótulo. Os valores dos rótulos oferecem suporte a substituições de configuração padrão, como o atributo from_env. Um nome de rótulo é rejeitado quando começa com __ (reservado pelo Prometheus) ou quando entra em conflito com um rótulo que este endpoint já grava para uma de suas seções habilitadas. Portanto, o conjunto reservado segue a superfície de exportação ativa do endpoint: le quando histograms está habilitado; os rótulos de ClickHouse_Info (name, version, version_describe, version_major, version_minor, version_patch) quando info está habilitado; e qualquer rótulo usado por uma família de métricas de histograma ou dimensional exposta (por exemplo, group, direction ou operation_type) quando histograms ou dimensional_metrics está habilitado. Como isso depende do que o endpoint realmente expõe, um nome pode ser válido em um endpoint, mas rejeitado em outro.

Verifique o endpoint:

curl http://127.0.0.1:9363/metrics

​

API HTTP do Prometheus e PromQL

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.

​

Pré-requisitos

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

SET allow_experimental_time_series_table = 1;

Crie um banco de dados e uma tabela TimeSeries:

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

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

​

Configure a API do Prometheus

Configure um manipulador 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 em intervalo

O exemplo omite database e table do handler. Cada solicitação deve fornecer o parâmetro de consulta table. 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.

​

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.

​

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"

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: GET
      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.

Apenas os endpoints de consulta /api/v1/query e /api/v1/query_range estão implementados. Os endpoints de metadados usados por uma fonte de dados Prometheus no Grafana para navegar por rótulos, variáveis de Template e preenchimento automático no construtor de consultas (/api/v1/series, /api/v1/labels, /api/v1/label/<name>/values) não estão implementados e retornam um erro. Escreva expressões PromQL no modo de código em vez de usar o 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()
);

​

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>