> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Демо HackerNews Analyzer

> Добавьте в приложение Node.js агент и отправляйте в ClickStack журналы, трассировки, метрики и записи воспроизведения сеансов

> [!NOTE]
>
> **Кратко**
>
> Клонируйте [HackerNews Analyzer](https://github.com/ClickHouse/hn-news-analyzer), укажите в `.env` конечную точку OTLP и токен, затем вставьте промпт агента. Backend не требует импортов OpenTelemetry: агент подключает `@hyperdx/node-opentelemetry` при запуске процесса.
>
> Требуемое время: около 10 минут

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

Это отличается от [демонстрации воспроизведения сеанса](https://clickhouse.com/docs/ru/clickstack/example-datasets/session-replay.md), где браузерное приложение инструментируется для работы с локальным 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](https://github.com/ClickHouse/hn-news-analyzer), установите зависимости и скопируйте шаблон файла окружения:

```bash theme={null}
git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env
```

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

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

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

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

```bash theme={null}
./run.sh
```

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

![Приложение HackerNews Analyzer, запущенное локально](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/getting-started/hackernews_main.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=5587ba7b6d7c6595e7782e5060586629)

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

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

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

```bash theme={null}
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 на этапе сборки, поэтому используйте одноразовый токен ингестии, а не токен для продакшна.

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

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

> [tab] Инструментирование с помощью агента
>
> Клонировав репозиторий и заполнив `.env`, вставьте этот промпт в coding agent **из этого каталога**, чтобы инструментировать приложение.
>
> Настройка с помощью агента
>
> `С помощью curl скачайте, прочитайте и выполните инструкции из: github.com/ClickHouse/hn-news-analyzer/blob/main/agent.md`
>
> Скопировать промпт
> Скопировано
>
> После клонирования hn-news-analyzer и заполнения .env запустите этот промпт из этого каталога. Работает с Claude Code, Cursor, Codex и другими coding agents.

> [tab] Ручное инструментирование
>
> Инструментирование состоит из трёх частей: установки SDK, изменения команды запуска и включения браузерного SDK. Это не изменяет бизнес-логику приложения.
>
> ### Установите Node SDK
>
> ```bash theme={null}
> npm install @hyperdx/node-opentelemetry
> ```
>
> ### Включите обёртку в run.sh
>
> В конце `run.sh` находятся две строки `exec`. Закомментируйте обычную строку `node` и раскомментируйте строку с инструментированием:
>
> ```diff theme={null}
>  # ДО: обычный 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
>
> ```bash theme={null}
> npm install @hyperdx/browser
> ```
>
> В `src/web/telemetry.ts` раскомментируйте импорт, блок `HyperDX.init({...})` и `HyperDX.addAction` в `recordAction()`:
>
> ```diff theme={null}
> -// 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.
>
> > [!WARNING]
> >
> > Токен ингестии встраивается в публичный браузерный bundle и доступен любому, кто просматривает вкладку Network. Используйте одноразовый токен.

> [tab] Используйте предварительно инструментированную ветку
>
> Чтобы пропустить инструментирование и начать работу с уже инструментированным приложением, переключитесь на [ветку `instrumented`](https://github.com/ClickHouse/hn-news-analyzer/tree/instrumented).
>
> ```bash theme={null}
> git checkout instrumented
> npm install
> ```
>
> Не запускайте `./reset.sh` в этой ветке, если не хотите удалить SDK.

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

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

```bash theme={null}
# Ctrl-C the previous run, then:
./run.sh
```

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

Откройте интерфейс ClickStack:

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

![Поиск ClickStack с журналами hn-analyzer-api за последние пять минут](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/getting-started/instrument_app_clickstack_logs.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=5fb0cdc33e97610f1f7f1c264f349aa0)

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

![Трассировка ClickStack со спаном обработчика Express и дочерним HTTP-спаном к ClickHouse](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/getting-started/instrument_app_clickstack_traces.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=77cefc89163e1e45a8475dd815ff95bd)

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

![Воспроизведение сеанса ClickStack, синхронизированное со шкалой времени трассировки](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/getting-started/instrument_app_clickstack_sessions.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=c80327d0ed8a5ac088bfa5979febf452)

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

## Подробнее

* [HackerNews Analyzer](https://github.com/ClickHouse/hn-news-analyzer): репозиторий демо-приложения, которое инструментируется в этом руководстве.
* [Воспроизведение сеанса](https://clickhouse.com/docs/ru/clickstack/features/session-replay.md): обзор этой возможности, варианты SDK и настройки конфиденциальности.
* [Демо воспроизведения сеанса](https://clickhouse.com/docs/ru/clickstack/example-datasets/session-replay.md): автономное демо с локальным экземпляром ClickStack.
* [Начало работы с ClickStack](https://clickhouse.com/docs/ru/clickstack/getting-started/index.md): разверните ClickStack и настройте приём первых данных.
* [Все демонстрационные наборы данных](https://clickhouse.com/docs/ru/clickstack/example-datasets/index.md): другие демонстрационные наборы данных и руководства.
