Расширение для Chrome

Добавьте на любой сайт поддержку воспроизведения сеанса и RUM в ClickStack с помощью HyperDX Chrome extension

Кратко

В этом руководстве показано, как подключить Browser SDK ClickStack к любому сайту с помощью HyperDX Chrome extension. Вносить изменения в исходный код целевого приложения не требуется — достаточно один раз настроить расширение, перейти на сайт и просматривать воспроизведения сеансов в ClickStack.

Требуемое время: 10–15 минут

​

Обзор

HyperDX Chrome extension внедряет SDK @hyperdx/browser в страницы, которые вы посещаете. Это полезно, если нужно отлаживать воспроизведение сеанса, RUM или распространение трассировки на сайте без изменений в его кодовой базе — например, в стороннем приложении, в production-сборке или на локальном dev-сервере со строгой Content Security Policy (CSP).

SDK встроен в расширение (~480 КБ), поэтому страницам не нужно загружать скрипты с CDN во время выполнения. Расширение сначала пытается внедрить внешний скрипт через chrome-extension://, а если CSP блокирует скрипты из расширения, переключается на встроенную инъекцию.

В отличие от Session Replay Demo, где вы инструментируете подконтрольное вам демо-приложение, этот подход работает с любым URL, который вы открываете в Chrome. Вы генерируете данные сеанса, взаимодействуя с сайтом как обычный пользователь.

Подробнее о воспроизведении сеанса и о том, как оно вписывается в ClickStack, см. на странице возможности Воспроизведение сеанса.

​

Предварительные требования

• Google Chrome или браузер на базе Chromium (Edge, Brave и т. д.)
• Установленный Docker, если вы запускаете ClickStack локально
• Свободные порты 4317, 4318 и 8080 (для локального ClickStack)

​

Запуск демо

1. ​

   Клонируйте репозиторий расширения

   git clone https://github.com/kyreddie/hyperdx-chrome-extension
   cd hyperdx-chrome-extension
   
2. ​

   Установите расширение

   1. Откройте Chrome и перейдите на chrome://extensions.
   2. Включите Developer mode (вверху справа).
   3. Нажмите Load unpacked.
   4. Выберите каталог hyperdx-chrome-extension, который вы клонировали.

   Расширение появится на панели инструментов как HyperDX Browser Extension.

3. ​

   Запустите ClickStack

   Если у вас уже есть конечная точка для ингестии в ClickStack или HyperDX, перейдите к разделу Настройте расширение.

   Для локального стека ClickStack запустите OpenTelemetry Collector. Замените {{CLICKHOUSE_ENDPOINT}} и {{CLICKHOUSE_PASSWORD}} своими сведениями о подключении к ClickHouse:

   export CLICKHOUSE_ENDPOINT={{CLICKHOUSE_ENDPOINT}}
   export CLICKHOUSE_PASSWORD={{CLICKHOUSE_PASSWORD}}
   
   docker run \
     -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
     -e CLICKHOUSE_USER=default \
     -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
     -p 8080:8080 \
     -p 4317:4317 \
     -p 4318:4318 \
     clickhouse/clickstack-otel-collector:latest
   

   Откройте HyperDX по адресу http://localhost:8080, чтобы убедиться, что интерфейс запущен.

   Инструкции по полному локальному развертыванию с ClickHouse и интерфейсом HyperDX см. в разделе Getting started with ClickStack.

4. ​

   Получите свой ключ API

   Для локального ClickStack ключ API может не понадобиться — оставьте это поле в расширении пустым, если отправляете telemetry в самоуправляемый коллектор на http://localhost:4318.

   Для ингестии в ClickStack Cloud или HyperDX Cloud откройте HyperDX, перейдите в Team Settings → API Keys и скопируйте свой Ingestion API Key.

