Перейти к основному содержанию

​
Введение

Это руководство посвящено наиболее распространённым и эффективным способам оптимизации производительности ClickStack, которых достаточно для оптимизации большинства реальных рабочих нагрузок обсервабилити — как правило, вплоть до десятков терабайт данных в день. Оптимизации представлены в продуманной последовательности: от самых простых и дающих наибольший эффект методов к более продвинутой и специализированной настройке. Ранние оптимизации следует применять в первую очередь, и нередко уже они сами по себе дают значительный прирост. По мере роста объёмов данных и усложнения рабочих нагрузок всё более целесообразным становится применение последующих методов.

​
Основные понятия ClickHouse

Прежде чем применять описанные в этом руководстве оптимизации, важно понимать несколько ключевых понятий ClickHouse. В ClickStack каждый источник данных напрямую сопоставляется с одной или несколькими таблицами ClickHouse. При использовании OpenTelemetry ClickStack создаёт и поддерживает набор таблиц по умолчанию для хранения журналов, трассировок и метрик. Если вы используете собственные схемы или сами управляете таблицами, скорее всего, эти понятия вам уже знакомы. Однако если вы просто отправляете данные через OpenTelemetry Collector, эти таблицы создаются автоматически, и именно к ним применяются все описанные ниже оптимизации. Таблицы относятся к базам данных в ClickHouse. По умолчанию используется база данных default, но это можно изменить в OpenTelemetry Collector.
Сосредоточьтесь на журналах и трассировкахВ большинстве случаев настройка производительности сосредоточена на таблицах журналов и трассировок. Хотя таблицы метрик тоже можно оптимизировать для фильтрации, их схемы намеренно ориентированы на рабочие нагрузки в стиле Prometheus и обычно не требуют изменений для стандартных графиков. Таблицы журналов и трассировок, напротив, поддерживают более широкий спектр access patterns, поэтому именно они выигрывают от настройки больше всего. Для данных сеансов пользовательский сценарий фиксирован, поэтому их схему редко приходится менять.
Как минимум, вам следует понимать следующие базовые принципы ClickHouse: Эти понятия лежат в основе производительности ClickHouse. Они определяют, как записываются данные, как они организованы на диске и насколько эффективно ClickHouse может пропускать чтение данных во время выполнения запроса. Любая оптимизация в этом руководстве — будь то материализованные столбцы, индекс пропуска данных, первичные ключи, проекции или materialized view — опирается на эти базовые механизмы. Перед началом настройки рекомендуется ознакомиться со следующей документацией ClickHouse: Все описанные ниже оптимизации можно применять непосредственно к базовым таблицам с помощью стандартного ClickHouse SQL — либо через SQL-консоль ClickHouse Cloud, либо через клиент ClickHouse.

​
Оптимизация 1. Материализуйте часто запрашиваемые атрибуты

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

​
Зачем материализовать атрибуты

ClickStack хранит метаданные, такие как метки Kubernetes, метаданные сервисов и пользовательские атрибуты, в столбцах Map(String, String). Это обеспечивает гибкость, но у запросов к вложенным ключам map есть важная особенность с точки зрения производительности. При запросе одного ключа из столбца Map ClickHouse приходится читать с диска весь столбец map целиком. Если map содержит много ключей, это приводит к лишним операциям IO и замедляет запросы по сравнению с чтением отдельного столбца. Материализация часто используемых атрибутов устраняет эти накладные расходы: значение извлекается во время вставки и сохраняется как полноценный столбец. Материализованные столбцы:
  • Вычисляются автоматически во время вставки
  • Не могут быть явно заданы в операторах INSERT
  • Поддерживают любые выражения ClickHouse
  • Позволяют преобразовывать типы из String в более эффективные числовые типы или типы даты
  • Позволяют использовать индекс пропуска данных и первичный ключ
  • Сокращают объём чтения с диска, избавляя от необходимости читать map целиком
ClickStack автоматически обнаруживает материализованные столбцы, извлечённые из map, и прозрачно использует их при выполнении запросов, даже если пользователи продолжают обращаться к исходному пути атрибута.

​
Пример

Рассмотрим схему трассировок ClickStack по умолчанию, в которой метаданные Kubernetes хранятся в 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 *. Это сохраняет инвариант, согласно которому результаты запроса всегда можно повторно вставить в таблицу.

​
Материализация исторических данных

