ClickHouse Cloud

Private preview in ClickHouse Cloud

Приватная предварительная версия

Эта функция находится в режиме приватной предварительной версии в ClickHouse Cloud. Если вашей организации нужен приоритетный доступ, присоединяйтесь к списку ожидания.

Если вы впервые работаете с ClickHouse Cloud, нажмите здесь, чтобы узнать больше, или зарегистрируйтесь для бесплатной пробной версии, чтобы начать работу.

Этот вариант предназначен для сценариев, когда вы используете ClickHouse Cloud. В этом шаблоне развертывания и ClickHouse, и HyperDX размещаются в ClickHouse Cloud, что минимизирует количество компонентов, которые пользователю нужно разворачивать самостоятельно.

Помимо сокращения объёма управления инфраструктурой, этот шаблон развертывания обеспечивает интеграцию аутентификации с SSO/SAML ClickHouse Cloud. В отличие от самостоятельных развертываний, здесь также нет необходимости поднимать экземпляр MongoDB для хранения состояния приложения — такого как дашборды, сохранённые поиски, пользовательские настройки и оповещения.

В этом режиме ингестия данных полностью остаётся на стороне пользователя. Вы можете выполнять приём данных в ClickHouse Cloud, используя собственный развернутый коллектор OpenTelemetry, прямую ингестию из клиентских библиотек, нативные табличные движки ClickHouse (такие как Kafka или S3), ETL-пайплайны или ClickPipes — управляемый сервис ингестии ClickHouse Cloud. Такой подход обеспечивает самый простой и наиболее производительный способ использования ClickStack.

Подходит для

Этот вариант развертывания оптимален в следующих сценариях:

У вас уже есть данные обсервабилити в ClickHouse Cloud, и вы хотите визуализировать их с помощью HyperDX.
Вы эксплуатируете крупное развертывание обсервабилити и нуждаетесь в выделенной производительности и масштабируемости ClickStack с ClickHouse Cloud.
Вы уже используете ClickHouse Cloud для аналитики и хотите инструментировать свое приложение с помощью библиотек инструментирования ClickStack, отправляя данные в тот же кластер. В этом случае мы рекомендуем использовать warehouses для изоляции вычислительных ресурсов для обсервабилити-нагрузок.

Шаги развертывания

В данном руководстве предполагается, что вы уже создали сервис ClickHouse Cloud. Если вы ещё не создали сервис, выполните шаг "Create a ClickHouse service" из нашего руководства по быстрому старту.

Копирование учетных данных службы (необязательно)

Если у вас уже есть события обсервабилити, которые необходимо визуализировать в вашем сервисе, этот шаг можно пропустить.

Перейдите к основному списку сервисов и выберите сервис, события обсервабилити которого вы хотите визуализировать в HyperDX.

Нажмите кнопку Connect в меню навигации. Откроется модальное окно с учетными данными для вашего сервиса и набором инструкций по подключению через различные интерфейсы и языки программирования. Выберите HTTPS из выпадающего списка и сохраните конечную точку подключения и учетные данные.

Развертывание OpenTelemetry Collector (необязательно)

Этот шаг обеспечивает создание таблиц со схемой Open Telemetry (OTel), которая затем может быть использована для создания источника данных в HyperDX. Также предоставляется OLTP-эндпоинт, который можно использовать для загрузки примеров наборов данных и отправки OTel-событий в ClickStack.

Использование стандартного коллектора Open Telemetry

Следующие инструкции используют стандартный дистрибутив OTel collector, а не дистрибутив ClickStack. Последний требует OpAMP-сервер для конфигурации. В настоящее время это не поддерживается в закрытой предварительной версии. Приведенная ниже конфигурация воспроизводит версию, используемую дистрибутивом ClickStack для коллектора, предоставляя OTLP-эндпоинт, на который могут отправляться события.

Скачайте конфигурацию для OTel collector:

curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/deployment/_snippets/otel-cloud-config.yaml

otel-cloud-config.yaml

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: '0.0.0.0:4317'
      http:
        cors:
          allowed_origins: ['*']
          allowed_headers: ['*']
        include_metadata: true
        endpoint: '0.0.0.0:4318'
