> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Compatibilidad de ClickHouse con la API HTTP de Prometheus: escritura y lectura remotas, consultas PromQL y métricas del servidor.
# Protocolos de Prometheus y PromQL
export const CloudNotSupportedBadge = () => {
return
No es compatible con ClickHouse Cloud
;
};
## Exponer métricas del servidor ClickHouse
Si usas ClickHouse Cloud, puedes exponer métricas a Prometheus con la [integración de Prometheus](/es/products/cloud/features/monitoring/prometheus).
Configure un puerto dedicado cuando un servidor Prometheus necesite recopilar las propias métricas de ClickHouse:
```xml theme={null}
9363
/metrics
true
true
true
true
true
true
```
Section `` can be used to make more extended handlers en el mismo puerto.
Esta sección es similar a [``](/es/concepts/features/interfaces/http) pero funciona para Protocolos de Prometheus:
```xml theme={null}
9363
/metrics
expose_metrics
true
true
true
true
true
true
production
```
Configuración:
| Nombre | Predeterminado | Descripción |
| ---------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port` | ninguno | Puerto que expone las métricas de ClickHouse. |
| `endpoint` | `/metrics` | Endpoint HTTP para recopilar métricas. Empieza por `/`. No debe usarse con la sección ``. |
| `url` / `headers` / `method` | ninguno | Filtros utilizados para encontrar un handler que coincida con una solicitud. Son similares a los campos con los mismos nombres de la sección [``](/es/concepts/features/interfaces/http). |
| `info` | true | Expone el gauge `ClickHouse_Info` con etiquetas de identidad del servidor (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`). |
| `metrics` | true | Expone métricas de [`system.metrics`](/es/reference/system-tables/metrics). |
| `asynchronous_metrics` | true | Expone métricas de [`system.asynchronous_metrics`](/es/reference/system-tables/asynchronous_metrics). |
| `events` | true | Expone métricas de [`system.events`](/es/reference/system-tables/events). |
| `errors` | true | Expone recuentos de errores de [`system.errors`](/es/reference/system-tables/errors). |
| `histograms` | true | Expone métricas de [`system.histogram_metrics`](/es/reference/system-tables/histogram_metrics). |
| `dimensional_metrics` | true | Expone métricas de [`system.dimensional_metrics`](/es/reference/system-tables/dimensional_metrics). |
| `labels` | ninguno | Etiquetas constantes añadidas a cada métrica expuesta. Cada elemento secundario define una etiqueta: el nombre del elemento es el nombre de la etiqueta (que debe coincidir con `[a-zA-Z_][a-zA-Z0-9_]*`) y el valor del elemento es el valor de la etiqueta. Los valores de las etiquetas admiten sustituciones de configuración estándar, como el atributo `from_env`. Se rechaza un nombre de etiqueta cuando empieza por `__` (reservado por Prometheus) o cuando entraría en conflicto con una etiqueta que este endpoint ya escribe para una de sus secciones habilitadas. Por tanto, el conjunto reservado sigue la superficie de exportación activa del endpoint: `le` cuando `histograms` está habilitado; las etiquetas de `ClickHouse_Info` (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) cuando `info` está habilitado; y cualquier etiqueta utilizada por una familia de métricas de histograma o dimensional expuesta (por ejemplo, `group`, `direction` u `operation_type`) cuando `histograms` o `dimensional_metrics` está habilitado. Como depende de lo que el endpoint expone realmente, un nombre puede ser válido en un endpoint, pero rechazarse en otro. |
Compruebe el endpoint:
```bash theme={null}
curl http://127.0.0.1:9363/metrics
```
## API HTTP de Prometheus y PromQL
ClickHouse implementa la API HTTP de Prometheus sobre una tabla [`TimeSeries`](/es/reference/engines/table-engines/integrations/time-series). Un handler gestiona la escritura remota, la lectura remota, las consultas PromQL instantáneas y las consultas PromQL de rango.
### Requisitos previos
Habilite la opción [`allow_experimental_time_series_table`](/es/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) para el usuario que crea la tabla y accede a ella:
```sql theme={null}
SET allow_experimental_time_series_table = 1;
```
Cree una base de datos y una tabla `TimeSeries`:
```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```
Para las solicitudes a la API HTTP, habilite `allow_experimental_time_series_table` en el perfil del usuario de la API.
### Configure la API de Prometheus
Configure un handler enrutado por prefijo en el puerto HTTP principal de ClickHouse:
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` conserva los handler integrados para endpoints como `/ping` y para solicitudes SQL. El prefijo anterior expone estos endpoints mediante un único handler:
| Endpoint | Finalidad |
| -------------------------------- | ------------------------------ |
| `/prometheus/api/v1/write` | Escritura remota de Prometheus |
| `/prometheus/api/v1/read` | Lectura remota de Prometheus |
| `/prometheus/api/v1/query` | Consultas PromQL instantáneas |
| `/prometheus/api/v1/query_range` | Consultas PromQL por intervalo |
El ejemplo omite `database` y `table` del handler. Cada solicitud debe incluir el parámetro de consulta `table`. También puede incluir `database`, usar un nombre de tabla completo como `prometheus.metrics` u omitir la base de datos para usar `default`. Esto permite que un único handler atienda varias tablas `TimeSeries`.
Para usar una tabla fija en todas las solicitudes, configúrela en el handler:
```xml theme={null}
prometheus_api_v1
prometheus
```
Una tabla configurada en el handler no puede sobrescribirse mediante parámetros de la solicitud.
Configuración de enrutamiento y del handler:
| Nombre | Predeterminado | Descripción |
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url_prefix` | ninguno | Regla de filtrado que coincide con todas las rutas de solicitud que comienzan con el prefijo configurado. |
| `table` | ninguno | El nombre de una tabla `TimeSeries`. Si se omite, la solicitud debe incluir el parámetro de consulta `table`. El nombre configurado puede incluir una base de datos. |
| `database` | ninguno | La base de datos que contiene la tabla. Una solicitud puede proporcionarla como parámetro de consulta. Si se omite, ClickHouse usa la base de datos de un valor `table` calificado o recurre a `default`. |
### Ingeste métricas mediante escritura remota
ClickHouse admite el [protocolo remote-write de Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). Configure Prometheus para que escriba en el controlador:
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
basic_auth:
username: default
password:
```
Prometheus envía muestras a la tabla `prometheus.metrics`.
### Consultas con PromQL
Utilice el endpoint de consulta instantánea para evaluar una expresión de PromQL en un momento dado:
```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 el endpoint de consulta de rango para evaluar una expresión en un intervalo de tiempo:
```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 las [funcionalidades de PromQL compatibles](/es/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) para obtener la lista de funciones y operadores de agregación que utilizan la API HTTP, el dialecto `promql` y las funciones de tabla.
#### Grafana
Configure una fuente de datos de Prometheus con una URL base que termine 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:
```
Grafana agrega `/api/v1/query` o `/api/v1/query_range` a esta URL base y añade `customQueryParameters` a cada solicitud.
Solo están implementados los endpoints de consulta `/api/v1/query` y `/api/v1/query_range`. Los endpoints de metadatos que utiliza un origen de datos de Prometheus en Grafana para explorar etiquetas, variables de plantilla y el autocompletado del constructor de consultas (`/api/v1/series`, `/api/v1/labels`, `/api/v1/label//values`) no están implementados y devuelven un error. Escriba expresiones de PromQL en el modo de código en lugar de usar el constructor de consultas.
#### Puntos de entrada de SQL
ClickHouse utiliza el mismo convertidor de PromQL para la API HTTP, el dialecto `promql` y las funciones de tabla [`prometheusQuery`](/es/reference/functions/table-functions/prometheusQuery) y [`prometheusQueryRange`](/es/reference/functions/table-functions/prometheusQueryRange).
Ejecute PromQL directamente con `clickhouse-client`:
```bash theme={null}
clickhouse-client \
--dialect promql \
--promql_database prometheus \
--promql_table metrics \
--query 'rate(http_requests_total[5m])'
```
Utilice las funciones de tabla para integrar PromQL en una consulta SQL:
```sql theme={null}
SELECT *
FROM prometheusQuery(
prometheus.metrics,
'rate(http_requests_total[5m])',
now()
);
```
### Leer métricas mediante lectura remota
ClickHouse admite el [protocolo de lectura remota de Prometheus](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) en `/prometheus/api/v1/read`.
Configure un servidor Prometheus para que lea de la misma tabla `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:
```