Материализованные столбцы автоматически применяются только к данным, вставленным после создания столбца. Для существующих данных запросы к материализованному столбцу будут прозрачно обращаться к чтению из исходного map. Если производительность запросов к историческим данным критически важна, столбец можно дозагрузить с помощью мутации, например:
При этом переписываются существующие части, чтобы заполнить столбец. Мутации выполняются в одном потоке для каждой части и на больших объёмах данных могут занимать значительное время. Чтобы ограничить их влияние, мутации можно применить только к конкретной партиции:
За прогрессом мутации можно следить с помощью таблицы system.mutations, например.
Дождитесь, пока для соответствующей мутации значение is_done не станет равным 1.
Мутации создают дополнительную нагрузку на IO и CPU, поэтому их следует использовать как можно реже. Во многих случаях достаточно дать старым данным естественным образом устареть и полагаться на повышение производительности для вновь поступающих данных.

​
Оптимизация 2. Добавление индексов пропуска данных

После материализации часто запрашиваемых атрибутов следующий шаг оптимизации — добавить индексы пропуска данных, чтобы ещё сильнее сократить объём данных, которые ClickHouse должен читать при выполнении запросов. Индексы пропуска данных позволяют ClickHouse не сканировать целые блоки данных, если система может определить, что подходящих значений в них нет. В отличие от традиционных вторичных индексов, индексы пропуска данных работают на уровне гранул и наиболее эффективны, когда фильтры запроса исключают значительную часть набора данных. При правильном использовании они могут существенно ускорить фильтрацию по атрибутам с высокой мощностью без изменения семантики запроса. Рассмотрим схему traces по умолчанию для ClickStack, которая включает индексы пропуска данных:
Эти индексы ориентированы на три распространённых шаблона:
  • Фильтрацию строк с высокой мощностью, таких как TraceId, идентификаторы сеансов, ключи или значения атрибутов
  • Фильтрацию по подключам Map, ускоренную текстовыми индексами в столбцах *AttributeItems
  • Фильтрацию по числовым диапазонам, например по длительности span
Таблица logs использует индексы text(tokenizer = 'array') вместо bloom-фильтров, а также добавляет индекс text(tokenizer = 'splitByNonAlpha') для lower(Body) для полнотекстового поиска. Полный DDL см. в разделе “Таблицы и схемы, используемые ClickStack”.

​
bloom-фильтры

Индексы типа bloom-фильтр — наиболее часто используемый тип индекса пропуска данных в ClickStack. Они хорошо подходят для строковых столбцов с высокой мощностью, как правило, не менее десятков тысяч различных значений. Уровень ложноположительных срабатываний 0.01 при гранулярности 1 — хорошая отправная точка по умолчанию, которая обеспечивает баланс между затратами на хранилище и эффективным отсечением данных. Продолжая пример из Optimization 1, предположим, что имя пода Kubernetes было материализовано из ResourceAttributes:
Затем можно добавить индекс пропуска данных с bloom-фильтром, чтобы ускорить фильтрацию по этому столбцу:
После добавления индекс пропуска данных необходимо материализовать — см. “Материализуйте индекс пропуска данных.” После создания и материализации ClickHouse может пропускать целые гранулы, которые заведомо не содержат запрошенное имя пода, что потенциально сокращает объём данных, считываемых при выполнении таких запросов, как PodName:"checkout-675775c4cc-f2p9c". bloom-фильтры наиболее эффективны, когда распределение значений таково, что конкретное значение встречается в относительно небольшом числе частей. Это часто естественным образом происходит в рабочих нагрузках обсервабилити, где такие метаданные, как имена подов, trace ID или идентификаторы сеансов, коррелируют со временем и, следовательно, группируются по ключу сортировки таблицы. Как и любые индексы пропуска данных, bloom-фильтры следует добавлять выборочно и проверять на реальных шаблонах запросов, чтобы убедиться, что они приносят измеримую пользу — см. “Оценка эффективности индекса пропуска данных.”

​
Текстовые индексы

Текстовые индексы предлагают альтернативу bloom-фильтрам. Bloom-фильтр — это вероятностная структура, которая позволяет однозначно исключать гранулы, но допускает ложноположительные срабатывания, поэтому гранулы, которые он не исключил, всё равно приходится загружать и проверять на соответствие условию WHERE. Текстовые индексы — это инвертированные индексы, которые сопоставляют токены с точными смещениями внутри части. Поскольку они анализируют смещения, а не гранулы, и не дают ложноположительных срабатываний, они обычно позволяют обработать условие WHERE без загрузки исходного столбца. Эта оптимизация называется прямое чтение. Поскольку загрузка данных часто занимает основную часть времени выполнения запроса, прямое чтение может заметно снизить задержку запроса. Кроме того, по самим текстовым индексам тоже можно выполнять запросы, что обеспечивает автодополнение и другие возможности интроспекции в ClickStack. Два токенизатора покрывают большинство сценариев ClickStack:

