Grafana + ClickHouse: мониторинг и дашборды

Grafana — стандартный инструмент визуализации метрик в production ClickHouse-стеке. Официальный плагин grafana-clickhouse-datasource (Grafana Labs) поддерживает нативный протокол ClickHouse, специальные макросы для временных диапазонов и автоматическое переключение между Query Builder и SQL Editor.

Архитектура: Prometheus + ClickHouse + Grafana

Установка плагина

# Через grafana-cli
grafana-cli plugins install grafana-clickhouse-datasource

# Или через Docker/docker-compose env
GF_INSTALL_PLUGINS: grafana-clickhouse-datasource

После установки в Grafana: Configuration → Data Sources → Add → ClickHouse.

Параметры подключения:

• Server address: clickhouse-host (или IP)
• Server port: 9000 (нативный протокол, рекомендуется) или 8123 (HTTP)
• Protocol: Native (предпочтительно)
• Username / Password: default / '' (или настроенные учётные данные)

Конфигурация: prometheus.xml

Для активации нативного Prometheus endpoint создайте конфигурационный файл:

<!-- /etc/clickhouse-server/config.d/prometheus.xml -->
<clickhouse>
    <prometheus>
        <port>9363</port>
        <handlers>
            <expose_metrics_handler>
                <url>/metrics</url>
                <handler>
                    <type>expose_metrics</type>
                    <metrics>true</metrics>
                    <asynchronous_metrics>true</asynchronous_metrics>
                    <events>true</events>
                    <errors>true</errors>
                </handler>
            </expose_metrics_handler>
        </handlers>
    </prometheus>
</clickhouse>

Конфигурация Prometheus для scrape:

# prometheus.yml (фрагмент)
scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['clickhouse:9363']
    metrics_path: /metrics
    scrape_interval: 15s

Макросы плагина

Плагин grafana-clickhouse-datasource предоставляет макросы, которые автоматически подставляют временной диапазон выбранного в Grafana интервала:

$__timeFilter(column)

Для колонок типа DateTime. Подставляет условие column >= toDateTime(start) AND column <= toDateTime(end).

-- Source: Context7 clickhouse-docs query-builder.md
SELECT
    $__timeInterval(event_time) AS time,
    count() AS queries,
    avg(query_duration_ms) AS avg_duration_ms
FROM system.query_log
WHERE $__timeFilter(event_time)
  AND type = 'QueryFinish'
GROUP BY time
ORDER BY time ASC;

$__timeFilter_ms(column)

Для колонок типа DateTime64 с миллисекундной точностью.

SELECT
    $__timeInterval(timestamp_ms) AS time,
    sum(bytes_read) AS total_bytes
FROM events_detailed
WHERE $__timeFilter_ms(timestamp_ms)
GROUP BY time
ORDER BY time;

$__dateFilter(column)

Для колонок типа Date. Подставляет column >= toDate(start) AND column <= toDate(end).

SELECT
    $__timeInterval(event_date) AS time,
    count() AS daily_queries
FROM system.query_log
WHERE $__dateFilter(event_date)
  AND type = 'QueryFinish'
GROUP BY time
ORDER BY time;

$__timeInterval(column)

Подставляет функцию округления по выбранному интервалу: toStartOfInterval(column, INTERVAL X second). Интервал рассчитывается автоматически на основе ширины временного окна и разрешения дашборда.

-- Временной ряд: запросы по минутам
SELECT
    $__timeInterval(event_time) AS time,
    count() AS queries_per_interval,
    sum(read_rows) AS total_rows_read
FROM system.query_log
WHERE $__timeFilter(event_time)
  AND type = 'QueryFinish'
GROUP BY time
ORDER BY time;

__fromTime и __toTime

Константы — нижняя и верхняя граница выбранного временного диапазона. Полезны для расчётов внутри подзапросов.

-- Процент ошибочных запросов в выбранном интервале
SELECT
    countIf(type = 'ExceptionWhileProcessing') * 100.0 / count() AS error_pct
FROM system.query_log
WHERE event_time BETWEEN $__fromTime AND $__toTime;

Сравнение режимов: Query Builder vs SQL Editor

Пример: дашборд мониторинга query_log

-- Панель: топ пользователей по нагрузке за выбранный период
SELECT
    user,
    count() AS query_count,
    formatReadableSize(sum(memory_usage)) AS total_memory,
    avg(query_duration_ms) AS avg_duration_ms
FROM system.query_log
WHERE $__timeFilter(event_time)
  AND type = 'QueryFinish'
GROUP BY user
ORDER BY query_count DESC
LIMIT 10;

-- Панель: количество активных запросов во времени (из system.metrics)
SELECT
    $__timeInterval(event_time) AS time,
    avg(value) AS avg_active_queries
FROM system.metric_log
WHERE $__timeFilter(event_time)
  AND metric = 'Query'
GROUP BY time
ORDER BY time;

Ключевые выводы

1. Официальный плагин grafana-clickhouse-datasource (Grafana Labs) — рекомендуемый выбор. Поддерживает нативный протокол, все макросы и Query Builder.
2. $__timeFilter(column) — основной макрос для DateTime колонок. Всегда используйте его вместо ручного написания условий на временные границы — Grafana автоматически подставит выбранный диапазон.
3. $__timeInterval(column) — для построения временных рядов. Автоматически выбирает шаг агрегации в зависимости от ширины временного окна дашборда.
4. Нативный Prometheus endpoint (порт 9363) экспортирует ~200 метрик без sidecar. Включается через prometheus.xml в config.d/.
5. SQL Editor предпочтителен для production-дашбордов: полный контроль над запросом, JOIN-ы, подзапросы и оконные функции — всё работает без ограничений Query Builder.