Skip to main content
В этом руководстве показано, как добавить OpenTelemetry-инструментацию в простое приложение Node.js и отправлять его журналы, метрики и трассировки в Управляемый ClickStack. Бэкенд инструментирован без изменений в исходном коде приложения. HackerNews Analyzer — небольшое приложение на Node.js, которое выполняет запросы к набору данных HackerNews, размещённому в общедоступном демо-экземпляре ClickHouse. За каждой диаграммой, таблицей и полем поиска стоит реальный запрос к ClickHouse, поэтому каждое взаимодействие порождает трассировку, в которой основной спан — это HTTPS-вызов от бэкенда к ClickHouse.

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

  • Доступный OTel collector, к которому можно подключиться и который отправляет данные в ваш сервис Управляемый ClickStack. Вам понадобятся его конечная точка OTLP и токен для ингестии.
  • Node 18+ и npm.
1

​
Клонируйте и запустите приложение

Клонируйте репозиторий, установите зависимости и создайте файл .env:
Источник данных ClickHouse по умолчанию использует общедоступный демо-кластер в режиме только для чтения, поэтому приложение можно запустить без дополнительной настройки. Запустите его:
Откройте http://localhost:5001. Вы увидите выбор года, сводную статистику, диаграмму активности, таблицы с пользователями и доменами, а также строку поиска. Попробуйте интерфейс: переключайте годы, открывайте истории.На этом этапе приложение запущено, но пока без инструментирования. ClickStack не показывает данные: он ждёт поступления телеметрии. Это состояние “до”.
2

​
Получите сведения о подключении

Приложению нужны два значения для подключения к коллектору:
  • OTEL_EXPORTER_OTLP_ENDPOINT: конечная точка OTLP, которую предоставляет ваш коллектор (обычно это порт 4318 для OTLP по HTTP).
  • OTEL_EXPORTER_OTLP_HEADERS: заголовок авторизации с вашим токеном ингестии в формате authorization=<token>.
Откройте .env и задайте их:
SDK использует OTEL_EXPORTER_OTLP_HEADERS для задания заголовка авторизации для всех трёх сигналов: трассировок, метрик и журналов. Если ваш коллектор запущен локально и не требует аутентификации, можно оставить значение пустым (OTEL_EXPORTER_OTLP_HEADERS=authorization=), но сама переменная должна присутствовать; если она не задана или полностью пуста, SDK вообще пропускает инициализацию.
3

​
Инструментируйте приложение

Инструментирование включает три части: установку SDK, изменение команды запуска и включение браузерного SDK. Ничто из этого не меняет бизнес-логику приложения.

​
Установите SDK

Установите OpenTelemetry SDK и для backend, и для браузера:

​
Используйте CLI opentelemetry-instrument

Приложение запускается с помощью run.sh; в конце файла есть две строки exec: одна активная, другая закомментирована. Поменяйте, какая из них активна, чтобы Node запускался через opentelemetry-instrument:
Это всё, что нужно изменить на серверной стороне. Auto-instrumentation загружается через opentelemetry-instrument при запуске процесса.

​
Включите браузерный SDK

Чтобы собирать распределённые трассировки (от браузера до сервера) и воспроизведения сеансов, включите браузерный SDK в src/web/telemetry.ts. Раскомментируйте импорт и блок HyperDX.init({...}):
Дополнительные правки .env не нужны. __OTLP_ENDPOINT__ и __OTLP_AUTH_TOKEN__ — это константы, подставляемые на этапе сборки через vite.config.ts: конечная точка берётся из OTEL_EXPORTER_OTLP_ENDPOINT, а токен извлекается из OTEL_EXPORTER_OTLP_HEADERS — используются те же значения, что и на стороне сервера.
Токен для ингестии встраивается в публичный браузерный бандл, поэтому его сможет увидеть любой, кто откроет вкладку Network.
4

​
Сгенерируйте трафик и просмотрите телеметрию

Перезапустите приложение, чтобы вступили в силу новая команда запуска и свежесобранный браузерный бандл:
Перезагрузите вкладку браузера, чтобы Vite отдал обновлённый бандл, затем несколько раз обновите приложение, переключите годы и откройте несколько историй, чтобы сгенерировать трафик.Откройте интерфейс ClickStack:
  1. Перейдите в Search и отфильтруйте данные за последние 5 минут. Появятся журналы для hn-analyzer-api.
  1. Откройте запрос и поднимитесь вверх по трейсу. Вы увидите спан обработчика Express, дочерний HTTP-спан, указывающий на кластер ClickHouse с реальной длительностью сетевого взаимодействия, а также коррелированные записи console.log в том же трейсе.
  1. Откройте Воспроизведение сеанса, чтобы просмотреть видео сеанса браузера с возможностью перемотки, синхронизированное с временной шкалой трейса.
Журналы, метрики, трейсы и воспроизведения сеансов попадают в один и тот же интерфейс, используют один и тот же язык запросов и автоматически коррелируются.

​
Подробнее

Last modified on July 2, 2026