​
Токенизатор Array для Map и столбцов типа Array

В схеме журналов по умолчанию для mapKeys и материализованных массивов элементов используется токенизатор array:
Каждый ключ Map (или элемент массива) становится отдельным токеном. Фильтрация по известному ключу атрибута затем отсекает любую строку, которая его не содержит, без сканирования самого столбца Map. Именно этот механизм делает оптимизацию прямого чтения Map эффективной.

​
splitByNonAlpha для тел log-записей

Полнотекстовому поиску по столбцу Body помогает текстовый индекс splitByNonAlpha. ClickStack определяет этот индекс для lower(Body), чтобы его могли использовать регистронезависимые поисковые запросы Lucene:
Когда ClickStack обнаруживает индекс text(tokenizer = 'splitByNonAlpha') для lower(Body), он преобразует Lucene-запросы с неявно указанным столбцом, такие как error или "connection refused", в hasAllTokens(lower(Body), lower(...)), так что индекс может обработать их без чтения всего столбца Body. Для большинства рабочих нагрузок с логами в обсервабилити это самое существенное доступное ускорение фильтрации.
Текстовые индексы и tokenbf_v1Более старый тип индекса tokenbf_v1 (он по-прежнему используется в схеме traces по умолчанию для lower(SpanName)) функционально похож, но в ClickHouse 26.2 и выше помечен как устаревший. Для новых индексов полнотекстового поиска следует использовать text(tokenizer = ...).
Подробное описание параметров токенизатора, препроцессоров и способов проверки см. в документации по полнотекстовому поиску.

​
Текстовые индексы в схеме журналов по умолчанию

Схема otel_logs по умолчанию, синхронизированная с upstream, содержит все рассмотренные выше текстовые индексы: text(tokenizer = 'array') для TraceId, каждого mapKeys(...) и массива *AttributeItems, а также text(tokenizer = 'splitByNonAlpha') для lower(Body) для полнотекстового поиска. Канонический DDL см. в разделе “Таблицы и схемы, используемые ClickStack”; та же схема приведена ниже.

​
Индексы minmax

Индексы 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, чтобы подтвердить отсечение, а затем выполните бенчмарк, чтобы подтвердить итоговый прирост производительности.

​
Когда добавлять индексы пропуска данных

Индексы пропуска данных следует добавлять выборочно, исходя из того, какие фильтры пользователи применяют чаще всего, и как устроены данные в частях и гранулах. Цель состоит в том, чтобы отсечь достаточно гранул и тем самым компенсировать затраты на вычисление самого индекса, поэтому бенчмаркинг на данных, близких к продакшн, крайне важен. Для числовых столбцов, используемых в фильтрах, индекс пропуска данных minmax почти всегда является удачным выбором. Он лёгкий, дёшев в вычислении и может быть эффективен для диапазонных предикатов — особенно когда значения слабо упорядочены или ограничены узкими диапазонами внутри частей. Даже если minmax не помогает для конкретного шаблона запроса, его накладные расходы обычно настолько малы, что его всё равно имеет смысл оставить. Для строковых столбцов по возможности предпочитайте текстовые индексы; в противном случае используйте bloom-фильтры. Текстовые индексы ускоряют те же фильтры на равенство и IN, что и bloom-фильтры, а также дополнительно позволяют использовать предикаты на основе токенов (hasToken, hasAllTokens, has), применяемые в полнотекстовом поиске и оптимизации прямого чтения Map. В старых кластерах, которые ещё не поддерживают текстовые индексы, bloom-фильтры по-прежнему остаются надёжным выбором. bloom-фильтры наиболее эффективны для строковых столбцов с высокой мощностью, где каждое значение встречается сравнительно редко, то есть в большинстве частей и гранул искомое значение отсутствует. Как правило, bloom-фильтры наиболее перспективны, когда столбец содержит не менее 10 000 различных значений, и часто показывают наилучшие результаты при 100 000+ различных значений. Они также эффективнее, когда совпадающие значения сгруппированы в небольшом числе последовательных частей, что обычно происходит, когда столбец коррелирует с ключом сортировки. И здесь результат может отличаться — ничто не заменит тестирование на реальных данных.

​
Оптимизация 3. Прямое чтение Map

