Мониторинг трассировок в Node.js с ClickStack

В этом разделе описано, как добавить распределённую трассировку в существующее приложение Node.js с помощью автоматической инструментации OpenTelemetry.

Если вы хотите протестировать интеграцию перед настройкой собственной среды, воспользуйтесь нашей предварительно настроенной средой и примерами данных в разделе о демо-наборе данных.

• Запущенный экземпляр ClickStack с доступными конечными точками OTLP (порты 4317/4318)
• Существующее приложение Node.js (Node.js 14 или выше)
• Менеджер пакетов npm или yarn
• Имя хоста или IP-адрес ClickStack

Установите и настройте OpenTelemetry

Установите пакет @hyperdx/node-opentelemetry и инициализируйте его при запуске приложения. Подробные инструкции по установке см. в руководстве по SDK для Node.js.

Получите ключ API ClickStack

Ключ API для отправки трассировок в конечную точку OTLP ClickStack.

1. Откройте HyperDX по URL вашего ClickStack (например, http://localhost:8080)
2. При необходимости создайте учётную запись или войдите в систему
3. Перейдите в Team Settings → API Keys
4. Скопируйте свой Ingestion API Key

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

Запустите приложение Node.js, предварительно задав переменные окружения:

export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Сгенерируйте немного трафика

Сделайте несколько запросов к приложению, чтобы сгенерировать трассировки:

# Простые запросы
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# Имитация нагрузки
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done

Проверьте трассировки в HyperDX

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

Нажмите на любую трассировку, чтобы открыть подробный просмотр со спанами, длительностью и атрибутами:

Для пользователей, которые хотят протестировать трассировку Node.js в ClickStack перед добавлением инструментации в свои production-приложения, мы предоставляем пример набора данных с заранее сгенерированными трассировками приложения Node.js с реалистичными шаблонами трафика.

Загрузите пример набора данных

Загрузите файл с примерами трассировок:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

Запустите ClickStack

Если ClickStack у вас ещё не запущен, выполните:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest

Получите ключ API ClickStack

Ключ API нужен для отправки трассировок в конечную точку OTLP ClickStack.

1. Откройте HyperDX по URL вашего ClickStack (например, http://localhost:8080)
2. Создайте учётную запись или войдите в систему, если это необходимо
3. Перейдите в Team Settings → API Keys
4. Скопируйте свой Ingestion API Key

Задайте ключ API как переменную окружения:

export CLICKSTACK_API_KEY=your-api-key-here

Отправьте трассировки в ClickStack

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

В ответ вы должны увидеть {"partialSuccess":{}} — это означает, что трассировки успешно отправлены.

Проверьте трассировки в HyperDX

1. Откройте HyperDX и войдите в свою учётную запись (возможно, сначала потребуется её создать)
2. Перейдите в представление Search и выберите источник Traces
3. Установите временной диапазон 2025-10-25 13:00:00 - 2025-10-28 13:00:00

Чтобы вам было проще начать мониторинг производительности приложения Node.js, мы предоставляем преднастроенную панель мониторинга с основными визуализациями трассировок.

Скачать конфигурацию панели мониторинга

Скачать файл конфигурации панели мониторинга.

Импортируйте преднастроенную панель мониторинга

1. Откройте HyperDX и перейдите в раздел Dashboards
2. Нажмите Import Dashboard в правом верхнем углу (в меню с многоточием)

3. Загрузите файл nodejs-traces-dashboard.json и нажмите Finish Import

Панель мониторинга будет создана со всеми преднастроенными визуализациями

Если вы отправили трассировки через curl, но не видите их в HyperDX, попробуйте отправить их ещё раз:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

Это известная проблема, которая возникает при использовании демонстрационного сценария через curl и не затрагивает продакшен-приложения с настроенной телеметрией.

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

echo $CLICKSTACK_API_KEY
# Должен вывести ваш API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Должен вывести http://localhost:4318 или хост вашего ClickStack

Проверьте подключение к сети:

curl -v http://localhost:4318/v1/traces

Подключение к конечной точке OTLP должно пройти успешно.

Проверьте журналы приложения: При запуске приложения ищите сообщения об инициализации OpenTelemetry. SDK HyperDX должен вывести подтверждение успешной инициализации.

• Настройте оповещения для критически важных метрик (частоты ошибок, пороговых значений задержки)
• Создайте дополнительные панели мониторинга для конкретных сценариев использования (мониторинг API, события безопасности)

В этом руководстве используется SDK HyperDX, который отправляет трассировки напрямую в конечную точку OTLP ClickStack. Это хорошо подходит для разработки, тестирования и небольших или средних продакшн-развертываний. Для более крупных продакшн-сред или если вам нужен дополнительный контроль над данными телеметрии, рассмотрите развертывание собственного OpenTelemetry Collector в роли агента. См. Приём данных с помощью OpenTelemetry: там описаны шаблоны развертывания для продакшна и приведены примеры конфигурации коллектора.