Типы Map и JSON в ClickStack

Когда использовать тип Map вместо типа JSON для атрибутов в ClickStack

Схема по умолчанию в ClickStack хранит атрибуты ресурсов, областей видимости, логов и спанов в столбцах Map(LowCardinality(String), String). ClickHouse также поддерживает строго типизированный тип JSON, а в ClickStack есть его поддержка в статусе бета в качестве замены Map.

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

​

Почему Map рекомендуется по умолчанию

В данных обсервабилити преобладают атрибуты ресурсов, областей видимости, а также атрибуты span и log. Эти наборы обычно велики, имеют высокую мощность и поступают с высокой пропускной способностью. Выбранная для этих атрибутов схема в первую очередь определяет затраты на приём и структуру хранения.

Map(LowCardinality(String), String) хранит ключи и значения в единой структуре. Исторически недостаток Map заключался в том, что чтение одного ключа требовало чтения всего столбца Map. Теперь это уже не так: ClickHouse поддерживает сериализацию Map по бакетам, которая разбивает Map на бакеты, так что запросы читают только нужные им бакеты. В сочетании с текстовыми индексами по ключам и значениям Map — именно так настроена схема ClickStack по умолчанию — это делает Map избирательным и быстрым при чтении без дополнительных затрат на приём новых ключей.

На практике это означает следующее:

• Стабильные затраты на приём по мере роста числа ключей. Добавление нового ключа атрибута не меняет структуру столбцов на диске и не создаёт новые файлы столбцов. Затраты на приём ограничиваются объёмом данных, а не мощностью ключей.
• Без взрывного роста метаданных. Количество файлов столбцов на диске не зависит от числа уникальных ключей атрибутов.
• Избирательные lookup через индексы. Текстовые индексы по ключам и значениям Map позволяют выполнять точечные lookup без сканирования каждой строки.
• Предсказуемое поведение при высокой пропускной способности. Map справляется со всплесками бессхемных наборов атрибутов, которые часто встречаются в трассировке и журналах, без накладных расходов на каждый ключ.

​

Почему не JSON по умолчанию

Тип JSON использует другой подход: при вставке ClickHouse динамически создаёт отдельный строго типизированный подстолбец для каждого обнаруженного пути. При чтении это удобно, поскольку считываются только запрошенные подстолбцы, типы сохраняются и не требуется приведение типов во время выполнения запроса.

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

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

​

Когда JSON всё ещё стоит рассмотреть

Тип JSON может быть разумным выбором, если выполняются все следующие условия:

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

Если выполняются не все эти условия, используйте схему по умолчанию на основе Map.

​

Статус бета

Возможность в статусе бета, не готова к промышленной эксплуатации

Поддержка типа JSON в ClickStack находится в статусе бета. Хотя сам тип JSON готов к промышленной эксплуатации в ClickHouse 25.3+, его интеграция в ClickStack все еще активно разрабатывается и может иметь ограничения, измениться в будущем или содержать ошибки.

В ClickStack поддержка типа JSON в статусе бета доступна с версии 2.0.4.

​

Включение поддержки JSON

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

Переменная	Где задаётся	Назначение
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'	OTel collector	Создаёт схемы в ClickHouse с типом JSON.
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true	HyperDX (интерфейс ClickStack)	Позволяет уровню приложения выполнять запросы к схемам с типом JSON. Только для ClickStack с открытым исходным кодом.

​

Управляемый ClickStack

Чтобы включить поддержку JSON в Управляемом ClickStack, до настройки коллектора обратитесь в службу поддержки [e-mail]. Эту возможность также нужно включить в интерфейсе ClickStack (HyperDX) в ClickHouse Cloud.

Установите OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' в коллекторе. Например:

docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

​

ClickStack с открытым исходным кодом

Задайте OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' в любом развертывании, где используется коллектор, и BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true на уровне приложения HyperDX, чтобы оно могло выполнять запросы к схемам, использующим тип JSON.

Например:

docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

​

Миграция со схемы на основе Map на JSON

Обратная совместимость

тип JSON не обратно совместим с существующими схемами на основе Map. Включение этой возможности создаёт новые таблицы с типом JSON и требует ручной миграции данных.

Чтобы перейти со схем на основе Map по умолчанию, выполните следующие шаги:

1. ​

   Остановите OTel коллектор

2. ​

   Переименуйте существующие таблицы и обновите источники данных

   Переименуйте существующие таблицы и обновите источники данных в HyperDX.

   Например:

   RENAME TABLE otel_logs TO otel_logs_map;
   RENAME TABLE otel_metrics TO otel_metrics_map;
   
3. ​

   Разверните коллектор

   Разверните коллектор, задав OTEL_AGENT_FEATURE_GATE_ARG.

4. ​

   Перезапустите контейнер HyperDX с поддержкой схемы JSON

   export BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true
   
5. ​

   Создайте новые источники данных

   Создайте в HyperDX новые источники данных, указывающие на таблицы JSON.

​

Перенос существующих данных (необязательно)

Чтобы перенести старые данные в новые JSON-таблицы:

INSERT INTO otel_logs SELECT * FROM otel_logs_map;
INSERT INTO otel_metrics SELECT * FROM otel_metrics_map;

Рекомендуется только для датасетов размером менее ~10 миллиардов строк. Данные, которые ранее хранились в типе Map, не сохраняли точность типов (все значения были строками). В результате в новой схеме эти старые данные будут отображаться как строки, пока не устареют, поэтому на фронтенде потребуется некоторое приведение типов. Для новых данных точность типов будет сохраняться благодаря типу JSON.