Параметры конфигурации

Параметры конфигурации ClickStack — стека обсервабилити ClickHouse

Для каждого компонента ClickStack доступны следующие параметры конфигурации:

​

Настройки для дистрибутивов с открытым исходным кодом

​

Docker

Если вы используете All in One, HyperDX Only или Local Mode, просто задайте нужный параметр через переменную окружения, например:

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

​

Docker Compose

Если вы используете руководство по развертыванию Docker Compose, для изменения настроек можно использовать файл .env.

Либо можно явно переопределить настройки в файле docker-compose.yaml, например:

Пример:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... другие настройки

​

Helm

​

Настройка значений (необязательно)

Вы можете изменить значения с помощью флагов --set, например:

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

Или отредактируйте values.yaml. Чтобы получить значения по умолчанию:

helm show values hyperdx/hdx-oss-v2 > values.yaml

Пример конфигурации:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

​

Приложение ClickStack: интерфейс HyperDX

​

Настройки источника данных

Интерфейс ClickStack предполагает, что пользователь задаёт источник для каждого из типов/основных сигналов данных обсервабилити:

• Logs
• Traces
• Metrics
• Sessions

Эту конфигурацию можно выполнить в приложении через Team Settings -> Sources, как показано ниже на примере журналов:

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

Если используется стандартная схема OpenTelemetry (OTel), поставляемая с ClickStack, эти столбцы могут быть автоматически определены для каждого источника. Если схема изменена или используется пользовательская схема, пользователи должны указать и обновлять эти сопоставления вручную.

Стандартная схема ClickHouse, поставляемая с ClickStack, — это схема, создаваемая экспортером ClickHouse для OTel collector. Имена этих столбцов соответствуют официальной спецификации OTel, описанной здесь.

Для каждого источника доступны следующие настройки:

​

Журналы

Настройка	Описание	Обязательно	Определяется в схеме по умолчанию	Определённое значение
Name	Имя источника.	Да	Нет	–
Server Connection	Имя подключения к серверу.	Да	Нет	Default
Database	Имя базы данных ClickHouse.	Да	Да	default
Table	Имя целевой таблицы. Укажите otel_logs, если используется схема по умолчанию.	Да	Нет
Timestamp Column	Столбец даты и времени или выражение, входящее в первичный ключ.	Да	Да	TimestampTime
Default Select	Столбцы, отображаемые в результатах поиска по умолчанию.	Да	Да	Timestamp, ServiceName, SeverityText, Body
Service Name Expression	Выражение или столбец для имени сервиса.	Да	Да	ServiceName
Log Level Expression	Выражение или столбец для уровня журнала.	Да	Да	SeverityText
Body Expression	Выражение или столбец для сообщения журнала.	Да	Да	Body
Log Attributes Expression	Выражение или столбец для пользовательских атрибутов журнала.	Да	Да	LogAttributes
Resource Attributes Expression	Выражение или столбец для атрибутов на уровне ресурса.	Да	Да	ResourceAttributes
Displayed Timestamp Column	Столбец временной метки, используемый для отображения в интерфейсе.	Да	Да	ResourceAttributes
Correlated Metric Source	Связанный источник метрик (например, метрики HyperDX).	Нет	Нет	–
Correlated Trace Source	Связанный источник трасс (например, трассы HyperDX).	Нет	Нет	–
Trace Id Expression	Выражение или столбец, используемые для извлечения trace ID.	Да	Да	TraceId
Span Id Expression	Выражение или столбец, используемые для извлечения span ID.	Да	Да	SpanId
Implicit Column Expression	Столбец, используемый для полнотекстового поиска, если поле не указано (в стиле Lucene). Обычно это тело журнала.	Да	Да	Body
Highlighted Attributes	Выражения или столбцы, отображаемые при открытии сведений о журнале. Выражения, возвращающие URL, будут показаны как ссылки.	Нет	Нет	–
Highlighted Trace Attributes	Выражения или столбцы, извлекаемые из каждой записи журнала в трассе и отображаемые над waterfall-диаграммой трассы. Выражения, возвращающие URL, будут показаны как ссылки.	Нет	Нет	–

