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

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

Если вы используете 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, для изменения настроек можно использовать файл .env.

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

Пример:

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

Вы можете изменить значения с помощью флагов --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 предполагает, что пользователь задаёт источник для каждого из типов/основных сигналов данных обсервабилити:

• Logs
• Traces
• Metrics
• Sessions

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

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

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

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

Materialized views можно зарегистрировать для источников данных Log и Trace, чтобы подходящие агрегационные запросы выполнялись по предварительно агрегированному представлению, а не по исходной таблице. Инструкции по созданию и регистрации представлений см. в разделе "Materialized views".

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

Большинство этих параметров определяется по схеме представления при выборе целевой таблицы.

Materialized view метаданных ускоряет обнаружение полей для фильтров и автодополнения. Его можно настроить для источников данных Log и Trace.

Highlighted Attributes и Highlighted Trace Attributes можно настроить для источников данных Log и Trace.

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

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

Каждый атрибут настраивается с помощью следующих параметров:

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

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

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

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

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

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

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

• 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.

Подробнее см. в "Коллектор 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.

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

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

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

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

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