5. ​

   Настройте расширение

   Нажмите значок HyperDX Browser Extension на панели инструментов Chrome и заполните настройки:

   Поле	Пример для локального ClickStack	Примечания
   Enable HyperDX Monitoring	On	Основной переключатель инъекции
   Service Name	my-frontend-app	Обязательно — идентифицирует сервис в ClickStack
   API Key	(пусто)	Обязательно для ингестии в Cloud; необязательно для некоторых самоуправляемых конфигураций
   Collector URL	http://localhost:4318	Конечная точка OTLP HTTP; для Cloud по умолчанию используется https://in-otel.hyperdx.io
   Environment	development	Необязательно — задаёт атрибут ресурса deployment.environment
   Trace Propagation Targets	/api\.myapp\.domain/i, /localhost/i	Необязательно — шаблоны регулярных выражений JavaScript, разделённые запятыми, для передачи заголовков трассировки
   Only inject on matching URLs	Off	Включите, чтобы ограничить список инструментируемых сайтов
   Capture console logs	Off	Включите, чтобы пересылать вывод консоли браузера
   Advanced network capture	Off	Включите для подробного захвата сетевых запросов

   Нажмите Save Configuration, затем перезагрузите все вкладки, которые хотите инструментировать.

   На снимке экрана выше показана типичная локальная конфигурация: мониторинг включён, имя сервиса задано, коллектор направлен на http://localhost:4318, а передача трассировки ограничена URL API и localhost.

6. ​

   Откройте сайт и создайте сеанс

   Откройте в Chrome любой веб-сайт или локальное приложение — например, http://localhost:3000 для frontend-сервера разработки.

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

7. ​

   Просмотрите воспроизведение сеанса

   Вернитесь в HyperDX по адресу http://localhost:8080 и выберите Client Sessions на левой боковой панели.

   Вы должны увидеть свой сеанс в списке с его длительностью и количеством событий. Нажмите кнопку ▶️, чтобы воспроизвести его.

   Переключайтесь между режимами Highlighted и All Events, чтобы менять уровень детализации на временной шкале.

​

Фильтрация URL

По умолчанию расширение внедряет SDK на каждой посещаемой странице, пока включен мониторинг. Чтобы SDK внедрялся только на определенных сайтах, включите Only inject on matching URLs и добавьте по одному шаблону в строке (или перечислите их через запятую):

Шаблон	Совпадает с
http://homedepot.com/*	Только HTTP на homedepot.com
*://homedepot.com/*	HTTP и HTTPS на homedepot.com
*://*.homedepot.com/*	Поддомены, например www.homedepot.com
https://localhost:3000/*	Локальный сервер разработки на порту 3000

После сохранения шаблонов URL перезагрузите вкладку.

​

Проверьте внедрение

Откройте DevTools на отслеживаемой странице (вкладка Console), перезагрузите страницу и проверьте, есть ли:

[HyperDX Extension] Configuration valid, injecting HyperDX
[HyperDX Extension] Injected via extension scripts
[HyperDX Extension] HyperDX initialized

Если CSP блокирует скрипты из источника расширения, расширение записывает сообщение о переключении на резервный вариант и повторяет попытку с помощью встроенной инъекции.

​

Устранение неполадок

Сеансы не отображаются в HyperDX

1. Проверьте консоль браузера на наличие сообщений [HyperDX Extension] или ошибок
2. Убедитесь, что параметр Enable HyperDX Monitoring включен и задано значение Service Name
3. Убедитесь, что ClickStack запущен, а URL коллектора указан верно (например, http://localhost:4318)
4. Измените временной диапазон в представлении Client Sessions (попробуйте Last 15 minutes)
5. Выполните принудительное обновление браузера: Cmd+Shift+R (Mac) или Ctrl+Shift+R (Windows/Linux)

Ошибки chrome-extension://invalid/

Перезагрузите расширение на странице chrome://extensions, затем принудительно обновите вкладку. Это происходит, когда расширение обновили или перезагрузили, пока вкладки всё ещё были открыты.

На сайте нет инъекции

1. Проверьте, что мониторинг включен и имя сервиса настроено
2. Если включен параметр Only inject on matching URLs, убедитесь, что URL текущей страницы соответствует одному из ваших шаблонов
3. Некоторые сайты через CSP блокируют инъекцию как со стороны расширения, так и встроенных скриптов — на таких страницах инъекция может быть невозможна

HyperDX: отсутствует apiKey в консоли

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

​

Конфиденциальность

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

​

Узнайте больше

• Воспроизведение сеанса — обзор возможности, варианты SDK и настройки конфиденциальности
• Справочник Browser SDK — полный список параметров SDK и расширенная конфигурация
• Session Replay Demo — инструментируйте демо-приложение из исходного кода
• Начало работы с ClickStack — разверните ClickStack и настройте приём первых данных
• HyperDX Chrome extension на GitHub — исходный код и трекер задач и ошибок