​

Трассировки

Setting	Description	Required	Inferred in Default Schema	Inferred Value
Name	Имя источника.	Да	Нет	–
Server Connection	Имя подключения к серверу.	Да	Нет	Default
Database	Имя базы данных ClickHouse.	Да	Да	default
Table	Имя целевой таблицы. Укажите otel_traces, если используете схему по умолчанию.	Да	Да	-
Timestamp Column	Столбец типа datetime или выражение, входящее в состав первичного ключа.	Да	Да	Timestamp
Timestamp	Псевдоним для Timestamp Column.	Да	Да	Timestamp
Default Select	Столбцы, отображаемые в результатах поиска по умолчанию.	Да	Да	Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName
Duration Expression	Выражение для вычисления длительности спана.	Да	Да	Duration
Duration Precision	Точность выражения длительности (например, наносекунды, микросекунды).	Да	Да	ns
Trace Id Expression	Выражение или столбец для trace ID.	Да	Да	TraceId
Span Id Expression	Выражение или столбец для span ID.	Да	Да	SpanId
Parent Span Id Expression	Выражение или столбец для ID родительского спана.	Да	Да	ParentSpanId
Span Name Expression	Выражение или столбец для имени спана.	Да	Да	SpanName
Span Kind Expression	Выражение или столбец для типа спана (например, client, server).	Да	Да	SpanKind
Correlated Log Source	Необязательно. Связанный источник логов (например, логи HyperDX).	Нет	Нет	–
Correlated Session Source	Необязательно. Связанный источник сеансов.	Нет	Нет	–
Correlated Metric Source	Необязательно. Связанный источник метрик (например, метрики HyperDX).	Нет	Нет	–
Status Code Expression	Выражение для кода состояния спана.	Да	Да	StatusCode
Status Message Expression	Выражение для сообщения о состоянии спана.	Да	Да	StatusMessage
Service Name Expression	Выражение или столбец для имени сервиса.	Да	Да	ServiceName
Resource Attributes Expression	Выражение или столбец для атрибутов на уровне ресурса.	Да	Да	ResourceAttributes
Event Attributes Expression	Выражение или столбец для атрибутов событий.	Да	Да	SpanAttributes
Span Events Expression	Выражение для извлечения событий спана. Обычно это столбец типа Nested. Это позволяет отображать трассировки стека исключений при использовании поддерживаемых language SDKs.	Да	Да	Events
Implicit Column Expression	Столбец, используемый для полнотекстового поиска, если поле не указано (в стиле Lucene). Обычно это тело лога.	Да	Да	SpanName
Highlighted Attributes	Выражения или столбцы, отображаемые при открытии сведений о спане. Выражения, возвращающие URL, будут показаны как ссылки.	Нет	Нет	–
Highlighted Trace Attributes	Выражения или столбцы, извлекаемые из каждого спана в trace и отображаемые над trace waterfall. Выражения, возвращающие URL, будут показаны как ссылки.	Нет	Нет	–

​

Метрики

Параметр	Описание	Обязательно	Определяется в схеме по умолчанию	Определяемое значение
Name	Имя источника.	Да	Нет	–
Server Connection	Имя подключения к серверу.	Да	Нет	Default
Database	Имя базы данных ClickHouse.	Да	Да	default
Gauge Table	Таблица для хранения метрик типа Gauge.	Да	Нет	otel_metrics_gauge
Histogram Table	Таблица для хранения метрик типа Histogram.	Да	Нет	otel_metrics_histogram
Sum Table	Таблица для хранения метрик типа Sum (Counter).	Да	Нет	otel_metrics_sum
Correlated Log Source	Необязательно. Связанный источник логов (например, логи HyperDX).	Нет	Нет	–

​

Сеансы

