Оповещения с ClickStack

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

Оповещения могут создаваться непосредственно в интерфейсе HyperDX и интегрироваться с популярными системами уведомлений, такими как Slack и PagerDuty.

Механизм оповещений бесшовно работает со всеми вашими данными в ClickStack, помогая отслеживать состояние системы, выявлять регрессии производительности и мониторить ключевые бизнес-события.

Типы оповещений

ClickStack поддерживает два взаимодополняющих способа создания оповещений: оповещения по поиску (Search alerts) и оповещения по графикам дашборда (Dashboard chart alerts). После создания оповещение привязывается либо к поисковому запросу, либо к графику.

1. Оповещения по поиску

Оповещения по поиску позволяют запускать уведомления на основе результатов сохранённого поиска. Они помогают обнаруживать, когда определённые события или паттерны начинают происходить чаще (или реже), чем ожидается.

Оповещение срабатывает, когда количество совпадающих результатов в заданном временном окне превышает или становится ниже указанного порогового значения.

Чтобы создать оповещение по поиску:

Откройте диалоговое окно создания оповещения

Сначала выполните поиск и нажмите кнопку Alerts в правом верхнем углу страницы Search.

Создайте оповещение

В панели создания оповещения вы можете:

• Задать имя сохранённому поиску, с которым связано оповещение.
• Настроить порог и указать, сколько раз он должен быть достигнут в течение заданного периода. Порог также можно использовать в качестве верхней или нижней границы. Указанный здесь период также определяет частоту срабатывания оповещения.
• Указать значение для grouped by. Это позволяет применить к поиску агрегацию, например по ServiceName, что даёт возможность запускать несколько оповещений от одного и того же поиска.
• Выбрать webhook-адрес для уведомлений. Вы можете добавить новый webhook прямо из этого окна. Подробнее см. в разделе Добавление webhook.

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

Обратите внимание, что к одному поиску можно добавить несколько оповещений. Если повторить описанный выше процесс, пользователи увидят текущие оповещения в виде вкладок в верхней части диалогового окна редактирования оповещения, при этом каждому оповещению будет присвоен номер.

2. Оповещения для графиков на дашборде

Оповещения дашборда распространяют систему оповещений на графики.

Вы можете создать оповещение на основе графика напрямую из сохранённого дашборда, используя полноценные SQL-агрегации и функции ClickHouse для продвинутых вычислений.

Когда метрика пересекает заданный порог, оповещение срабатывает автоматически, что позволяет отслеживать KPI, задержки или другие ключевые метрики в динамике.

Примечание

Чтобы для визуализации на дашборде можно было создать оповещение, дашборд должен быть сохранён.

Чтобы добавить оповещение дашборда:

Откройте диалог редактирования графика

Откройте меню настроек графика и выберите кнопку оповещения. Откроется диалоговое окно редактирования графика.

Добавьте оповещение

Выберите Add Alert.

Задайте условия срабатывания оповещения

Укажите условие (>=, >, <=, <, =, !=, <= x >=, > or <), порог, продолжительность и webhook. Здесь продолжительность также определяет, как часто будет срабатывать оповещение.

Вы можете добавить новый webhook прямо с этого экрана. Подробности см. в разделе Добавление webhook.

Добавление вебхука

При создании оповещения пользователи могут либо использовать существующий вебхук, либо создать новый. После создания вебхук будет доступен для повторного использования в других оповещениях.

Вебхук можно создать для разных типов сервисов, включая Slack и PagerDuty, а также для универсальных целей.

Например, рассмотрим создание оповещения для приведённого ниже графика. Перед указанием вебхука пользователь может выбрать Add New Webhook.

Откроется диалог создания вебхука, где пользователи могут создать новый вебхук:

Имя вебхука является обязательным, описание — необязательным. Остальные настройки, которые необходимо заполнить, зависят от типа сервиса.

Обратите внимание, что доступные типы сервисов различаются между ClickStack Open Source и ClickStack Cloud. См. раздел Интеграции по типу сервиса.

Интеграции по типу сервиса

Оповещения ClickStack по умолчанию интегрируются со следующими типами сервисов:

• Slack: отправка уведомлений напрямую в канал через webhook или API.
• PagerDuty: маршрутизация инцидентов для дежурных команд через PagerDuty API.
• Webhook: подключение оповещений к любой пользовательской системе или рабочему процессу через универсальный webhook.

Интеграции только для ClickHouse Cloud

Интеграции через Slack API и PagerDuty поддерживаются только в ClickHouse Cloud.

В зависимости от типа сервиса вам потребуется указать разные параметры. В частности:

Slack (Webhook URL)

• URL вебхука. Например: https://hooks.slack.com/services/<unique_path>. Подробности см. в документации Slack.

Slack (API)

• Токен бота Slack. Подробности см. в документации Slack.

PagerDuty API

• Ключ интеграции PagerDuty. Подробности см. в документации PagerDuty.

Generic

• URL вебхука
• Заголовки вебхука (необязательно)
• Тело вебхука (необязательно). В теле на данный момент поддерживаются переменные шаблона {{title}}, {{body}} и {{link}}.

