Protocolos do Prometheus e PromQL

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:

Verifique o endpoint:

curl http://127.0.0.1:9363/metrics

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.

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

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:

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.

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.

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.

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()
);

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:

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"

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>