processors:
  transform:
    log_statements:
      - context: log
        error_mode: ignore
        statements:
          # JSON parsing: Extends log attributes with the fields from structured log body content, either as an OTEL map or
          # as a string containing JSON content.
          - set(log.cache, ExtractPatterns(log.body, "(?P<0>(\\{.*\\}))")) where
            IsString(log.body)
          - merge_maps(log.attributes, ParseJSON(log.cache["0"]), "upsert")
            where IsMap(log.cache)
          - flatten(log.attributes) where IsMap(log.cache)
          - merge_maps(log.attributes, log.body, "upsert") where IsMap(log.body)
      - context: log
        error_mode: ignore
        conditions:
          - severity_number == 0 and severity_text == ""
        statements:
          # Infer: extract the first log level keyword from the first 256 characters of the body
          - set(log.cache["substr"], log.body.string) where Len(log.body.string)
            < 256
          - set(log.cache["substr"], Substring(log.body.string, 0, 256)) where
            Len(log.body.string) >= 256
          - set(log.cache, ExtractPatterns(log.cache["substr"],
            "(?i)(?P<0>(alert|crit|emerg|fatal|error|err|warn|notice|debug|dbug|trace))"))
          # Infer: detect FATAL
          - set(log.severity_number, SEVERITY_NUMBER_FATAL) where
            IsMatch(log.cache["0"], "(?i)(alert|crit|emerg|fatal)")
          - set(log.severity_text, "fatal") where log.severity_number ==
            SEVERITY_NUMBER_FATAL
          # Infer: detect ERROR
          - set(log.severity_number, SEVERITY_NUMBER_ERROR) where
            IsMatch(log.cache["0"], "(?i)(error|err)")
          - set(log.severity_text, "error") where log.severity_number ==
            SEVERITY_NUMBER_ERROR
          # Infer: detect WARN
          - set(log.severity_number, SEVERITY_NUMBER_WARN) where
            IsMatch(log.cache["0"], "(?i)(warn|notice)")
          - set(log.severity_text, "warn") where log.severity_number ==
            SEVERITY_NUMBER_WARN
          # Infer: detect DEBUG
          - set(log.severity_number, SEVERITY_NUMBER_DEBUG) where
            IsMatch(log.cache["0"], "(?i)(debug|dbug)")
          - set(log.severity_text, "debug") where log.severity_number ==
            SEVERITY_NUMBER_DEBUG
          # Infer: detect TRACE
          - set(log.severity_number, SEVERITY_NUMBER_TRACE) where
            IsMatch(log.cache["0"], "(?i)(trace)")
          - set(log.severity_text, "trace") where log.severity_number ==
            SEVERITY_NUMBER_TRACE
          # Infer: else
          - set(log.severity_text, "info") where log.severity_number == 0
          - set(log.severity_number, SEVERITY_NUMBER_INFO) where log.severity_number == 0
      - context: log
        error_mode: ignore
        statements:
          # Normalize the severity_text case
          - set(log.severity_text, ConvertCase(log.severity_text, "lower"))
  resourcedetection:
    detectors:
      - env
      - system
      - docker
    timeout: 5s
    override: false
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200
  clickhouse/rrweb:
    database: ${env:CLICKHOUSE_DATABASE}
    endpoint: ${env:CLICKHOUSE_ENDPOINT}
    password: ${env:CLICKHOUSE_PASSWORD}
    username: ${env:CLICKHOUSE_USER}
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: ${env:CLICKHOUSE_DATABASE}
    endpoint: ${env:CLICKHOUSE_ENDPOINT}
    password: ${env:CLICKHOUSE_PASSWORD}
    username: ${env:CLICKHOUSE_USER}
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
extensions:
  health_check:
    endpoint: :13133
service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, transform, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

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

# modify to your cloud endpoint
export CLICKHOUSE_ENDPOINT=
export CLICKHOUSE_PASSWORD=
# optionally modify 
export CLICKHOUSE_DATABASE=default

# osx
docker run --rm -it \
  -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -e CLICKHOUSE_DATABASE=${CLICKHOUSE_DATABASE} \
  --user 0:0 \
  -v "$(pwd)/otel-cloud-collector.yaml":/etc/otel/config.yaml \
  -v /var/log:/var/log:ro \
  -v /private/var/log:/private/var/log:ro \
  otel/opentelemetry-collector-contrib:latest \
  --config /etc/otel/config.yaml

