Демо HackerNews Analyzer

КраткоКлонируйте HackerNews Analyzer, укажите в .env конечную точку OTLP и токен, затем вставьте промпт агента. Backend не требует импортов OpenTelemetry: агент подключает @hyperdx/node-opentelemetry при запуске процесса.Требуемое время: около 10 минут

HackerNews Analyzer — приложение Node.js, которое выполняет запросы к датасету HackerNews, размещённому в публичной демоверсии ClickHouse. Каждая диаграмма, таблица и поле поиска выполняют реальный запрос к ClickHouse, поэтому при каждом взаимодействии создаётся трассировка, основной спан которой — HTTPS-вызов из backend в ClickHouse. Это отличается от демонстрации воспроизведения сеанса, где браузерное приложение инструментируется для работы с локальным ClickStack в Docker. Здесь одно приложение предоставляет автоматическую инструментацию backend, спаны запросов к ClickHouse и воспроизведение сеанса.

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

Node 18+ и npm
Конечная точка ClickStack OTLP/HTTP и токен ингестии:
- ClickHouse Cloud: откройте сервис, затем перейдите в ClickStack → Configure your OpenTelemetry exporter → Env vars. Протокол: http/protobuf. Заголовок: authorization=<ingestion token> без префикса Bearer.
- Локальный collector: используйте http://localhost:4318. Если collector не защищён, оставьте authorization= пустым.

Клонируйте репозиторий

Клонируйте HackerNews Analyzer, установите зависимости и скопируйте шаблон файла окружения:

git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env

На следующих шагах вы заполните .env, а затем из этого каталога инструментируете приложение.

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

Запустите приложение

В клонированном каталоге hn-news-analyzer запустите приложение. По умолчанию источником данных ClickHouse служит общедоступный демонстрационный кластер в режиме «только для чтения», поэтому дополнительная настройка не требуется:

./run.sh

Откройте http://localhost:5001. Вы увидите переключатель года, сводную статистику, диаграмму активности, таблицы самых активных пользователей и доменов, а также поле поиска. Попробуйте приложение: переключайте годы, открывайте подробности историй.

Приложение HackerNews Analyzer, запущенное локально

На этом этапе приложение запущено, но не оснащено инструментированием. ClickStack пока не показывает данных: он ожидает телеметрию.

Настройте окружение

SDK используют стандартные переменные экспортёра OpenTelemetry. Они не прописаны жёстко в исходном коде. Откройте .env и задайте:

OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

OTEL_EXPORTER_OTLP_ENDPOINT — конечная точка OTLP/HTTP (порт 4318). OTEL_EXPORTER_OTLP_HEADERS — заголовок авторизации в формате authorization=<token> без префикса Bearer.Если коллектор не требует аутентификации, оставьте токен пустым (OTEL_EXPORTER_OTLP_HEADERS=authorization=). Переменная всё равно должна быть задана: SDK пропускает инициализацию, если она не задана или полностью пуста.Browser SDK использует те же значения. vite.config.ts встраивает конечную точку и токен в публичный bundle на этапе сборки, поэтому используйте одноразовый токен ингестии, а не токен для продакшна.

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

Выберите один из вариантов. Все три приведут к одному и тому же инструментированному приложению.

Инструментирование с помощью агента
Ручное инструментирование
Используйте предварительно инструментированную ветку

Клонировав репозиторий и заполнив .env, вставьте этот промпт в coding agent из этого каталога, чтобы инструментировать приложение.

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

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

npm install @hyperdx/node-opentelemetry

Включите обёртку в run.sh

В конце run.sh находятся две строки exec. Закомментируйте обычную строку node и раскомментируйте строку с инструментированием:

 # ДО: обычный node, без инструментирования:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # ПОСЛЕ: тот же исходный код, обёрнутый opentelemetry-instrument:
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

Продолжайте запускать приложение через scripts/entrypoint.js. Этот shim вызывает require('console'), поэтому захват консольных сообщений оборачивает console.log. Если указать для opentelemetry-instrument непосредственно dist/server/index.js, трассы будут отправляться, но логи будут незаметно теряться.

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

npm install @hyperdx/browser

В src/web/telemetry.ts раскомментируйте импорт, блок HyperDX.init({...}) и HyperDX.addAction в recordAction():

-// import HyperDX from '@hyperdx/browser';
+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,
-  // });
+  HyperDX.init({
+    url: __OTLP_ENDPOINT__,
+    apiKey: __OTLP_AUTH_TOKEN__,
+    service: 'hn-analyzer-web',
+    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
+    consoleCapture: true,
+    advancedNetworkCapture: true,
+  });
 }

__OTLP_ENDPOINT__ и __OTLP_AUTH_TOKEN__ — константы времени компиляции, которые vite.config.ts внедряет из тех же значений OTEL_EXPORTER_OTLP_*, что использует backend.

Токен ингестии встраивается в публичный браузерный bundle и доступен любому, кто просматривает вкладку Network. Используйте одноразовый токен.

Чтобы пропустить инструментирование и начать работу с уже инструментированным приложением, переключитесь на ветку instrumented.

git checkout instrumented
npm install

Не запускайте ./reset.sh в этой ветке, если не хотите удалить SDK.

Создайте трафик и просмотрите телеметрические данные

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

# Ctrl-C the previous run, then:
./run.sh

Убедитесь, что в стартовом баннере выводятся три строки “Проверка работоспособности пройдена” для /v1/traces, /v1/metrics и /v1/logs. Перезагрузите вкладку браузера, чтобы Vite отдал обновлённый bundle, затем переключайте годы и открывайте истории, чтобы сгенерировать трафик.Откройте интерфейс ClickStack:

Перейдите в Search и установите период «последние 5 минут». Начнут поступать журналы hn-analyzer-api.

Поиск ClickStack с журналами hn-analyzer-api за последние пять минут

Откройте запрос и перейдите к родительским спанам трассировки. Вы увидите спан обработчика Express, дочерний HTTP-спан, указывающий на sql-clickhouse.clickhouse.com, с фактической длительностью сетевого запроса, а также коррелированные записи console.log в той же трассировке.

Трассировка ClickStack со спаном обработчика Express и дочерним HTTP-спаном к ClickHouse

Откройте Воспроизведение сеанса, чтобы просмотреть видео сеанса браузера с возможностью перемотки, синхронизированное со шкалой времени трассировки.

Воспроизведение сеанса ClickStack, синхронизированное со шкалой времени трассировки

Журналы, метрики, трассировки и воспроизведения сеансов отображаются в одном интерфейсе, используют один язык запросов и автоматически коррелируются.

Подробнее

HackerNews Analyzer: репозиторий демо-приложения, которое инструментируется в этом руководстве.
Воспроизведение сеанса: обзор этой возможности, варианты SDK и настройки конфиденциальности.
Демо воспроизведения сеанса: автономное демо с локальным экземпляром ClickStack.
Начало работы с ClickStack: разверните ClickStack и настройте приём первых данных.
Все демонстрационные наборы данных: другие демонстрационные наборы данных и руководства.

Начало работы

Возможности

Управление ClickStack

Руководства

Партнёры по интеграции

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

Клонируйте репозиторий

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

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

Включите обёртку в run.sh

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

Подробнее

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

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

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

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

​Включите обёртку в run.sh

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

​Подробнее

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

Клонируйте репозиторий

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

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

Включите обёртку в run.sh

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

Подробнее