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

The following configuration options are available for each component of 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 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

Docker Compose

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

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

Пример:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... other settings

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

HyperDX

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

HyperDX зависит от определения пользователем источника для каждого из типов/столпов данных наблюдаемости:

Logs
Traces
Metrics
Sessions

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

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

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

примечание

Схема по умолчанию для ClickHouse, предоставляемая с ClickStack, является схемой, созданной экспортером ClickHouse для OTel коллекторов. Эти названия колонок соответствуют официальной спецификации 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`	Выражение или колонка, используемая для извлечения идентификатора трассировки.	Да	Да	`TraceId`
`Span Id Expression`	Выражение или колонка, используемая для извлечения идентификатора спана.	Да	Да	`SpanId`
`Implicit Column Expression`	Столбец, используемый для полнотекстового поиска, если поле не указано (в стиле Lucene). Обычно это тело лога.	Да	Да	`Body`

Трассировки

Настройка	Описание	Обязательно	Выведено в схеме по умолчанию	Выведенное значение
`Name`	Имя источника.	Да	Нет	–
`Server Connection`	Имя соединения с сервером.	Да	Нет	`Default`
`Database`	Имя базы данных ClickHouse.	Да	Да	`default`
`Table`	Имя целевой таблицы. Установите на `otel_traces`, если используется схема по умолчанию.	Да	Да	-
`Timestamp Column`	Столбец даты и времени или выражение, которое является частью вашего первичного ключа.	Да	Да	`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`	Выражение или колонка для идентификаторов трассировок.	Да	Да	`TraceId`
`Span Id Expression`	Выражение или колонка для идентификаторов спанов.	Да	Да	`SpanId`
`Parent Span Id Expression`	Выражение или колонка для идентификаторов родительских спанов.	Да	Да	`ParentSpanId`
`Span Name Expression`	Выражение или колонка для имен спанов.	Да	Да	`SpanName`
`Span Kind Expression`	Выражение или колонка для вида спана (например, клиент, сервер).	Да	Да	`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`. Это позволяет отображать трассировки исключений с поддерживаемыми языковыми SDK.	Да	Да	`Events`
`Implicit Column Expression`	Столбец, используемый для полнотекстового поиска, если поле не указано (в стиле Lucene). Обычно это тело лога.	Да	Да	`SpanName`

Метрики

Настройка	Описание	Обязательно	Выведено в схеме по умолчанию	Выведенное значение
`Name`	Имя источника.	Да	Нет	–
`Server Connection`	Имя соединения с сервером.	Да	Нет	`Default`
`Database`	Имя базы данных ClickHouse.	Да	Да	`default`
`Gauge Table`	Таблица, хранящая метрики типа gauge.	Да	Нет	`otel_metrics_gauge`
`Histogram Table`	Таблица, хранящая метрики типа histogram.	Да	Нет	`otel_metrics_histogram`
`Sum Table`	Таблица, хранящая метрики типа sum (счетчик).	Да	Нет	`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`

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

Чтобы обеспечить полную кросс-источниковую корреляцию в 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 в продакшене для уменьшения объема логов
HYPERDX_API_PORT
- По умолчанию: 8000
- Описание: Порт для сервера API HyperDX.
- Руководство:
- Убедитесь, что этот порт доступен на вашем хосте
- Измените, если у вас конфликт портов
- Должен соответствовать порту в конфигурациях вашего API клиента
HYPERDX_APP_PORT
- По умолчанию: 8000
- Описание: Порт для фронтенд-приложения HyperDX.
- Руководство:
- Убедитесь, что этот порт доступен на вашем хосте
- Измените, если у вас конфликт портов
- Должен быть доступен из вашего браузера
HYPERDX_APP_URL
- По умолчанию: http://localhost
- Описание: Базовый URL для фронтенд-приложения.
- Руководство:
- Установите на свой домен в продакшене
- Укажите протокол (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 сервиса майнера в продакшене
- Должен быть доступен из сервиса 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.
- Руководство:
- Важно для самостоянно инструментирования HyperDX.
- Используйте по умолчанию для локальной разработки
- Установите на 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
- Описание: Переключает документацию API Swagger.
- Руководство:
- Установите в true, чтобы включить документацию API
- Полезно для разработки и тестирования
- Отключите в продакшене
BETA_CH_OTEL_JSON_SCHEMA_ENABLED
- По умолчанию: false
- Описание: Включает Бета поддержку для типа JSON в HyperDX. Смотрите также OTEL_AGENT_FEATURE_GATE_ARG для включения поддержки JSON в OTel коллекторе.
- Руководство:
- Установите в true, чтобы включить поддержку JSON в ClickStack.

Коллектор OpenTelemetry

Смотрите "ClickStack OpenTelemetry Collector" для получения дополнительной информации.

CLICKHOUSE_ENDPOINT
- По умолчанию: Нет (обязательно), если используется отдельный образ. Если 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
- По умолчанию: Нет (обязательно, если включена аутентификация)
- Описание: Пароль для указанного пользователя ClickHouse.
- Руководство:
  - Обязательно, если у учетной записи пользователя установлен пароль
  - Храните безопасно, используя секреты в продакшен-развертываниях
HYPERDX_LOG_LEVEL
- По умолчанию: info
- Описание: Уровень детализации логов для коллектора.
- Руководство:
  - Принимает значения такие как debug, info, warn, error
  - Используйте debug во время отладки
OPAMP_SERVER_URL
- По умолчанию: Нет (обязательно), если используется отдельный образ. Если All-in-one или Docker Compose распределение, это указывает на развернутую инстанцию HyperDX.
- Описание: URL сервера OpAMP, используемого для управления коллектором (например, инстанция HyperDX). Порт по умолчанию - 4320.
- Руководство:
  - Должен указывать на вашу инстанцию HyperDX
  - Включает динамическую конфигурацию и безопасную погрузку
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE
- По умолчанию: default
- Описание: База данных ClickHouse, в которую коллектор записывает телеметрию.
- Руководство:
  - Установите, если используете пользовательское имя базы данных
  - Убедитесь, что указанный пользователь имеет доступ к этой базе данных
OTEL_AGENT_FEATURE_GATE_ARG
- По умолчанию: <пустая строка>
- Описание: Включает флаги функций для включения в коллектор. Если установлено значение --feature-gates=clickhouse.json, включает Бета поддержку типа JSON в коллекторе, обеспечивая создание схем с этим типом. Смотрите также BETA_CH_OTEL_JSON_SCHEMA_ENABLED для включения поддержки JSON в HyperDX.
- Руководство:
- Установите в true, чтобы включить поддержку JSON в ClickStack.

ClickHouse

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

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

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

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

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

Изменение настроек​

Docker​

Docker Compose​

Helm​

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

HyperDX​

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

Логи​

Трассировки​

Метрики​

Сессии​

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

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

Коллектор OpenTelemetry​

ClickHouse​