Управление оповещениями

Оповещениями можно централизованно управлять через панель оповещений слева в интерфейсе HyperDX.

В этом представлении пользователи могут видеть все оповещения, которые были созданы и в данный момент активны в ClickStack.

В этом представлении также отображается история проверок оповещений. Оповещения проверяются через регулярные промежутки времени (интервал определяется периодом/длительностью, заданными при создании оповещения). Во время каждой проверки HyperDX выполняет запрос к вашим данным, чтобы определить, выполнено ли условие оповещения:

• Красная полоса: пороговое условие было выполнено во время этой проверки, и оповещение сработало (уведомление отправлено)
• Зелёная полоса: оповещение было проверено, но пороговое условие не было выполнено (уведомление не отправлено)

Каждая проверка независима — оповещение анализирует данные за соответствующий временной интервал и срабатывает только в том случае, если условие истинно в этот момент.

В приведённом выше примере первое оповещение срабатывало при каждой проверке, что указывает на постоянную проблему. Второе оповещение показывает уже решённую проблему: оно сработало два раза вначале (красные полосы), затем при последующих проверках пороговое условие больше не выполнялось (зелёные полосы).

При нажатии на оповещение вы переходите к диаграмме или поисковому запросу, с которыми связано это оповещение.

Удаление оповещения

Чтобы удалить оповещение, откройте диалог редактирования соответствующего поиска или графика, затем нажмите Remove Alert. В примере ниже кнопка Remove Alert удалит оповещение с графика.

Оповещения для чартов на основе SQL

Оповещения для чартов на основе SQL позволяют писать произвольные SQL-запросы ClickHouse, чтобы задавать условия оповещений. Это дает полный контроль над фильтрацией, агрегацией и вычислениями — все, что можно выразить в SQL, можно превратить в оповещение.

Поддерживаемые типы диаграмм

Оповещения на основе SQL поддерживаются для трёх типов отображения диаграмм:

Тип диаграммы	Поведение
Line	Оповещение для временных рядов. Запрос должен возвращать строки с разбивкой по временным бакетам. Каждый бакет оценивается отдельно относительно порогового значения.
Stacked Bar	Оповещение для временных рядов. Поведение такое же, как у Line.
Number	Оповещение по одному значению. Запрос возвращает единственный числовой результат, который сравнивается с пороговым значением один раз при каждой проверке.

Другие типы диаграмм на основе SQL (Table, Pie, Heatmap и т. д.) не поддерживают оповещения.

Создание SQL-оповещения

Чтобы создать оповещение для SQL-диаграммы:

Создайте или откройте SQL-диаграмму на дашборде

На сохранённом дашборде либо создайте новую диаграмму в режиме SQL, либо откройте существующую SQL-диаграмму для редактирования.

Выберите Линия, Столбцы с накоплением или Число в качестве типа отображения.

Добавьте оповещение

В редакторе диаграммы в разделе оповещений выберите Добавить оповещение. Настройте:

• Тип порога: >= (больше или равно), > (больше), <= (меньше или равно), < (меньше), = (равно), != (не равно), <= x >= (между) или > or < (вне диапазона)
• Значение порога: Числовое значение для сравнения
• Интервал: Как часто оценивается оповещение (1m, 5m, 15m, 30m, 1h, 6h, 12h или 1d). Это также задаёт временное окно для каждой проверки.
• Webhook: Канал уведомлений, который используется при срабатывании оповещения. См. Добавление webhook.

Временной диапазон оповещения

Как правило, запросы оповещения выполняются один раз за каждый интервал. Однако если один или несколько интервалов были пропущены из-за ошибок или медленных запросов, при следующем выполнении будет использоваться временной диапазон, включающий пропущенные интервалы. В этом случае параметры интервала в запросе по-прежнему будут соответствовать периоду, настроенному для оповещения, а параметры временного диапазона будут отражать более длительный временной диапазон.

Сохраните дашборд

Сохраните дашборд, чтобы активировать оповещение. После этого оповещение начнёт проверяться с заданным интервалом.

Как интерпретируются результаты запроса

Система оповещений анализирует столбцы, возвращаемые вашим SQL-запросом, чтобы определить, что именно сравнивать с пороговым значением.

• Столбец значения: В качестве значения оповещения используется последний числовой столбец в секции SELECT. Если запрос возвращает несколько числовых столбцов (например, count, avg_latency, p99_latency), с пороговым значением сравнивается только последний из них (p99_latency).
• Столбец таймстампа: Для диаграмм временных рядов (Line и Stacked Bar) система определяет столбец Date/DateTime в результатах как временной бакет (то есть ось X на диаграмме временного ряда). Столбец значения для каждого временного бакета оценивается относительно порогового значения независимо, и если значение в любом временном бакете превышает настроенный порог, сработает оповещение.
• Столбцы группировки: Любые нечисловые столбцы, не являющиеся столбцами таймстампа (например, ServiceName, Environment), рассматриваются как измерения группировки. Если группы присутствуют, каждая уникальная комбинация значений групп отслеживается и проверяется отдельно. ClickStack отправит оповещение для каждой группы, значение которой превышает настроенный порог. Группы доступны только для диаграмм временных рядов.