Когда вы фильтруете по подключу Map, например LogAttributes['k8s.pod.name'] = 'checkout', ClickHouse должен прочитать с диска весь столбец Map LogAttributes и распаковать каждую строку, чтобы проверить предикат. Материализация часто запрашиваемых атрибутов решает эту задачу для ключей, которые известны заранее, но не масштабируется на произвольные атрибуты, по которым пользователи фильтруют по мере необходимости. Даже если схема содержит индексы по mapKeys и mapValues, эти индексы могут показать, есть ли у строки заданный ключ и есть ли у неё заданное значение, но не могут определить, относятся ли ключ и значение к одной и той же записи. Иначе говоря, mapKeys отвечает на mapContainsKey(ResourceAttributes, 'foo'), а mapValues — на mapContainsValue(ResourceAttributes, 'bar'), но ни один из них не отвечает на ResourceAttributes['foo'] = 'bar'. За счёт объединения ключей и значений в один столбец Array(String) оптимизация прямого чтения Map позволяет обрабатывать ResourceAttributes['foo'] = 'bar' без загрузки исходной Map. Maps часто бывают большими и увеличиваются в размере по мере роста объёма. В сочетании с переписыванием запроса на уровне приложения фильтры равенства по любому подключу Map сводятся к одному вызову has(...), использующему этот индекс, без десериализации Map во время выполнения запроса. Кроме того, дополнительные затраты на хранилище есть только у текстового индекса, поскольку исходный столбец является столбцом ALIAS и не хранится. Эта оптимизация работает автоматически. ClickStack включает необходимые столбцы и индексы в стандартные таблицы журналов и трассировок и переписывает фильтры по обращению к элементам Map во время выполнения, когда подключённый ClickHouse server поддерживает базовый примитив. Если в вашей схеме нет этих столбцов или у вас есть дополнительные столбцы Map, которые вы хотите ускорить сверх стандартного набора, читайте далее, чтобы включить их.

​
Схема

Для каждого столбца Map, чтение которого вы хотите ускорить, ClickStack создаёт столбец Array(String) ALIAS, в котором каждый ключ соединяется со значением через =:
Форма ALIAS означает, что массив не занимает байты на диске. ClickHouse вычисляет его во время выполнения запроса и при построении индекса. text(tokenizer = 'array') индекс пропуска данных для столбца ALIAS хранит один токен для каждой пары key=value, который ClickHouse использует, чтобы отсекать гранулы, не обращаясь к исходному Map:
После создания индекса в существующей таблице материализуйте его, чтобы он применялся и к историческим данным (см. “Материализовать индекс пропуска данных”). В схемах ClickStack по умолчанию предусмотрены следующие столбцы и индексы:

​
Перезапись запроса

Когда пользователь применяет фильтр по подключу Map через интерфейс ClickStack или SDK, ClickStack перезаписывает:
в:
Преобразованная форма задействует текстовый индекс по LogAttributeItems, отсекает целые строки, которые не содержат токен key=value, и никогда не десериализует исходный Map LogAttributes для несовпадающих строк. Для рабочих нагрузок обсервабилити с высокой мощностью это обычно даёт сокращение I/O на порядок по сравнению с доступом к элементам Map по индексу. Преобразование выполняется автоматически — сохранённые запросы, панели мониторинга и алерты, которые ссылаются на LogAttributes['key'], получают ускорение без каких-либо изменений.

​
Требования к версии ClickHouse

Для перезаписи запроса требуется версия ClickHouse, поддерживающая прямое pruning на уровне токенов для столбцов типа Array с текстовым индексом. ClickStack определяет версию подключённого сервера (SELECT version(), кэшируется для каждого подключения) и использует rewritten form только тогда, когда версия сервера не ниже пороговой. На более старых серверах автоматически используется исходная форма с обращением к Map по индексу.
Почему ALIAS, а не MATERIALIZEDМассив items — это представление данных, которые уже хранятся в столбце Map. Хранение этих данных дважды — один раз в Map, второй раз в массиве — удвоило бы I/O при записи, не открыв новых шаблонов запроса. Текстовый индекс для столбца ALIAS строится во время вставки из тех же исходных данных, поэтому эта оптимизация добавляет на диск только объём самого индекса.

​
Оптимизация 4. Изменение первичного ключа

