Это руководство посвящено наиболее распространённым и эффективным способам оптимизации производительности ClickStack, которых достаточно для оптимизации большинства реальных рабочих нагрузок обсервабилити — как правило, вплоть до десятков терабайт данных в день.
Оптимизации представлены в продуманной последовательности: от самых простых и дающих наибольший эффект методов к более продвинутой и специализированной настройке. Ранние оптимизации следует применять в первую очередь, и нередко уже они сами по себе дают значительный прирост. По мере роста объёмов данных и усложнения рабочих нагрузок всё более целесообразным становится применение последующих методов.
Основные понятия ClickHouse
default, но это можно изменить в OpenTelemetry Collector.
Сосредоточьтесь на журналах и трассировкахВ большинстве случаев настройка производительности сосредоточена на таблицах журналов и трассировок. Хотя таблицы метрик тоже можно оптимизировать для фильтрации, их схемы намеренно ориентированы на рабочие нагрузки в стиле Prometheus и обычно не требуют изменений для стандартных графиков. Таблицы журналов и трассировок, напротив, поддерживают более широкий спектр access patterns, поэтому именно они выигрывают от настройки больше всего. Для данных сеансов пользовательский сценарий фиксирован, поэтому их схему редко приходится менять.
Оптимизация 1. Материализуйте часто запрашиваемые атрибуты
LogAttributes, ScopeAttributes и ResourceAttributes и вынести их в столбцы верхнего уровня с помощью материализованных столбцов.
Одной этой оптимизации часто достаточно, чтобы масштабировать развертывания ClickStack до десятков терабайт в день, и применять ее следует прежде, чем переходить к более продвинутым методам тонкой настройки.
Зачем материализовать атрибуты
Map(String, String). Это обеспечивает гибкость, но у запросов к вложенным ключам map есть важная особенность с точки зрения производительности.
При запросе одного ключа из столбца Map ClickHouse приходится читать с диска весь столбец map целиком. Если map содержит много ключей, это приводит к лишним операциям IO и замедляет запросы по сравнению с чтением отдельного столбца.
Материализация часто используемых атрибутов устраняет эти накладные расходы: значение извлекается во время вставки и сохраняется как полноценный столбец.
Материализованные столбцы:
- Вычисляются автоматически во время вставки
- Не могут быть явно заданы в операторах INSERT
- Поддерживают любые выражения ClickHouse
- Позволяют преобразовывать типы из String в более эффективные числовые типы или типы даты
- Позволяют использовать индекс пропуска данных и первичный ключ
- Сокращают объём чтения с диска, избавляя от необходимости читать map целиком
ClickStack автоматически обнаруживает материализованные столбцы, извлечённые из map, и прозрачно использует их при выполнении запросов, даже если пользователи продолжают обращаться к исходному пути атрибута.
ResourceAttributes:
Пользователь может фильтровать трассировки, используя синтаксис Lucene, например: ResourceAttributes.k8s.pod.name:"checkout-675775c4cc-f2p9c":
В результате получается SQL-предикат, похожий на следующий:
Поскольку здесь используется ключ Map, ClickHouse должен читать весь столбец ResourceAttributes для каждой подходящей строки — он может быть очень большим, если Map содержит много ключей.
Если по этому атрибуту часто выполняются запросы, его следует материализовать как столбец верхнего уровня.
Чтобы извлекать имя пода во время вставки, добавьте материализованный столбец:
С этого момента новые данные будут сохранять имя пода в отдельном столбце PodName.
Теперь пользователи могут эффективно выполнять запросы по именам подов, используя синтаксис Lucene, например PodName:"checkout-675775c4cc-f2p9c"
Для вновь вставленных данных это позволяет полностью избежать доступа к Map и значительно сократить I/O.
Однако даже если пользователи продолжают выполнять запросы по исходному пути атрибута, например ResourceAttributes.k8s.pod.name:"checkout-675775c4cc-f2p9c", ClickStack автоматически перепишет запрос внутри системы так, чтобы использовать материализованный столбец PodName, то есть с применением предиката:
Это гарантирует, что пользователи смогут воспользоваться преимуществами оптимизации без изменения панелей мониторинга, оповещений или сохранённых запросов.
По умолчанию материализованные столбцы исключаются из запросов SELECT *. Это сохраняет инвариант, согласно которому результаты запроса всегда можно снова вставить в таблицу.
Материализация исторических данных
system.mutations, например.
Дождитесь, пока для соответствующей мутации значение is_done не станет равным 1.
Мутации создают дополнительную нагрузку на IO и CPU, поэтому их следует использовать как можно реже. Во многих случаях достаточно дать старым данным естественным образом устареть и полагаться на повышение производительности для вновь поступающих данных.
Оптимизация 2. Добавление индексов пропуска данных
- Фильтрацию строк с высокой мощностью, таких как TraceId, идентификаторы сеансов, ключи или значения атрибутов
- Фильтрацию по числовым диапазонам, например по длительности span
Индексы типа bloom-фильтр — наиболее часто используемый тип индекса пропуска данных в ClickStack. Они хорошо подходят для строковых столбцов с высокой мощностью, как правило, не менее десятков тысяч различных значений. Уровень ложноположительных срабатываний 0.01 при гранулярности 1 — хорошая отправная точка по умолчанию, которая обеспечивает баланс между затратами на хранилище и эффективным отсечением данных.
Продолжая пример из Optimization 1, предположим, что имя пода Kubernetes было материализовано из ResourceAttributes:
Затем можно добавить индекс пропуска данных с bloom-фильтром, чтобы ускорить фильтрацию по этому столбцу:
После добавления индекс пропуска данных необходимо материализовать — см. “Материализуйте индекс пропуска данных.”
После создания и материализации ClickHouse может пропускать целые гранулы, которые заведомо не содержат запрошенное имя пода, что потенциально сокращает объём данных, считываемых при выполнении таких запросов, как PodName:"checkout-675775c4cc-f2p9c".
bloom-фильтры наиболее эффективны, когда распределение значений таково, что конкретное значение встречается в относительно небольшом числе частей. Это часто естественным образом происходит в рабочих нагрузках обсервабилити, где такие метаданные, как имена подов, trace ID или идентификаторы сеансов, коррелируют со временем и, следовательно, группируются по ключу сортировки таблицы.
Как и любые индексы пропуска данных, bloom-фильтры следует добавлять выборочно и проверять на реальных шаблонах запросов, чтобы убедиться, что они приносят измеримую пользу — см. “Оценка эффективности индекса пропуска данных.”
Индексы Minmax хранят минимальное и максимальное значение для каждой гранулы и очень легковесны. Они особенно эффективны для числовых столбцов и диапазонных запросов. Хотя они ускоряют не каждый запрос, они почти ничего не стоят и для числовых полей их почти всегда стоит добавлять.
Индексы Minmax лучше всего работают, когда числовые значения либо естественным образом упорядочены, либо ограничены узкими диапазонами в пределах каждой части.
Предположим, что по смещению Kafka часто выполняются запросы в SpanAttributes:
Это значение можно материализовать и привести к числовому типу:
Затем можно добавить индекс minmax:
Это позволяет ClickHouse эффективно пропускать части при фильтрации по диапазонам смещений Kafka, например при отладке отставания потребителя или повторного воспроизведения данных.
Индекс должен быть материализован, прежде чем станет доступен.
Материализация индекса пропуска данных
Материализация индексов пропуска данныхМатериализация индекса пропуска данных обычно является лёгкой и безопасной операцией, особенно для minmax-индексов. Для индексов bloom-фильтра на больших датасетах может быть удобнее выполнять материализацию по одной партиции, чтобы лучше контролировать потребление ресурсов, например: is_done = 1.
После завершения убедитесь, что данные индекса созданы:
Ненулевые значения указывают на то, что индекс был успешно материализован.
Важно понимать, что размер индекса пропуска данных напрямую влияет на производительность запроса. Очень большие индексы пропуска данных — порядка десятков или сотен гигабайт — могут требовать заметного времени на вычисление во время выполнения запроса, что может уменьшить или даже полностью свести на нет их пользу.
На практике индексы MinMax обычно очень компактны и почти не требуют затрат на вычисление, поэтому их материализация почти всегда безопасна. Индексы bloom-фильтра, напротив, могут значительно разрастаться в зависимости от мощности, гранулярности и вероятности ложноположительного срабатывания.
Размер bloom-фильтра можно уменьшить, повысив допустимую вероятность ложноположительного срабатывания. Например, увеличение параметра вероятности с 0.01 до 0.05 даёт индекс меньшего размера, который вычисляется быстрее, но ценой менее агрессивного отсечения. Хотя пропускаться будет меньше гранул, общая задержка запроса может снизиться за счёт более быстрой обработки индекса.
Поэтому настройка параметров bloom-фильтра — это оптимизация, зависящая от рабочей нагрузки, и её следует проверять на реальных шаблонах запросов и объёмах данных, близких к продакшн.
Дополнительные сведения об индексах пропуска данных см. в руководстве “Понимание индексов пропуска данных в ClickHouse.”
Оценка эффективности индекса пропуска данных
EXPLAIN indexes = 1, который показывает, сколько частей и гранул отсекается на каждом этапе планирования запроса. В большинстве случаев желательно видеть существенное сокращение числа гранул на этапе Skip — в идеале после того, как первичный ключ уже сузил пространство поиска. Индексы пропуска данных оцениваются после отсечения партиций и отсечения по первичному ключу, поэтому их влияние лучше всего измерять относительно оставшихся частей и гранул.
EXPLAIN подтверждает, происходит ли отсечение, но не гарантирует итогового ускорения. Вычисление индексов пропуска данных требует затрат, особенно если индекс большой. Всегда выполняйте бенчмарк запросов до и после добавления индекса и его материализации, чтобы подтвердить реальное повышение производительности.
Например, рассмотрим индекс пропуска данных с bloom-фильтром по умолчанию для TraceId, включенный в схему Traces по умолчанию:
Вы можете использовать EXPLAIN indexes = 1, чтобы оценить, насколько это эффективно для селективного запроса:
В этом случае фильтр по первичному ключу сначала существенно сокращает набор данных (с 35898 гранул до 255), а затем bloom-фильтр дополнительно отсекает всё до одной гранулы (1/255). Это идеальный сценарий для индексов пропуска данных: отсечение по первичному ключу сужает область поиска, а затем индекс пропуска данных отсекает большую часть оставшегося.
Чтобы оценить реальный эффект, выполните бенчмарк запроса со стабильными настройками и сравните время выполнения. Используйте FORMAT Null, чтобы избежать накладных расходов на сериализацию результата, и отключите кэш условий запроса, чтобы прогоны оставались воспроизводимыми:
Теперь выполните тот же запрос с отключёнными индексами пропуска данных:
Отключение use_query_condition_cache гарантирует, что результаты не будут зависеть от кэшированных решений о фильтрации, а установка use_skip_indexes = 0 дает чистую отправную точку для сравнения. Если отсечение данных эффективно, а затраты на вычисление индекса невелики, запрос с индексом должен быть заметно быстрее, как в примере выше.
Если EXPLAIN показывает минимальное отсечение гранул или индекс пропуска данных очень велик, затраты на вычисление индекса могут свести на нет весь выигрыш. Используйте EXPLAIN indexes = 1, чтобы подтвердить отсечение, а затем выполните бенчмарк, чтобы подтвердить итоговый прирост производительности.
Когда добавлять индексы пропуска данных
Оптимизация 3. Изменение первичного ключа
Примечание о терминологииВ этом документе термин “ключ сортировки” используется как взаимозаменяемый с термином “первичный ключ”. Строго говоря, в ClickHouse это разные понятия, но в ClickStack они обычно относятся к одним и тем же столбцам, указанным в ORDER BY таблицы. Подробнее см. документацию ClickHouse о выборе первичного ключа, отличающегося от ключа сортировки.
- Логи (
otel_logs) - (ServiceName, TimestampTime, Timestamp)
- Трассировки (‘otel_traces) -
(ServiceName, SpanName, toDateTime(Timestamp))
См. “Таблицы и схемы, используемые в ClickStack”, чтобы узнать, какие первичные ключи используются в таблицах для других типов данных. Например, таблицы трассировок оптимизированы для фильтрации по имени сервиса и имени span, а затем по временной метке и trace ID. Таблицы журналов, напротив, оптимизированы для фильтрации по имени сервиса, затем по дате и затем по временной метке. Хотя оптимально, если пользователь применяет фильтры в порядке столбцов первичного ключа, запросы всё равно существенно выигрывают от фильтрации по любому из этих столбцов в любом порядке, поскольку ClickHouse отсекает данные до чтения.
При выборе первичного ключа есть и другие факторы, которые влияют на оптимальный порядок столбцов. См. “Выбор первичного ключа.”
Первичные ключи следует изменять отдельно для каждой таблицы. То, что имеет смысл для журналов, может не подходить для трассировок или метрик.
Сначала определите, насколько ваши паттерны доступа для конкретной таблицы отличаются от значений по умолчанию. Например, если чаще всего вы фильтруете журналы по узлу Kubernetes, а уже потом по имени сервиса, и это основной сценарий работы, изменение первичного ключа может быть оправданно.
Изменение первичного ключа по умолчаниюПервичные ключи по умолчанию достаточны в большинстве случаев. Вносить изменения следует с осторожностью и только при четком понимании шаблонов запросов. Изменение первичного ключа может ухудшить производительность других сценариев, поэтому тестирование обязательно.
- Выбирайте столбцы, соответствующие вашим типичным фильтрам и паттернам доступа. Если вы обычно начинаете расследование в области обсервабилити с фильтрации по конкретному столбцу, например по имени пода, этот столбец будет часто использоваться в секциях
WHERE. Такие столбцы стоит включать в ключ в первую очередь, а не те, которые используются реже.
- Предпочитайте столбцы, которые при фильтрации позволяют исключить большую часть строк и тем самым сократить объем читаемых данных. Имена сервисов и коды status часто являются хорошими кандидатами — во втором случае только если вы фильтруете по значениям, исключающим большинство строк; например, фильтрация по кодам 200 в большинстве систем охватит большую часть строк, тогда как ошибки 500 будут соответствовать лишь небольшому подмножеству.
- Предпочитайте столбцы, которые, вероятно, будут сильно коррелировать с другими столбцами таблицы. Это поможет обеспечить их смежное хранение, что улучшит сжатие.
- Операции
GROUP BY (агрегации для диаграмм) и ORDER BY (сортировка) по столбцам из ключа сортировки могут быть более эффективны с точки зрения использования памяти.
После того как вы определили подмножество столбцов для ключа сортировки, их нужно объявить в определенном порядке. Этот порядок может существенно влиять как на эффективность фильтрации по вторичным столбцам ключа в запросах, так и на коэффициент сжатия файлов данных таблицы. В общем случае лучше располагать ключи в порядке возрастания мощности. Однако это нужно соотносить с тем, что фильтрация по столбцам, расположенным ближе к концу ключа сортировки, будет менее эффективной, чем по столбцам, находящимся в начале кортежа. Учитывайте этот баланс и свои паттерны доступа. Самое главное — тестируйте разные варианты. Чтобы лучше понять ключи сортировки и способы их оптимизации, рекомендуется прочитать «Выбор первичного ключа», а для еще более глубокого изучения настройки первичного ключа и внутренних структур данных см. «Практическое введение в первичные разреженные индексы в ClickHouse»
Изменение первичного ключа
SeverityText расположен перед ServiceName.
Создайте новую таблицу
Ключ сортировки и первичный ключОбратите внимание: в примере выше необходимо указать PRIMARY KEY и ORDER BY.
В ClickStack они почти всегда совпадают.
ORDER BY управляет физической организацией данных, а PRIMARY KEY определяет разреженный индекс.
В редких случаях при очень больших рабочих нагрузках они могут различаться, но большинству пользователей следует держать их согласованными.
Обменяйте и удалите таблицу
Оператор EXCHANGE используется, чтобы атомарно поменять имена таблиц местами. Временную таблицу (теперь это старая таблица по умолчанию) можно удалить.Дозагрузка существующих данных в новую таблицу в крупных инсталляциях редко оправданна. Затраты на вычислительные ресурсы и IO обычно высоки и не окупаются выигрышем в производительности. Вместо этого дайте старым данным истечь через TTL, а новые данные пусть используют преимущества улучшенного ключа. SeverityText добавляется как первый столбец первичного ключа. В этом случае новая таблица создаётся для новых данных, а старая сохраняется для исторического анализа.
Создайте новую таблицу
Создайте новую таблицу с нужным первичным ключом. Обратите внимание на суффикс _23_01_2025 — замените его на текущую дату. Например:Создайте Merge-таблицу
Движок Merge (не путать с MergeTree) сам не хранит данные, но позволяет одновременно читать из любого числа других таблиц.currentDatabase() предполагает, что команда выполняется в правильной базе данных. В противном случае явно укажите имя базы данных.
otel_logs.Обновите HyperDX, чтобы читать из merge-таблицы
Настройте HyperDX на использование otel_logs_merge в качестве таблицы для источника данных журналов.На этом этапе запись по-прежнему идёт в otel_logs с исходным первичным ключом, а чтение выполняется через merge-таблицу. Для пользователей ничего не меняется, и на ингестию это не влияет.Поменяйте таблицы местами
Теперь оператор EXCHANGE используется для атомарной перестановки имён таблиц otel_logs и otel_logs_23_01_2025.Теперь запись идёт в новую таблицу otel_logs с обновлённым первичным ключом. Существующие данные остаются в otel_logs_23_01_2025 и по-прежнему доступны через merge-таблицу. Суффикс указывает дату применения изменения и соответствует самой поздней временной метке в этой таблице.Этот процесс позволяет изменить первичный ключ без прерывания приёма и без какого-либо заметного влияния для пользователей.SeverityNumber, а не SeverityText. Описанный ниже процесс можно повторять столько раз, сколько потребуется при изменении первичного ключа.
Создайте новую таблицу
Создайте новую таблицу с нужным первичным ключом.
В примере ниже 30_01_2025 используется в качестве суффикса, обозначающего дату таблицы. Например:Обменяйте таблицы
Теперь оператор EXCHANGE используется для атомарной замены имен таблиц otel_logs и otel_logs_30_01_2025.Теперь запись идет в новую таблицу otel_logs с обновленным первичным ключом. Старые данные остаются в otel_logs_30_01_2025 и доступны через merge-таблицу.Избыточные таблицыЕсли настроены политики TTL, что рекомендуется, таблицы со старыми первичными ключами, в которые больше не записываются данные, будут постепенно освобождаться по мере истечения срока хранения данных. Их следует отслеживать и периодически очищать, когда в них больше не остается данных. В настоящее время этот процесс очистки выполняется вручную.
Оптимизация 4. Использование materialized view
Оптимизация 5. Использование проекций
ORDER BY базовой таблицы, что позволяет ClickHouse эффективнее отсекать данные для шаблонов доступа, не соответствующих исходному порядку.
Materialized views могут давать схожий эффект, явно записывая строки в отдельную целевую таблицу с другим ключом сортировки. Главное отличие в том, что проекции поддерживаются ClickHouse автоматически и прозрачно, тогда как materialized views — это явные таблицы, которые ClickStack должен регистрировать и выбирать явно.
Когда запрос обращается к базовой таблице, ClickHouse оценивает базовую структуру и все доступные проекции, анализирует их первичные индексы и выбирает ту структуру, которая позволяет получить корректный результат, прочитав минимальное число гранул. Это решение автоматически принимает анализатор запросов.
Поэтому в ClickStack проекции лучше всего подходят для простого переупорядочивания данных, когда:
- Шаблоны доступа принципиально отличаются от первичного ключа по умолчанию
- Непрактично охватить все сценарии работы одним ключом сортировки
- Вы хотите, чтобы ClickHouse прозрачно выбирал оптимальную физическую структуру
Для предварительной агрегации и ускорения метрик ClickStack настоятельно рекомендует явные materialized views, которые дают уровню приложения полный контроль над выбором и использованием представлений.
Дополнительные сведения см. здесь:
Предположим, что ваша таблица трассировок оптимизирована под стандартный сценарий доступа в ClickStack:
Если у вас есть основной сценарий работы, в котором фильтрация выполняется по TraceId (или данные часто группируются и фильтруются по нему), вы можете добавить проекцию, которая хранит строки, отсортированные по TraceId и времени:
Используйте подстановочные шаблоныВ примере с проекцией выше используется подстановочный шаблон (SELECT *). Хотя выбор подмножества столбцов может снизить накладные расходы на запись, это также ограничивает случаи, когда проекцию можно использовать, поскольку подходят только те запросы, которые можно полностью выполнить по этим столбцам. В ClickStack это часто сводит использование проекций к очень узким сценариям. Поэтому обычно рекомендуется использовать подстановочный шаблон, чтобы максимально расширить область применения.
Материализация проекции может занять много времени и потребовать значительных ресурсов. Поскольку данные обсервабилити обычно удаляются по TTL, делать это следует только в случае крайней необходимости. В большинстве случаев достаточно, чтобы проекция применялась только к вновь принимаемым данным, оптимизируя наиболее часто запрашиваемые временные диапазоны, например последние 24 часа.
SELECT *), а фильтры запроса хорошо согласуются с ORDER BY проекции.
Запросы с фильтрацией по TraceId (особенно на точное совпадение) и указанием временного диапазона выиграют от приведенной выше проекции. Например:
Запросы, которые не ограничивают TraceId или в основном фильтруют по другим измерениям, не являющимся первыми в ключе сортировки проекции, обычно не дают выигрыша (и вместо этого могут читать данные из базовой структуры).
Проекции также могут хранить агрегации (аналогично materialized views). В ClickStack агрегации на основе проекций обычно не рекомендуются, поскольку выбор зависит от анализатора ClickHouse, а их использование сложнее контролировать и предсказать. Вместо этого лучше использовать явные materialized views, которые ClickStack может регистрировать и целенаправленно выбирать на уровне приложения.
- Накладные расходы на вставку: Проекция
SELECT * с другим ключом сортировки фактически приводит к двойной записи данных, что увеличивает I/O при записи и может потребовать дополнительных ресурсов CPU и пропускной способности диска для поддержания ингестии.
- Используйте экономно: Проекции стоит применять только для действительно разных сценариев доступа, когда второй физический порядок даёт заметное отсечение данных для большой доли запросов — например, если две команды работают с одним и тем же набором данных принципиально по-разному.
- Проверяйте с помощью бенчмарков: Как и при любой оптимизации, сравнивайте реальную задержку запросов и использование ресурсов до и после добавления и материализации проекции.
Более подробно см.:
Облегчённые проекции с _part_offset
Облегчённые проекции — в статусе бета для ClickStackОблегчённые проекции на основе _part_offset не рекомендуются для рабочих нагрузок ClickStack. Хотя они уменьшают объём хранилища и I/O при записи, они могут приводить к большему числу произвольных обращений при выполнении запросов, а их поведение в продакшне при нагрузках масштаба обсервабилити всё ещё оценивается. Эта рекомендация может измениться по мере развития этой возможности и накопления большего объёма эксплуатационных данных.
_part_offset в базовой таблице вместо дублирования полных строк. Это может значительно сократить накладные расходы на хранение, а недавние улучшения позволяют выполнять pruning на уровне гранул, из-за чего такие проекции всё больше напоминают настоящие вторичные индексы. См.:
Если вам нужны несколько ключей сортировки, проекции — не единственный вариант. В зависимости от операционных ограничений и того, как вы хотите, чтобы ClickStack направлял запросы, рассмотрите следующие варианты:
- Настройте OpenTelemetry Collector так, чтобы он записывал данные в две таблицы с разными ключами
ORDER BY, и создайте отдельные источники ClickStack для каждой таблицы.
- Создайте materialized view как конвейер копирования, то есть подключите materialized view к основной таблице так, чтобы она записывала необработанные строки во вторичную таблицу с другим ключом сортировки (это шаблон денормализации или маршрутизации). Создайте источник для этой целевой таблицы. Примеры можно найти здесь.
Последнее изменение 19 июня 2026 г.
