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

Мониторинг трассировок приложения на Node.js с ClickStack

Кратко

Собирайте распределённые трассировки приложений Node.js в ClickStack с помощью автоматической инструментации OpenTelemetry. Включены демо-набор данных и преднастроенная панель мониторинга.

​

Интеграция с существующим приложением Node.js

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

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

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

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

1. ​

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

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

2. ​

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

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

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

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

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

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

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

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

   # Простые запросы
   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
   
5. ​

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

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

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

​

Демо-набор данных

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

1. ​

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

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

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

   Запустите 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
   
3. ​

   Получите ключ 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
   
4. ​

   Отправьте трассировки в 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":{}} — это означает, что трассировки успешно отправлены.

5. ​

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

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

   Отображение часового пояса

   HyperDX отображает временные метки в часовом поясе, установленном в вашем браузере. Демо-данные охватывают период 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC). Широкий временной диапазон гарантирует, что вы увидите демо-трассировки независимо от своего местоположения. После этого можно сузить диапазон до 24 часов для более наглядной визуализации.

​

Панели мониторинга и визуализация

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

1. ​

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

2. ​

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

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

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

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

   Для демо-набора данных установите временной диапазон 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (с учётом вашего местного часового пояса). По умолчанию временной диапазон в импортированной панели мониторинга не задан.

​

Устранение неполадок

​

Демо-трассировки не появляются при отправке через curl

Если вы отправили трассировки через 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 и не затрагивает продакшен-приложения с настроенной телеметрией.

​

В HyperDX не отображаются трассировки

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

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. Это хорошо подходит для разработки, тестирования, а также небольших и средних production-развертываний. Для более крупных production-сред или если вам нужен дополнительный контроль над данными телеметрии, рассмотрите возможность развернуть собственный OpenTelemetry Collector в качестве агента. См. Приём данных с OpenTelemetry — там описаны типовые схемы развертывания для production и приведены примеры конфигурации OpenTelemetry Collector.