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

Для каждого компонента 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}
      # ... прочие настройки

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 exporter для OTel collector. Эти имена столбцов соответствуют официальной спецификации OTel, задокументированной здесь.

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

Логи

Setting	Description	Required	Inferred in Default Schema	Inferred Value
`Name`	Имя источника.	Yes	No	–
`Server Connection`	Имя подключения к серверу.	Yes	No	`Default`
`Database`	Имя базы данных ClickHouse.	Yes	Yes	`default`
`Table`	Имя целевой таблицы. Установите `otel_logs`, если используется схема по умолчанию.	Yes	No
`Timestamp Column`	Столбец или выражение типа DateTime, входящее в первичный ключ.	Yes	Yes	`TimestampTime`
`Default Select`	Столбцы, отображаемые в результатах поиска по умолчанию.	Yes	Yes	`Timestamp`, `ServiceName`, `SeverityText`, `Body`
`Service Name Expression`	Выражение или столбец для имени сервиса.	Yes	Yes	`ServiceName`
`Log Level Expression`	Выражение или столбец для уровня логирования.	Yes	Yes	`SeverityText`
`Body Expression`	Выражение или столбец для текста сообщения лога.	Yes	Yes	`Body`
`Log Attributes Expression`	Выражение или столбец для пользовательских атрибутов логов.	Yes	Yes	`LogAttributes`
`Resource Attributes Expression`	Выражение или столбец для атрибутов на уровне ресурса.	Yes	Yes	`ResourceAttributes`
`Displayed Timestamp Column`	Столбец с временной меткой, используемый для отображения в интерфейсе.	Yes	Yes	`ResourceAttributes`
`Correlated Metric Source`	Связанный источник метрик (например, метрики HyperDX).	No	No	–
`Correlated Trace Source`	Связанный источник трейсов (например, трейсы HyperDX).	No	No	–
`Trace Id Expression`	Выражение или столбец, используемый для извлечения идентификатора трейса.	Yes	Yes	`TraceId`
`Span Id Expression`	Выражение или столбец, используемый для извлечения идентификатора span.	Yes	Yes	`SpanId`
`Implicit Column Expression`	Столбец, используемый для полнотекстового поиска, если поле не указано (в стиле Lucene). Обычно используется тело лога.	Yes	Yes	`Body`

Трейсы

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

Метрики

Параметр	Описание	Обязательный	Выводится в схеме по умолчанию	Выведенное значение
`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).	Нет	Нет	–

Сессии

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

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

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

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

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

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

Источник 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 для фронтенд-приложения.
- Рекомендации:
- Укажите ваш домен в 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 в рабочей (production) среде
- Должен быть доступен из 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
- Default: true
- Description: Указывает, включён ли режим OSS.
- Guidance:
- Оставьте значение true для open-source-развертываний
- Установите значение false для enterprise-развертываний
- Влияет на доступность функций
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 (Beta) в HyperDX. См. также OTEL_AGENT_FEATURE_GATE_ARG для включения поддержки JSON в OTel collector.
- Рекомендации:
- Установите значение true, чтобы включить поддержку JSON в ClickStack.

Коллектор OpenTelemetry

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

CLICKHOUSE_ENDPOINT
- Default: None (required), если используется автономный образ. В случае дистрибутива All-in-one или Docker Compose этот параметр указывает на встроенный экземпляр ClickHouse.
- Description: URL по протоколу HTTPS экземпляра ClickHouse, в который экспортируются телеметрические данные.
- Guidance:
  - Должен быть полным HTTPS-адресом, включая порт (например, https://clickhouse.example.com:8443)
  - Обязателен, чтобы коллектор мог отправлять данные в ClickHouse
CLICKHOUSE_USER
- Default: default
- Description: Имя пользователя, используемое для аутентификации в экземпляре ClickHouse.
- Guidance:
  - Убедитесь, что у пользователя есть права INSERT и CREATE TABLE
  - Рекомендуется создать отдельного пользователя для ингестии
CLICKHOUSE_PASSWORD
- Default: None (required if authentication is enabled)
- Description: Пароль для указанного пользователя ClickHouse.
- Guidance:
  - Обязателен, если для учётной записи пользователя задан пароль
  - Храните его безопасно с помощью secrets в продуктивных развертываниях
HYPERDX_LOG_LEVEL
- Default: info
- Description: Уровень подробности логов для коллектора.
- Guidance:
  - Принимает значения, такие как debug, info, warn, error
  - Используйте debug при устранении неполадок
OPAMP_SERVER_URL
- Default: None (required), если используется автономный образ. В случае дистрибутива All-in-one или Docker Compose этот параметр указывает на развернутый экземпляр HyperDX.
- Description: URL сервера OpAMP, используемого для управления коллектором (например, экземпляр HyperDX). По умолчанию используется порт 4320.
- Guidance:
  - Должен указывать на ваш экземпляр HyperDX
  - Обеспечивает динамическую конфигурацию и безопасную ингестию
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE
- Default: default
- Description: База данных ClickHouse, в которую коллектор записывает телеметрические данные.
- Guidance:
  - Задайте, если используете пользовательское имя базы данных
  - Убедитесь, что указанный пользователь имеет доступ к этой базе данных
OTEL_AGENT_FEATURE_GATE_ARG
- Default: <empty string>
- Description: Включает feature flags, которые должны быть активированы в коллекторе. Если установить значение --feature-gates=clickhouse.json, включается бета-поддержка типа JSON в коллекторе, и схемы создаются с этим типом. См. также BETA_CH_OTEL_JSON_SCHEMA_ENABLED для включения поддержки JSON в HyperDX.
- Guidance:
- Установите значение true, чтобы включить поддержку JSON в ClickStack.

ClickHouse

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

Чтобы эффективно настраивать ClickHouse, пользователям следует понимать ключевые концепции хранения, такие как parts, partitions, shards and replicas и то, как merges выполняются во время вставки данных. Рекомендуется ознакомиться с основами primary indices, sparse secondary indices и индексов пропуска данных (data skipping indices), а также с техниками управления жизненным циклом данных, например с использованием жизненного цикла на основе TTL.

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

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

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

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

Docker​

Docker Compose​

Helm​

Настройка параметров (необязательно)​

HyperDX​

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

Логи​

Трейсы​

Метрики​

Сессии​

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

Параметры конфигурации приложения​

Коллектор OpenTelemetry​

ClickHouse​