Настройка	Описание	Обязательно	Определяется в схеме по умолчанию	Определённое значение
Name	Имя источника.	Да	Нет	–
Server Connection	Имя подключения к серверу.	Да	Нет	Default
Database	Имя базы данных ClickHouse.	Да	Да	default
Table	Целевая таблица для данных сеансов. Имя целевой таблицы. Установите значение hyperdx_sessions, если используете схему по умолчанию.	Да	Да	-
Timestamp Column	Столбец с датой и временем или выражение, входящее в состав первичного ключа.	Да	Да	TimestampTime
Log Attributes Expression	Выражение для извлечения атрибутов логов из данных сеансов.	Да	Да	LogAttributes
LogAttributes	Псевдоним или ссылка на поле, используемые для хранения атрибутов логов.	Да	Да	LogAttributes
Resource Attributes Expression	Выражение для извлечения метаданных ресурса.	Да	Да	ResourceAttributes
Correlated Trace Source	Необязательно. Связанный источник трассировок для корреляции сеансов.	Нет	Нет	–
Implicit Column Expression	Столбец, используемый для полнотекстового поиска, если поле не указано (например, при разборе запросов в стиле Lucene).	Да	Да	Body

​

Выделенные атрибуты

Выделенные атрибуты и выделенные атрибуты трейсов можно настроить для источников данных Log и Trace.

• Выделенные атрибуты — это столбцы или выражения, которые отображаются для каждого лога или спана при просмотре сведений о логе или спане.
• Выделенные атрибуты трейсов — это столбцы или выражения, которые запрашиваются для каждого лога или спана в трейсе и отображаются над waterfall-диаграммой трейса.

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

Например, для этого источника трейсов настроены выделенный атрибут и выделенный атрибут трейсов:

Эти атрибуты отображаются на боковой панели после нажатия на лог или спан:

При нажатии на атрибут появляются варианты использования этого атрибута в качестве значения поиска. Если в конфигурации атрибута задано необязательное выражение Lucene, для поиска будет использоваться именно оно, а не SQL-выражение.

​

Коррелированные источники

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

• Logs: Можно коррелировать с трассировками и метриками.
• Traces: Можно коррелировать с логами, сеансами и метриками.
• Metrics: Можно коррелировать с логами.
• Sessions: Можно коррелировать с трассировками.

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

Ниже показан источник логов, настроенный с коррелированными источниками:

​

Настройки конфигурации приложения

HyperDX в ClickHouse Cloud

Эти настройки нельзя изменить, если HyperDX работает под управлением ClickHouse Cloud.

• HYPERDX_API_KEY

  • По умолчанию: Не задано (обязательно)
  • Описание: Ключ аутентификации для API HyperDX.
  • Рекомендации:
  • Обязательно для телеметрии и логирования
  • При локальной разработке может быть любым непустым значением
  • Для продакшена используйте безопасный уникальный ключ
  • Его можно получить на странице настроек команды после создания аккаунта

• HYPERDX_LOG_LEVEL

  • По умолчанию: info
  • Описание: Задает уровень подробности логирования.
  • Варианты: debug, info, warn, error
  • Рекомендации:
  • Используйте debug для подробной диагностики неполадок
  • Используйте info для штатной работы
  • Используйте warn или error в production, чтобы уменьшить объем логов

• HYPERDX_API_PORT

  • По умолчанию: 8000
  • Описание: Порт API-сервера HyperDX.
  • Рекомендации:
  • Убедитесь, что этот порт доступен на вашем хосте
  • Измените его при конфликте портов
  • Должен совпадать с портом в конфигурации вашего API-клиента

• HYPERDX_APP_PORT

  • По умолчанию: 8000
  • Описание: Порт для веб-приложения HyperDX.
  • Рекомендации:
  • Убедитесь, что этот порт свободен на вашем хосте
  • Измените его, если этот порт конфликтует с другими
  • Должен быть доступен из браузера

• HYPERDX_APP_URL

  • По умолчанию: http://localhost
  • Описание: Базовый URL интерфейса приложения.
  • Рекомендации:
  • В production укажите свой домен
  • Укажите протокол (http/https)
  • Не добавляйте завершающий слеш