Первичный ключ — один из важнейших элементов настройки производительности ClickHouse для большинства рабочих нагрузок. Чтобы эффективно его настраивать, нужно понимать, как он работает и как соотносится с вашими шаблонами запросов. В конечном итоге первичный ключ должен соответствовать тому, как пользователи обращаются к данным, и особенно тому, по каким столбцам они чаще всего фильтруют данные. Хотя первичный ключ также влияет на сжатие и структуру хранения, его основное назначение — производительность запросов. В ClickStack первичные ключи по умолчанию уже оптимизированы под наиболее распространённые паттерны доступа в задачах обсервабилити и обеспечивают хорошее сжатие. Ключи по умолчанию для таблиц журналов, трассировок и метрик спроектированы так, чтобы хорошо работать в типовых сценариях. Фильтрация по столбцам, которые расположены раньше в первичном ключе, эффективнее, чем по столбцам, расположенным позже. Хотя конфигурации по умолчанию достаточно для большинства пользователей, в некоторых случаях изменение первичного ключа может повысить производительность для конкретных рабочих нагрузок.
Примечание о терминологииВ этом документе термин “ключ сортировки” используется как взаимозаменяемый с термином “первичный ключ”. Строго говоря, в ClickHouse это разные понятия, но в ClickStack они обычно относятся к одним и тем же столбцам, указанным в ORDER BY таблицы. Подробнее см. документацию ClickHouse о выборе первичного ключа, отличающегося от ключа сортировки.
Прежде чем изменять какой-либо первичный ключ, настоятельно рекомендуем ознакомиться с нашим руководством по пониманию работы первичных индексов в ClickHouse: Настройка первичного ключа зависит от конкретной таблицы и типа данных. Изменение, полезное для одной таблицы и одного типа данных, может не подойти для других. Цель всегда состоит в том, чтобы оптимизировать работу с определённым типом данных, например с журналами. Обычно оптимизируют таблицы журналов и трассировок. Необходимость изменять первичный ключ для других типов данных возникает редко. Ниже приведены первичные ключи по умолчанию для таблиц ClickStack с журналами и трассировками.
  • Логи (otel_logs) - (toStartOfFiveMinutes(Timestamp), ServiceName, Timestamp)
  • Трассировки (otel_traces) - (ServiceName, SpanName, toDateTime(Timestamp))
См. “Таблицы и схемы, используемые в ClickStack”, чтобы узнать, какие первичные ключи используются в таблицах для других типов данных. Таблицы трассировок оптимизированы для фильтрации по имени сервиса и имени span, а затем по временной метке. В таблицах журналов первым идёт пятиминутный временной бакет, чтобы сканирование по диапазону времени сначала использовало первичный индекс, а затем сужалось по имени сервиса внутри каждого бакета — такая структура хорошо подходит для типового сценария «что произошло за последние N минут в сервисе X». Хотя оптимально, если пользователь применяет фильтры в порядке столбцов первичного ключа, запросы всё равно существенно выигрывают от фильтрации по любому из этих столбцов в любом порядке, поскольку ClickHouse отсекает данные до чтения. При выборе первичного ключа есть и другие факторы, которые влияют на оптимальный порядок столбцов. См. “Выбор первичного ключа.” Первичные ключи следует изменять отдельно для каждой таблицы. То, что имеет смысл для журналов, может не подходить для трассировок или метрик.

​
Выбор первичного ключа

Сначала определите, насколько ваши паттерны доступа для конкретной таблицы отличаются от значений по умолчанию. Например, если чаще всего вы фильтруете журналы по узлу Kubernetes, а уже потом по имени сервиса, и это основной сценарий работы, изменение первичного ключа может быть оправданно.
Изменение первичного ключа по умолчаниюПервичные ключи по умолчанию достаточны в большинстве случаев. Вносить изменения следует с осторожностью и только при четком понимании шаблонов запросов. Изменение первичного ключа может ухудшить производительность других сценариев, поэтому тестирование обязательно.
После того как вы определили нужные столбцы, можно приступать к оптимизации ключа сортировки/первичного ключа. Чтобы упростить выбор ключа сортировки, можно руководствоваться несколькими простыми правилами. Иногда они могут противоречить друг другу, поэтому рассматривайте их по порядку. Старайтесь выбирать не более 4–5 ключей:
  1. Выбирайте столбцы, соответствующие вашим типичным фильтрам и паттернам доступа. Если вы обычно начинаете расследование в области обсервабилити с фильтрации по конкретному столбцу, например по имени пода, этот столбец будет часто использоваться в секциях WHERE. Такие столбцы стоит включать в ключ в первую очередь, а не те, которые используются реже.
  2. Предпочитайте столбцы, которые при фильтрации позволяют исключить большую часть строк и тем самым сократить объем читаемых данных. Имена сервисов и коды status часто являются хорошими кандидатами — во втором случае только если вы фильтруете по значениям, исключающим большинство строк; например, фильтрация по кодам 200 в большинстве систем охватит большую часть строк, тогда как ошибки 500 будут соответствовать лишь небольшому подмножеству.
  3. Предпочитайте столбцы, которые, вероятно, будут сильно коррелировать с другими столбцами таблицы. Это поможет обеспечить их смежное хранение, что улучшит сжатие.
  4. Операции GROUP BY (агрегации для диаграмм) и ORDER BY (сортировка) по столбцам из ключа сортировки могут быть более эффективны с точки зрения использования памяти.
