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:
git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env
Источник данных ClickHouse по умолчанию использует общедоступный демо-кластер в режиме только для чтения, поэтому приложение можно запустить без дополнительной настройки. Запустите его:
./run.sh
Откройте http://localhost:5001. Вы увидите выбор года, сводную статистику, диаграмму активности, таблицы с пользователями и доменами, а также строку поиска. Попробуйте интерфейс: переключайте годы, открывайте истории.На этом этапе приложение запущено, но пока без инструментирования. ClickStack не показывает данные: он ждёт поступления телеметрии. Это состояние “до”.
2

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

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

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

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

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

Установите OpenTelemetry SDK и для backend, и для браузера:
npm install @hyperdx/node-opentelemetry @hyperdx/browser

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

Приложение запускается с помощью run.sh; в конце файла есть две строки exec: одна активная, другая закомментирована. Поменяйте, какая из них активна, чтобы Node запускался через opentelemetry-instrument:
 # BEFORE: plain node, no instrumentation, collector stays silent:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # AFTER: same source, wrapped by opentelemetry-instrument CLI.
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js
Это всё, что нужно изменить на серверной стороне. Auto-instrumentation загружается через opentelemetry-instrument при запуске процесса.

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

Чтобы собирать распределённые трассировки (от браузера до сервера) и воспроизведения сеансов, включите браузерный SDK в src/web/telemetry.ts. Раскомментируйте импорт и блок HyperDX.init({...}):
import HyperDX from '@hyperdx/browser';

export function initTelemetry(): void {
  HyperDX.init({
    url: __OTLP_ENDPOINT__,
    apiKey: __OTLP_AUTH_TOKEN__,
    service: 'hn-analyzer-web',
    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
    consoleCapture: true,
    advancedNetworkCapture: true,
  });
}
Дополнительные правки .env не нужны. __OTLP_ENDPOINT__ и __OTLP_AUTH_TOKEN__ — это константы, подставляемые на этапе сборки через vite.config.ts: конечная точка берётся из OTEL_EXPORTER_OTLP_ENDPOINT, а токен извлекается из OTEL_EXPORTER_OTLP_HEADERS — используются те же значения, что и на стороне сервера.
Токен для ингестии встраивается в публичный браузерный бандл, поэтому его сможет увидеть любой, кто откроет вкладку Network.
4

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

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

​
Подробнее

Last modified on June 25, 2026