> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Suporte à API HTTP do Prometheus no ClickHouse: gravação remota, leitura remota, consultas PromQL e métricas do servidor.
# Protocolos do Prometheus e PromQL
export const CloudNotSupportedBadge = () => {
return
Sem suporte no ClickHouse Cloud
;
};
## 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](/pt-BR/products/cloud/features/monitoring/prometheus).
Configure uma porta dedicada quando um servidor Prometheus precisar coletar as próprias métricas do ClickHouse:
```xml theme={null}
9363
/metrics
true
true
true
true
true
true
```
A seção `` pode ser usada para criar handlers mais avançados na mesma porta.
Esta seção é semelhante a [``](/pt-BR/concepts/features/interfaces/http), mas funciona com protocolos Prometheus:
```xml theme={null}
9363
/metrics
expose_metrics
true
true
true
true
true
true
production
```
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 ``. |
| `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 [``](/pt-BR/concepts/features/interfaces/http). |
| `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`](/pt-BR/reference/system-tables/metrics). |
| `asynchronous_metrics` | true | Expõe métricas de [`system.asynchronous_metrics`](/pt-BR/reference/system-tables/asynchronous_metrics). |
| `events` | true | Expõe métricas de [`system.events`](/pt-BR/reference/system-tables/events). |
| `errors` | true | Expõe contagens de erros de [`system.errors`](/pt-BR/reference/system-tables/errors). |
| `histograms` | true | Expõe métricas de [`system.histogram_metrics`](/pt-BR/reference/system-tables/histogram_metrics). |
| `dimensional_metrics` | true | Expõe métricas de [`system.dimensional_metrics`](/pt-BR/reference/system-tables/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:
```bash theme={null}
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`](/pt-BR/reference/engines/table-engines/integrations/time-series). 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`](/pt-BR/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) para o usuário que cria e acessa a tabela:
```sql theme={null}
SET allow_experimental_time_series_table = 1;
```
Crie um banco de dados e uma tabela `TimeSeries`:
```sql theme={null}
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:
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` 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:
```xml theme={null}
prometheus_api_v1
prometheus
```
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](https://prometheus.io/docs/specs/remote_write_spec/). Configure o Prometheus para gravar no handler:
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
basic_auth:
username: default
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:
```bash theme={null}
curl --user default: --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:
```bash theme={null}
curl --user default: --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](/pt-BR/sql-reference/table-functions/prometheusQueryRange#supported-promql-features) 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`:
```yaml theme={null}
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:
```
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//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`](/pt-BR/sql-reference/table-functions/prometheusQuery) e [`prometheusQueryRange`](/pt-BR/sql-reference/table-functions/prometheusQueryRange).
Execute PromQL diretamente com o `clickhouse-client`:
```bash theme={null}
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:
```sql theme={null}
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](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) em `/prometheus/api/v1/read`.
Configure um servidor Prometheus para ler da mesma tabela `TimeSeries`:
```yaml theme={null}
remote_read:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
basic_auth:
username: default
password:
```