# linux command

# docker run --network=host --rm -it \
#   -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
#   -e CLICKHOUSE_USER=default \
#   -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
#   -e CLICKHOUSE_DATABASE=${CLICKHOUSE_DATABASE} \
#   --user 0:0 \
#   -v "$(pwd)/otel-cloud-config.yaml":/etc/otel/config.yaml \
#   -v /var/log:/var/log:ro \
#   -v /private/var/log:/private/var/log:ro \
#   otel/opentelemetry-collector-contrib:latest \
#   --config /etc/otel/config.yaml

Примечание

В продакшене рекомендуется создать выделенного пользователя для ингестии, ограничив права доступа к необходимым базе данных и таблицам. Подробнее см. "База данных и пользователь для ингестии".

Подключение к ClickStack

Выберите свой сервис, затем выберите ClickStack в левом меню.

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

Для пользователей, которые хотят только ознакомиться с интерфейсом HyperDX, мы рекомендуем наши примеры наборов данных, которые используют данные OTel.

Начальная страница HyperDX в ClickHouse Cloud

Разрешения пользователя

Пользователи, получающие доступ к HyperDX, автоматически проходят аутентификацию с помощью учетных данных консоли ClickHouse Cloud. Управление доступом осуществляется через разрешения SQL-консоли, настраиваемые в параметрах сервиса.

Настройка доступа пользователей

Перейдите к своему сервису в консоли ClickHouse Cloud
Перейдите в раздел Settings → SQL Console Access
Установите соответствующий уровень прав доступа для каждого пользователя:
- Service Admin → Full Access - требуется для включения оповещений
- Service Read Only → Read Only - позволяет просматривать данные обсервабилити и создавать дашборды
- No access - не имеет доступа к HyperDX

Для оповещений требуется доступ администратора

Чтобы включить оповещения, как минимум один пользователь с правами Service Admin (соответствует Full Access в выпадающем списке SQL Console Access) должен войти в HyperDX хотя бы один раз. Это создаст выделенного пользователя в базе данных для выполнения запросов оповещений.

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

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

Использование схем OpenTelemetry

Если вы используете указанный выше OTel collector для создания базы данных и таблиц в ClickHouse, сохраните все значения по умолчанию в модели создания источника, указав в поле Table значение otel_logs — это создаст источник логов. Все остальные параметры должны определиться автоматически, после чего вы сможете нажать Save New Source.

Источник данных ClickHouse Cloud в HyperDX

Для создания источников трассировок и метрик OTel выберите Создать Новый Источник в верхнем меню.

Здесь выберите требуемый тип источника, затем соответствующую таблицу — например, для трассировок выберите таблицу otel_traces. Все настройки должны быть определены автоматически.

Корреляция источников

Обратите внимание, что различные источники данных в ClickStack — такие как логи и трассировки — можно коррелировать друг с другом. Для этого требуется дополнительная настройка каждого источника. Например, в источнике логов можно указать соответствующий источник трассировок и наоборот. Подробнее см. "Коррелированные источники".

Использование пользовательских схем

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

При использовании собственной схемы рекомендуется создать источник логов, указав все необходимые поля — подробнее см. в разделе "Настройки источника логов".

Поддержка типа JSON

Beta feature. Learn more.

Beta Feature - not production ready

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

Поддержка типа JSON в ClickStack доступна в статусе бета-версии, начиная с версии 2.0.4.

О преимуществах этого типа см. раздел Преимущества типа JSON.

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

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

Кроме того, вам следует связаться с support@clickhouse.com, чтобы убедиться, что в вашем сервисе ClickHouse Cloud включена поддержка JSON.

Подходит для​

Шаги развертывания​

Копирование учетных данных службы (необязательно)​

Развертывание OpenTelemetry Collector (необязательно)​

Подключение к ClickStack​

Разрешения пользователя​

Настройка доступа пользователей​

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

Использование схем OpenTelemetry​

Использование пользовательских схем​

Поддержка типа JSON​