После того как вы определили подмножество столбцов для ключа сортировки, их нужно объявить в определенном порядке. Этот порядок может существенно влиять как на эффективность фильтрации по вторичным столбцам ключа в запросах, так и на коэффициент сжатия файлов данных таблицы. В общем случае лучше располагать ключи в порядке возрастания мощности. Однако это нужно соотносить с тем, что фильтрация по столбцам, расположенным ближе к концу ключа сортировки, будет менее эффективной, чем по столбцам, находящимся в начале кортежа. Учитывайте этот баланс и свои паттерны доступа. Самое главное — тестируйте разные варианты. Чтобы лучше понять ключи сортировки и способы их оптимизации, рекомендуется прочитать «Выбор первичного ключа», а для еще более глубокого изучения настройки первичного ключа и внутренних структур данных см. «Практическое введение в первичные разреженные индексы в ClickHouse»

​
Изменение первичного ключа

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

​
Создайте новую таблицу

Ключ сортировки и первичный ключОбратите внимание: в примере выше необходимо указать PRIMARY KEY и ORDER BY. В ClickStack они почти всегда совпадают. ORDER BY управляет физической организацией данных, а PRIMARY KEY определяет разреженный индекс. В редких случаях при очень больших рабочих нагрузках они могут различаться, но большинству пользователей следует держать их согласованными.
2

​
Обменяйте и удалите таблицу

Оператор EXCHANGE используется, чтобы атомарно поменять имена таблиц местами. Временную таблицу (теперь это старая таблица по умолчанию) можно удалить.
Однако первичный ключ нельзя изменить в существующей таблице. Чтобы изменить его, нужно создать новую таблицу. Следующий процесс позволяет сохранить старые данные и при этом прозрачно продолжать выполнять к ним запросы (при необходимости — используя их существующий ключ в интерфейсе ClickStack), а новые данные направлять в новую таблицу, оптимизированную под шаблоны доступа пользователей. Такой подход позволяет не менять конвейеры приёма: данные по-прежнему отправляются в таблицы с именами по умолчанию, а все изменения остаются незаметными для пользователей.
Дозагрузка существующих данных в новую таблицу в крупных инсталляциях редко оправданна. Затраты на вычислительные ресурсы и IO обычно высоки и не окупаются выигрышем в производительности. Вместо этого дайте старым данным истечь через TTL, а новые данные пусть используют преимущества улучшенного ключа.
Ниже используется тот же пример, где SeverityText добавляется как первый столбец первичного ключа. В этом случае новая таблица создаётся для новых данных, а старая сохраняется для исторического анализа.
1

​
Создайте новую таблицу

Создайте новую таблицу с нужным первичным ключом. Обратите внимание на суффикс _23_01_2025 — замените его на текущую дату. Например:
2

​
Создайте Merge-таблицу

Движок Merge (не путать с MergeTree) не хранит данные сам, но позволяет одновременно читать из любого количества других таблиц.
currentDatabase() предполагает, что команда выполняется в нужной базе данных. В противном случае явно укажите имя базы данных.
Теперь можно выполнить запрос к этой таблице и убедиться, что она возвращает данные из otel_logs.
3

​
Обновите интерфейс ClickStack, чтобы читать из merge-таблицы

Настройте интерфейс ClickStack так, чтобы для источника данных журналов использовалась таблица otel_logs_merge.На этом этапе запись по-прежнему идёт в otel_logs с исходным первичным ключом, а чтение использует merge-таблицу. Для пользователей нет видимых изменений, и на ингестию это не влияет.
4

​
Обменяйте таблицы

Теперь для атомарного обмена именами таблиц otel_logs и otel_logs_23_01_2025 используется оператор EXCHANGE.
Теперь запись идёт в новую таблицу otel_logs с обновлённым первичным ключом. Существующие данные остаются в otel_logs_23_01_2025 и по-прежнему доступны через merge-таблицу. Суффикс указывает дату применения изменения и соответствует самой поздней временной метке в этой таблице.Этот процесс позволяет изменять первичный ключ без прерывания приёма и без видимого влияния на пользователей.
Этот процесс можно адаптировать, если потребуется внести дополнительные изменения в первичный ключ. Например, если через неделю вы решите, что в состав первичного ключа на самом деле должен входить SeverityNumber, а не SeverityText. Описанный ниже процесс можно повторять столько раз, сколько потребуется при изменении первичного ключа.
1

​
Создайте новую таблицу

Создайте новую таблицу с нужным первичным ключом. В примере ниже 30_01_2025 используется в качестве суффикса, обозначающего дату таблицы. Например:
2

​
Обменяйте таблицы