• MONGO_URI

  • По умолчанию: mongodb://db:27017/hyperdx
  • Описание: Строка подключения к MongoDB.
  • Рекомендации:
  • Используйте значение по умолчанию для локальной разработки с Docker
  • Для продакшена используйте безопасную строку подключения
  • При необходимости добавьте аутентификацию
  • Пример: mongodb://user:pass@host:port/db

• MINER_API_URL

  • По умолчанию: http://miner:5123
  • Описание: URL сервиса анализа шаблонов логов.
  • Рекомендации:
  • Используйте значение по умолчанию для локальной разработки с Docker
  • В продуктивной среде укажите URL вашего сервиса miner
  • Должен быть доступен из API-сервиса

• FRONTEND_URL

  • По умолчанию: http://localhost:3000
  • Описание: URL интерфейса.
  • Рекомендации:
  • Используйте значение по умолчанию для локальной разработки
  • В продакшене укажите свой домен
  • Должен быть доступен из API-сервиса

• OTEL_SERVICE_NAME

  • По умолчанию: hdx-oss-api
  • Описание: Имя сервиса для инструментирования OpenTelemetry.
  • Рекомендации:
  • Используйте понятное, описательное имя для сервиса HyperDX. Применимо, если HyperDX инструментирует себя самостоятельно.
  • Помогает идентифицировать сервис HyperDX в телеметрических данных

• NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

  • По умолчанию: http://localhost:4318
  • Описание: конечная точка OpenTelemetry Collector.
  • Рекомендации:
  • Актуально при самоинструментировании HyperDX.
  • Используйте значение по умолчанию для локальной разработки
  • В production укажите URL вашего коллектора
  • Должно быть доступно из сервиса HyperDX

• USAGE_STATS_ENABLED

  • По умолчанию: true
  • Описание: Включает сбор статистики использования.
  • Рекомендации:
  • Установите false, чтобы отключить сбор статистики использования
  • Полезно для развертываний с повышенными требованиями к конфиденциальности
  • Значение по умолчанию — true, чтобы способствовать улучшению продукта

• IS_OSS

  • По умолчанию: true
  • Описание: Указывает, работает ли система в режиме OSS.
  • Рекомендации:
  • Оставьте true для развертываний с открытым исходным кодом
  • Установите false для корпоративных развертываний
  • Влияет на доступные возможности

• IS_LOCAL_MODE

  • По умолчанию: false
  • Описание: Указывает, работает ли приложение в локальном режиме.
  • Рекомендации:
  • Установите значение true для локальной разработки
  • Отключает некоторые возможности, используемые в продакшене
  • Полезно для тестирования и разработки

• EXPRESS_SESSION_SECRET

  • По умолчанию: hyperdx is cool 👋
  • Описание: Секрет для управления сеансами в Express.
  • Рекомендации:
  • Измените в продакшене
  • Используйте надёжную случайную строку
  • Храните в секрете и в безопасном месте

• ENABLE_SWAGGER

  • По умолчанию: false
  • Описание: Включает или отключает документацию Swagger API.
  • Рекомендации:
  • Установите true, чтобы включить документацию API
  • Полезно для разработки и тестирования
  • В рабочей среде отключайте

• BETA_CH_OTEL_JSON_SCHEMA_ENABLED

  • По умолчанию: false
  • Описание: Включает бета-поддержку типа JSON в HyperDX. См. также OTEL_AGENT_FEATURE_GATE_ARG, чтобы включить поддержку JSON в OTel collector.
  • Рекомендации:
    • Включает возможность в статусе бета. Схемы с типом JSON не рекомендуются для типичных задач обсервабилити. Сравнение и рекомендации по выбору см. в разделе Map vs JSON type.
    • Установите true, чтобы включить поддержку JSON в интерфейсе ClickStack.

​

Коллектор OpenTelemetry

Подробнее см. в “Коллектор ClickStack OpenTelemetry”.

