Protocolos do Prometheus e PromQL

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
`/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. 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. 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"

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 e os endpoints de metadados /api/v1/series, /api/v1/labels 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). O endpoint de valores de rótulos (/api/v1/label/<name>/values), usado 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, não está implementado e retorna 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()
);

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>

Fundamentals

ClickHouse concepts

Best practices

Exponha métricas do servidor ClickHouse

API HTTP do Prometheus e PromQL

Pré-requisitos

Configure a API do Prometheus

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

Consulta com PromQL

Grafana

Pontos de entrada SQL

Consultar metadados de métricas

Leia métricas com leitura remota

​Exponha métricas do servidor ClickHouse

​API HTTP do Prometheus e PromQL

​Pré-requisitos

​Configure a API do Prometheus

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

​Consulta com PromQL

​Grafana

​Pontos de entrada SQL

​Consultar metadados de métricas

​Leia métricas com leitura remota

Exponha métricas do servidor ClickHouse

API HTTP do Prometheus e PromQL

Pré-requisitos

Configure a API do Prometheus

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

Consulta com PromQL

Grafana

Pontos de entrada SQL

Consultar metadados de métricas

Leia métricas com leitura remota