Теперь оператор EXCHANGE используется для атомарной замены имен таблиц otel_logs и otel_logs_30_01_2025.
Теперь запись идёт в новую таблицу otel_logs с обновлённым первичным ключом. Старые данные остаются в otel_logs_30_01_2025 и доступны через merge-таблицу.
Избыточные таблицыЕсли настроены политики TTL, что рекомендуется, таблицы со старыми первичными ключами, в которые больше не записываются данные, будут постепенно освобождаться по мере истечения срока хранения данных. Их следует отслеживать и периодически очищать, когда в них больше не остается данных. В настоящее время этот процесс очистки выполняется вручную.

​
Ускорение поиска по строкам с помощью блочных столбцов

Схема журналов ClickStack по умолчанию включает две настройки MergeTree, которые не влияют напрямую на производительность запросов, но существенно ускоряют поиск подробной информации по строкам в интерфейсе ClickStack:
С этими настройками каждая строка в таблице неявно содержит пару (_block_number, _block_offset), которая однозначно идентифицирует её внутри части. Когда вы нажимаете строку журнала в интерфейсе ClickStack, чтобы открыть панель сведений, ClickStack выполняет дополнительный запрос, чтобы получить именно эту строку. Без блочных столбцов предложение WHERE для строки должно включать достаточно столбцов — обычно первичный ключ плюс Body и SeverityText — чтобы однозначно определить строку. С блочными столбцами достаточно первичного ключа, _block_number и _block_offset. Большие столбцы, такие как Body, при таком поиске не читаются, что фактически ускоряет запрос. ClickStack определяет эту настройку из оператора CREATE таблицы и автоматически формирует более компактное предложение WHERE, когда включены оба столбца. Никаких изменений в конфигурации приложения не требуется. Чтобы применить эту оптимизацию к существующей таблице журналов или трассировок:
Настройки применяются к данным, записанным после ALTER. Существующие части по-прежнему используют старый построчный lookup, пока их не перепишет процесс слияния.

​
Оптимизация 5. Использование materialized view

ClickStack может использовать incremental materialized view для ускорения визуализаций, которые зависят от запросов с интенсивной агрегацией, например при расчете средней длительности запросов по минутам во времени. Эта возможность может значительно повысить производительность запросов и обычно наиболее полезна для крупных развертываний — от 10 ТБ в день и выше, — при этом позволяя масштабироваться до диапазона PB в день. incremental materialized view находятся в статусе бета, поэтому использовать их следует с осторожностью. Подробнее об использовании этой возможности в ClickStack см. в отдельном руководстве “ClickStack - Materialized Views.”

​
Оптимизация 6. Использование проекций

Проекции — это заключительный, продвинутый этап оптимизации, к которому стоит переходить после рассмотрения материализованных столбцов, индексов пропуска данных, первичных ключей и materialized views. Хотя проекции и materialized views могут показаться похожими, в ClickStack они решают разные задачи и лучше подходят для разных сценариев.
На практике проекцию можно рассматривать как дополнительную скрытую копию таблицы, которая хранит те же строки в ином физическом порядке. Благодаря этому у проекции есть собственный первичный индекс, отличный от ключа ORDER BY базовой таблицы, что позволяет ClickHouse эффективнее отсекать данные для шаблонов доступа, не соответствующих исходному порядку. Materialized views могут давать схожий эффект, явно записывая строки в отдельную целевую таблицу с другим ключом сортировки. Главное отличие в том, что проекции поддерживаются ClickHouse автоматически и прозрачно, тогда как materialized views — это явные таблицы, которые ClickStack должен регистрировать и выбирать явно. Когда запрос обращается к базовой таблице, ClickHouse оценивает базовую структуру и все доступные проекции, анализирует их первичные индексы и выбирает ту структуру, которая позволяет получить корректный результат, прочитав минимальное число гранул. Это решение автоматически принимает анализатор запросов. Поэтому в ClickStack проекции лучше всего подходят для простого переупорядочивания данных, когда:
  • Шаблоны доступа принципиально отличаются от первичного ключа по умолчанию
  • Непрактично охватить все сценарии работы одним ключом сортировки
  • Вы хотите, чтобы ClickHouse прозрачно выбирал оптимальную физическую структуру
Для предварительной агрегации и ускорения метрик ClickStack настоятельно рекомендует явные materialized views, которые дают уровню приложения полный контроль над выбором и использованием представлений. Дополнительные сведения см. здесь:

​
Пример проекций

