Визуализации на основе SQL

ClickStack поддерживает визуализации на основе SQL-запросов в исходном виде. Это дает полный контроль над логикой запроса, сохраняя интеграцию с временными диапазонами на уровне панели мониторинга, фильтрами и отрисовкой диаграмм.

Визуализации на основе SQL полезны, когда нужно выйти за рамки встроенного Chart Explorer — например, чтобы объединять таблицы с помощью JOIN или строить сложные агрегации, которые не поддерживаются chart builder.

Чтобы создать визуализацию на основе SQL, откройте редактор плитки панели мониторинга и выберите вкладку SQL.

Далее:

1. Выберите подключение к ClickHouse, для которого будет выполняться запрос.
2. При необходимости выберите Source — это позволит применять к вашей визуализации фильтры уровня панели мониторинга через макрос $__filters.
3. Напишите SQL-запрос в редакторе, используя параметры запроса и макросы для интеграции с временным диапазоном, фильтрами и переменными панели мониторинга.
4. Нажмите кнопку play, чтобы просмотреть результат, затем нажмите Save.

Параметры запроса позволяют использовать в SQL текущий временной диапазон и уровень детализации панели мониторинга. Для этого применяется синтаксис параметризованных запросов ClickHouse: {paramName:Type}.

Доступные параметры зависят от типа диаграммы:

Диаграммы Line и столбчатые диаграммы с накоплением:

Диаграммы Table, Pie и Number:

Макросы — это сокращённые конструкции, которые разворачиваются в типовые выражения ClickHouse SQL. Они начинаются с префикса $__ и заменяются до отправки запроса в ClickHouse.

Эти макросы возвращают выражение ClickHouse, соответствующее времени начала или окончания панели мониторинга. Они не принимают аргументов.

Эти макросы создают фрагмент условия WHERE, который фильтрует столбец по временному диапазону панели мониторинга.

Пример развёртывания $__timeFilter(TimestampTime):

TimestampTime >= toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
AND TimestampTime <= toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))

Эти макросы группируют столбец с временной меткой по интервалам, соответствующим детализации панели мониторинга. Обычно они используются в секциях SELECT и GROUP BY для графиков временных рядов. Они доступны только для визуализаций Line и столбчатых диаграмм с накоплением.

Пример развёртывания $__timeInterval(TimestampTime):

toStartOfInterval(toDateTime(TimestampTime), INTERVAL {intervalSeconds:Int64} second)

Когда на графике выбран Source и включены фильтры панели мониторинга, $__filters разворачивается в соответствующие условия SQL WHERE. Если источник не выбран или фильтры не заданы, он разворачивается в (1=1), поэтому его всегда можно безопасно включать в условие WHERE.

$__filters применяет только фильтры с включенным параметром Broadcast filter condition. Фильтры, представленные как переменные, указываются явно, как описано ниже.

Если фильтр панели мониторинга доступен в качестве переменной, его выбранные значения можно использовать в любом месте запроса. Эти макросы доступны только в плитках панели мониторинга, в которой объявлена хотя бы одна переменная.

Значения переменной также можно подставлять напрямую как $name или ${name}, указав необязательный формат: ${name:sqlstring} (по умолчанию), ${name:csv} или ${name:regex}. В формате по умолчанию прямая ссылка до выбора значения отображается как NULL, поэтому везде, где ожидается предикат, используйте указанные выше макросы.

ClickStack автоматически сопоставляет столбцы результатов с элементами диаграммы в зависимости от типов столбцов. Правила сопоставления зависят от типа диаграммы.

Все столбцы результатов отображаются непосредственно в виде столбцов таблицы.

Этот запрос подсчитывает количество событий логов для каждого сервиса, группируя их по временным интервалам в соответствии с детализацией панели мониторинга.

SELECT
  toStartOfInterval(TimestampTime, INTERVAL {intervalSeconds:Int64} second) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

• ts (DateTime) используется как временная метка на оси X.
• count (числовое значение) отображается как значение серии.
• ServiceName (строка) создает отдельную линию для каждого сервиса.

Тот же запрос с использованием макросов для краткости:

SELECT
  $__timeInterval(TimestampTime) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

Для панели мониторинга с переменной service, связанной с ServiceName, и переменной severity, связанной с SeverityText, этот запрос ограничивает диаграмму текущим выбранным сервисом и исключает выбранные уровни серьёзности. Если для переменной не выбрано значение, оба макроса разворачиваются в 1=1, поэтому до выбора значения пользователем диаграмма отображается без фильтрации.

SELECT
  $__timeInterval(TimestampTime) AS ts,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filter(ServiceName, $service)
  AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY ts
ORDER BY ts ASC

SELECT
  $__timeInterval(TimestampTime) AS ts,
  lower(SeverityText),
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND lower(SeverityText) IN ('error', 'warn')
  AND $__filters
GROUP BY SeverityText, ts
ORDER BY ts ASC

SELECT
  SpanName AS endpoint,
  avg(Duration) / 1000 AS avg_duration_ms,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY SpanName
ORDER BY avg_duration_ms DESC
LIMIT 10

SELECT
  ServiceName,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY ServiceName

• request_count (числовое значение) определяет размер каждого сегмента.
• ServiceName (строка) задает метку каждого сегмента.

SELECT
  count() AS total_errors
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND SeverityText = 'error'
  AND $__filters

Отображается числовое значение total_errors из первой строки.

• Визуализации на основе SQL выполняются во включенном режиме readonly — разрешены только запросы SELECT.
• Визуализации на основе SQL должны содержать ровно один SQL-запрос — несколько запросов не поддерживаются.
• Редактор SQL предлагает автодополнение как для параметров запроса, так и для макросов.
• Чтобы фильтры панели мониторинга применялись к визуализациям на основе SQL, необходимо выбрать Source. Для корректной фильтрации Source должен соответствовать таблице, к которой обращается запрос.
• Для переменных панели мониторинга Source не требуется — значения берутся из выпадающих списков фильтров панели мониторинга, а не из собственного Source блока.
• Оповещения для SQL-блока, ссылающегося на переменную панели мониторинга, вычисляются для каждой переменной в пустом состоянии, а не со значениями, выбранными на панели мониторинга.