> ## 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.
> Prometheus HTTP API support in ClickHouse: remote write, remote read, PromQL queries, and server metrics.
# Prometheus protocols and PromQL
export const CloudNotSupportedBadge = () => {
return
Not supported in ClickHouse Cloud
;
};
Expose ClickHouse server metrics
If you're using ClickHouse Cloud, you can expose metrics to Prometheus using the [Prometheus Integration](/products/cloud/features/monitoring/prometheus).
Configure a dedicated port when a Prometheus server needs to scrape ClickHouse's own metrics:
```xml theme={null}
9363
/metrics
true
true
true
true
true
true
```
Section `` can be used to make more extended handlers on the same port.
This section is similar to [``](/concepts/features/interfaces/http) but works for prometheus protocols:
```xml theme={null}
9363
/metrics
expose_metrics
true
true
true
true
true
true
production
```
Settings:
| Name | Default | Description |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port` | none | Port that serves ClickHouse metrics. |
| `endpoint` | `/metrics` | HTTP endpoint for scraping metrics. It starts with `/`. Should not be used with the `` section. |
| `url` / `headers` / `method` | none | Filters used to find a matching handler for a request. Similar to the fields with the same names in the [``](/concepts/features/interfaces/http) section. |
| `info` | true | Exposes the `ClickHouse_Info` gauge with server identity labels (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`). |
| `metrics` | true | Exposes metrics from [`system.metrics`](/reference/system-tables/metrics). |
| `asynchronous_metrics` | true | Exposes metrics from [`system.asynchronous_metrics`](/reference/system-tables/asynchronous_metrics). |
| `events` | true | Exposes metrics from [`system.events`](/reference/system-tables/events). |
| `errors` | true | Exposes error counts from [`system.errors`](/reference/system-tables/errors). |
| `histograms` | true | Exposes metrics from [`system.histogram_metrics`](/reference/system-tables/histogram_metrics). |
| `dimensional_metrics` | true | Exposes metrics from [`system.dimensional_metrics`](/reference/system-tables/dimensional_metrics). |
| `labels` | none | Constant labels added to every exposed metric. Each child element defines one label: the element name is the label name (which must match `[a-zA-Z_][a-zA-Z0-9_]*`) and the element value is the label value. Label values support standard config substitutions such as the `from_env` attribute. A label name is rejected when it starts with `__` (reserved by Prometheus), or when it would collide with a label this endpoint already writes for one of its enabled sections. The reserved set therefore follows the endpoint's active export surface: `le` when `histograms` is enabled; the `ClickHouse_Info` labels (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) when `info` is enabled; and any label used by an exposed histogram or dimensional metric family (for example, `group`, `direction`, or `operation_type`) when `histograms` or `dimensional_metrics` is enabled. Because it depends on what the endpoint actually exposes, a name can be valid on one endpoint but rejected on another. |
Check the endpoint:
```bash theme={null}
curl http://127.0.0.1:9363/metrics
```
Prometheus HTTP API and PromQL
ClickHouse implements the Prometheus HTTP API over a [`TimeSeries`](/reference/engines/table-engines/integrations/time-series) table. One handler serves remote write, remote read, instant PromQL queries, and range PromQL queries.
Prerequisites
Enable the [`allow_experimental_time_series_table`](/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) setting for the user that creates and accesses the table:
```sql theme={null}
SET allow_experimental_time_series_table = 1;
```
Create a database and a `TimeSeries` table:
```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```
For HTTP API requests, enable `allow_experimental_time_series_table` in the profile of the API user.
Configure one prefix-routed handler on the main ClickHouse HTTP port:
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` preserves the built-in handlers for endpoints such as `/ping` and for SQL requests. The prefix above exposes these endpoints through one handler:
| Endpoint | Purpose |
| -------------------------------- | ----------------------- |
| `/prometheus/api/v1/write` | Prometheus remote write |
| `/prometheus/api/v1/read` | Prometheus remote read |
| `/prometheus/api/v1/query` | Instant PromQL queries |
| `/prometheus/api/v1/query_range` | Range PromQL queries |
The example omits `database` and `table` from the handler. Each request must provide the `table` query parameter. It can also provide `database`, use a qualified table name such as `prometheus.metrics`, or omit the database to use `default`. This allows one handler to serve multiple `TimeSeries` tables.
To use one fixed table for every request, configure it in the handler:
```xml theme={null}
prometheus_api_v1
prometheus
```
A table configured in the handler cannot be overridden by request parameters.
Routing and handler settings:
| Name | Default | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url_prefix` | none | Rule filter that matches every request path that starts with the configured prefix. |
| `table` | none | The name of a `TimeSeries` table. When omitted, the request must provide the `table` query parameter. The configured name can include a database. |
| `database` | none | The database containing the table. A request can provide it as a query parameter. When omitted, ClickHouse uses a database from a qualified `table` value or falls back to `default`. |
Ingest metrics with remote write
ClickHouse supports the [Prometheus remote-write protocol](https://prometheus.io/docs/specs/remote_write_spec/). Configure Prometheus to write to the 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:
```
Prometheus sends samples to the `prometheus.metrics` table.
To batch data from many concurrent remote-write requests into fewer parts, enable [asynchronous inserts](/reference/settings/session-settings/async-insert#async_insert) by adding the `async_insert` setting to the URL (or by enabling it in the user profile):
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1
```
ClickHouse acknowledges an asynchronous remote-write request only after the data is flushed to all inner tables of the `TimeSeries` table, regardless of the [`wait_for_async_insert`](/reference/settings/session-settings/wait-for#wait_for_async_insert) setting: the remote-write protocol treats an acknowledged write as durable. If the flush fails, the request returns an error and Prometheus retries it.
Query with PromQL
Use the instant-query endpoint to evaluate a PromQL expression at one point in time:
```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 the range-query endpoint to evaluate an expression over a time range:
```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"
```
See the [supported PromQL features](/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) for the function and aggregation operator list used by the HTTP API, the `promql` dialect, and the table functions.
Grafana
Configure a Prometheus data source with the base URL ending before `/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 appends `/api/v1/query` or `/api/v1/query_range` to this base URL and adds `customQueryParameters` to each request.
Only the query endpoints `/api/v1/query` and `/api/v1/query_range` and the series metadata endpoint `/api/v1/series` are implemented. `/api/v1/series` requires at least one `match[]` series selector, supports the optional `start`, `end`, and `limit` parameters, and returns the union of the series matched by each selector. The label metadata endpoints a Grafana Prometheus datasource uses for label browsing, template variables, and query-builder autocomplete (`/api/v1/labels`, `/api/v1/label//values`) are not implemented and return an error. Write PromQL expressions in code mode instead of the query builder.
SQL entry points
ClickHouse uses the same PromQL converter for the HTTP API, the `promql` dialect, and the [`prometheusQuery`](/reference/functions/table-functions/prometheusQuery) and [`prometheusQueryRange`](/reference/functions/table-functions/prometheusQueryRange) table functions.
Run PromQL directly with `clickhouse-client`:
```bash theme={null}
clickhouse-client \
--dialect promql \
--promql_database prometheus \
--promql_table metrics \
--query 'rate(http_requests_total[5m])'
```
Use the table functions to embed PromQL in a SQL query:
```sql theme={null}
SELECT *
FROM prometheusQuery(
prometheus.metrics,
'rate(http_requests_total[5m])',
now()
);
```
Read metrics with remote read
ClickHouse supports the [Prometheus remote-read protocol](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) at `/prometheus/api/v1/read`.
Configure a Prometheus server to read from the same `TimeSeries` table:
```yaml theme={null}
remote_read:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
basic_auth:
username: default
password:
```