Предположим, что ваша таблица трассировок оптимизирована под стандартный сценарий доступа в ClickStack:
Если у вас есть основной сценарий работы, в котором фильтрация выполняется по TraceId (или данные часто группируются и фильтруются по нему), вы можете добавить проекцию, которая хранит строки, отсортированные по TraceId и времени:
Используйте подстановочные шаблоныВ примере с проекцией выше используется подстановочный шаблон (SELECT *). Хотя выбор подмножества столбцов может снизить накладные расходы на запись, это также ограничивает случаи, когда проекцию можно использовать, поскольку подходят только те запросы, которые можно полностью выполнить по этим столбцам. В ClickStack это часто сводит использование проекций к очень узким сценариям. Поэтому обычно рекомендуется использовать подстановочный шаблон, чтобы максимально расширить область применения.
Как и другие изменения структуры данных, проекция влияет только на вновь записанные части. Чтобы применить её к существующим данным, материализуйте её:
Материализация проекции может занять много времени и потребовать значительных ресурсов. Поскольку данные обсервабилити обычно удаляются по TTL, делать это следует только в случае крайней необходимости. В большинстве случаев достаточно, чтобы проекция применялась только к вновь принимаемым данным, оптимизируя наиболее часто запрашиваемые временные диапазоны, например последние 24 часа.
ClickHouse может автоматически выбрать проекцию, если оценит, что она будет сканировать меньше гранул, чем базовая структура. Проекции работают наиболее надежно, когда представляют собой простое переупорядочивание полного набора строк (SELECT *), а фильтры запроса хорошо согласуются с ORDER BY проекции. Запросы с фильтрацией по TraceId (особенно на точное совпадение) и указанием временного диапазона выиграют от приведенной выше проекции. Например:
Запросы, которые не ограничивают TraceId или в основном фильтруют по другим измерениям, не являющимся первыми в ключе сортировки проекции, обычно не дают выигрыша (и вместо этого могут читать данные из базовой структуры).
Проекции также могут хранить агрегации (аналогично materialized views). В ClickStack агрегации на основе проекций обычно не рекомендуются, поскольку выбор зависит от анализатора ClickHouse, а их использование сложнее контролировать и предсказать. Вместо этого лучше использовать явные materialized views, которые ClickStack может регистрировать и целенаправленно выбирать на уровне приложения.
На практике проекции лучше всего подходят для сценариев, где вы часто переходите от более широкого поиска к детальному анализу конкретного трейса (например, извлекая все spans для определённого TraceId).

​
Издержки и рекомендации

  • Накладные расходы на вставку: Проекция SELECT * с другим ключом сортировки фактически приводит к двойной записи данных, что увеличивает I/O при записи и может потребовать дополнительных ресурсов CPU и пропускной способности диска для поддержания ингестии.
  • Используйте экономно: Проекции стоит применять только для действительно разных сценариев доступа, когда второй физический порядок даёт заметное отсечение данных для большой доли запросов — например, если две команды работают с одним и тем же набором данных принципиально по-разному.
  • Проверяйте с помощью бенчмарков: Как и при любой оптимизации, сравнивайте реальную задержку запросов и использование ресурсов до и после добавления и материализации проекции.
Более подробно см.:

​
Облегчённые проекции с _part_offset

Облегчённые проекции — в статусе бета для ClickStackОблегчённые проекции на основе _part_offset не рекомендуются для рабочих нагрузок ClickStack. Хотя они уменьшают объём хранилища и I/O при записи, они могут приводить к большему числу произвольных обращений при выполнении запросов, а их поведение в продакшне при нагрузках масштаба обсервабилити всё ещё оценивается. Эта рекомендация может измениться по мере развития этой возможности и накопления большего объёма эксплуатационных данных.
Новые версии ClickHouse также поддерживают ещё более лёгкие проекции, которые хранят только ключ сортировки проекции и указатель _part_offset в базовой таблице вместо дублирования полных строк. Это может значительно сократить накладные расходы на хранение, а недавние улучшения позволяют выполнять pruning на уровне гранул, из-за чего такие проекции всё больше напоминают настоящие вторичные индексы. См.:

​
Альтернативы

Если вам нужны несколько ключей сортировки, проекции — не единственный вариант. В зависимости от операционных ограничений и того, как вы хотите, чтобы ClickStack направлял запросы, рассмотрите следующие варианты:
  • Настройте OpenTelemetry Collector так, чтобы он записывал данные в две таблицы с разными ключами ORDER BY, и создайте отдельные источники ClickStack для каждой таблицы.
  • Создайте materialized view как конвейер копирования, то есть подключите materialized view к основной таблице так, чтобы она записывала необработанные строки во вторичную таблицу с другим ключом сортировки (это шаблон денормализации или маршрутизации). Создайте источник для этой целевой таблицы. Примеры можно найти здесь.
Последнее изменение 25 июня 2026 г.