• CLICKHOUSE_ENDPOINT

  • По умолчанию: None (обязательно) для автономного образа. Для дистрибутива All-in-one или Docker Compose это значение задается как адрес встроенного экземпляра ClickHouse.
  • Описание: HTTPS URL экземпляра ClickHouse, в который экспортируются данные телеметрии.
  • Рекомендации:
    • Должна быть указана полная HTTPS конечная точка, включая порт (например, https://clickhouse.example.com:8443)
    • Обязательно для отправки данных из коллектора в ClickHouse

• CLICKHOUSE_USER

  • По умолчанию: default
  • Описание: Имя пользователя для аутентификации в экземпляре ClickHouse.
  • Рекомендации:
    • Убедитесь, что у пользователя есть разрешения INSERT и CREATE TABLE
    • Рекомендуется создать отдельного пользователя для ингестии

• CLICKHOUSE_PASSWORD

  • По умолчанию: None (обязательно, если включена аутентификация)
  • Описание: Пароль для указанного пользователя ClickHouse.
  • Рекомендации:
    • Обязательно, если для учетной записи пользователя задан пароль
    • В production-развертываниях храните его безопасно с помощью secrets

• HYPERDX_LOG_LEVEL

  • По умолчанию: info
  • Описание: Уровень детализации Log для коллектора.
  • Рекомендации:
    • Принимает значения debug, info, warn, error
    • Используйте debug при устранении неполадок

• OPAMP_SERVER_URL

  • По умолчанию: None (обязательно) для автономного образа. Для дистрибутива All-in-one или Docker Compose это значение указывает на развернутый экземпляр HyperDX.
  • Описание: URL сервера OpAMP, используемого для управления коллектором (например, экземпляра HyperDX). По умолчанию используется порт 4320.
  • Рекомендации:
    • Должен указывать на ваш экземпляр HyperDX
    • Включает динамическую конфигурацию и безопасную ингестию
    • Если значение не указано, безопасная ингестия отключается, если только не задан OTLP_AUTH_TOKEN.

• OTLP_AUTH_TOKEN

  • По умолчанию: None. Используется только для автономного образа.
  • Описание: Позволяет указать токен аутентификации OTLP. Если он задан, для всего обмена требуется этот bearer-токен.
  • Рекомендации:
    • Рекомендуется при использовании автономного образа коллектора в production.

• HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

  • По умолчанию: default
  • Описание: База данных ClickHouse, в которую коллектор записывает данные телеметрии.
  • Рекомендации:
    • Задайте, если используете пользовательское имя базы данных
    • Убедитесь, что указанный пользователь имеет доступ к этой базе данных

• OTEL_AGENT_FEATURE_GATE_ARG

  • По умолчанию: <empty string>
  • Описание: Включает feature flags в коллекторе. Если задано значение --feature-gates=clickhouse.json, в коллекторе включается бета-поддержка JSON type, что позволяет создавать схемы с этим типом. См. также BETA_CH_OTEL_JSON_SCHEMA_ENABLED, чтобы включить поддержку JSON в HyperDX.
  • Рекомендации:
    • Включает бета-возможность. Схемы с типом JSON не рекомендуются для типичных рабочих нагрузок обсервабилити. Сравнение и рекомендации по выбору см. в Map vs JSON type.
    • Установите значение --feature-gates=clickhouse.json, чтобы создавать новые таблицы с использованием типа JSON.

​

ClickHouse

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

Чтобы эффективно настраивать ClickHouse, важно понимать ключевые концепции хранения, такие как части, партиции, сегменты и реплики, а также то, как происходят слияния в момент вставки. Мы рекомендуем ознакомиться с основами первичных индексов, разреженных вторичных индексов и индексов пропуска данных, а также с методами управления жизненным циклом данных, например с использованием TTL.

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

Кроме того, materialized views можно использовать для преобразования или фильтрации данных во время ингестии при условии, что данные записываются в исходную таблицу этого представления, а приложение читает из целевой таблицы. Materialized views также можно использовать для ускорения запросов встроенными средствами в ClickStack.

Подробнее см. в документации ClickHouse по проектированию схемы, стратегиям индексирования и рекомендациям по управлению данными — большинство из них напрямую применимы к развертываниям ClickStack.