Параметры запроса и макросы

SQL-запросы для оповещений поддерживают шаблонные параметры и макросы, которые автоматически заменяются при вычислении. Это те же параметры и макросы, которые доступны при создании SQL-чарта.

Обязательные и рекомендуемые параметры

Запросы, используемые для оповещений на основе линейных или составных столбчатых диаграмм, должны включать параметр interval или макрос ({intervalSeconds:Int64}, {intervalMilliseconds:Int64}, $__timeInterval(col) или $__timeInterval_ms(col)). При выполнении оповещения он будет заменён настроенным для оповещения периодом.

Запросы, используемые для оповещений, должны включать фильтр временного диапазона ({startDateMilliseconds:Int64} и {endDateMilliseconds:Int64} или $__timeFilter(col) и т. д.). Независимо от того, есть ли в запросе фильтр временного диапазона, запрос оповещения будет выполняться для периода, настроенного в оповещении. Если фильтр временного диапазона отсутствует, то при каждом выполнении запрос будет читать весь временной диапазон, доступный в исходной таблице.

Временной диапазон оповещения

Обычно запросы оповещений выполняются один раз за interval. Однако если один или несколько interval были пропущены из-за ошибок или медленного выполнения запросов, при следующем выполнении будет использован временной диапазон, включающий пропущенные interval. В этом случае параметры interval в запросе по-прежнему будут установлены в настроенный для оповещения период, а параметры временного диапазона будут соответствовать более длинному временному диапазону.

Примеры запросов для оповещений

Скорость ошибок по сервисам (time-series)

Настройте оповещение, если у любого сервиса скорость ошибок превышает 5 %, при этом за период оповещения должно быть не менее 10 запросов, чтобы избежать лишнего шума для сервисов с низким трафиком.

WITH error_rates AS (
  SELECT
    $__timeInterval(Timestamp) as ts,
    ServiceName,
    countIf (SpanKind = 'Server') as request_count,
    countIf (
      SpanKind = 'Server'
      and StatusCode = 'Error'
    ) as error_count,
    error_count / request_count * 100 AS error_percent
  FROM $__sourceTable
  WHERE $__timeFilter(Timestamp)
  GROUP BY ts, ServiceName
)
SELECT ts, ServiceName, error_percent
FROM error_rates
WHERE request_count > 10

Тип отображения: Линия или столбчатая диаграмма с накоплением Порог: >= 5 (срабатывает, когда скорость ошибок достигает 5 %)

В этом запросе ServiceName — нечисловой столбец и не столбец с таймстампом, поэтому каждый сервис отслеживается как отдельная группа алертов. Алерт срабатывает независимо для каждого сервиса.

Обнаружение аномалий с помощью запаздывающего среднего (временные ряды)

Настройте alert для избыточного числа ошибок, которое превышает скользящее среднее более чем на два стандартных отклонения. Это позволяет выявлять всплески относительно недавнего базового уровня, а не по фиксированному порогу.

WITH buckets AS (
  SELECT
    $__timeInterval(Timestamp) AS ts,
    count() AS bucket_count
  FROM $__sourceTable
  WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
        - toIntervalSecond($__interval_s * 30) -- Fetch 30 intervals back
    AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
    AND SeverityText = 'error'
  GROUP BY ts
  ORDER BY ts
  WITH FILL
    FROM toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
    TO toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))
    STEP toIntervalSecond($__interval_s)
),

anomaly_detection AS (
  SELECT
    ts,
    bucket_count,
    avg(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS previous_30_avg,
    stddevPop(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS previous_30_stddev,
    greatest(
      bucket_count - (previous_30_avg + 2 * previous_30_stddev), 0
    ) AS excess_error_count
  FROM buckets
)

SELECT ts, excess_error_count
FROM anomaly_detection
WHERE ts >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND ts < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})

Тип отображения: Линия Порог: > 0 (срабатывает, когда число ошибок превышает скользящий базовый уровень)

Обратите внимание, что запрос получает данные за 30 интервалов до начала диапазона дат, чтобы инициализировать расчёты скользящего окна, а затем фильтрует итоговый вывод, оставляя только окно оценки.

Типичные сценарии оповещений

Ниже приведены несколько распространённых сценариев оповещений, для которых вы можете использовать HyperDX:

Ошибки: Рекомендуем настроить оповещения для стандартных сохранённых запросов All Error Events и HTTP Status >= 400, чтобы получать уведомления, когда возникает слишком много ошибок.

Медленные операции: Вы можете настроить поиск медленных операций (например, duration:>5000), а затем включить оповещения, когда происходит слишком много таких операций.

Пользовательские события: Вы также можете настроить оповещения для команд, работающих с клиентами, чтобы они получали уведомления, когда регистрируются новые пользователи или выполняется критически важное действие пользователя.