Перейти к основному содержанию
КраткоСобирайте распределённые трассировки из Nginx в ClickStack с помощью модуля OpenTelemetry для Nginx. Включает демо-набор данных и преднастроенный дашборд.

Интеграция с существующим Nginx

В этом разделе описано, как добавить распределённую трассировку в существующую установку Nginx: установить модуль OpenTelemetry и настроить отправку трассировок в ClickStack. Если вы хотите протестировать интеграцию перед настройкой собственной среды, воспользуйтесь нашей предварительно настроенной средой и тестовыми данными из следующего раздела.
Предварительные требования
  • Запущенный экземпляр ClickStack с доступными конечными точками OTLP (порты 4317/4318)
  • Установленный Nginx (версии 1.18 или выше)
  • Доступ root или sudo для изменения конфигурации Nginx
  • Имя хоста или IP-адрес ClickStack
1

Установите модуль OpenTelemetry для Nginx

Самый простой способ добавить трассировку в Nginx — использовать официальный образ Nginx со встроенной поддержкой OpenTelemetry.
Использование образа nginx:otel
Замените текущий образ Nginx на версию с поддержкой OpenTelemetry:
Этот образ включает ngx_otel_module.so, который уже установлен и готов к использованию.
Если вы запускаете Nginx вне Docker, см. документацию OpenTelemetry для Nginx с инструкциями по ручной установке.
2

Настройте Nginx для отправки трассировок в ClickStack

Добавьте конфигурацию OpenTelemetry в файл nginx.conf. Она загружает модуль и направляет трассировки в конечную точку OTLP ClickStack.Сначала получите свой ключ API:
  1. Откройте HyperDX по URL вашего ClickStack
  2. Перейдите в Settings → API Keys
  3. Скопируйте свой ключ API для приёма данных
  4. Задайте его как переменную окружения: export CLICKSTACK_API_KEY=your-api-key-here
Добавьте в nginx.conf следующее:
Если Nginx запущен в Docker, передайте переменную окружения в контейнер:
Замените <clickstack-host> на имя хоста или IP-адрес вашего экземпляра ClickStack.
  • Порт 4317 — это конечная точка gRPC, которую использует модуль Nginx
  • otel_service_name должен понятно описывать ваш экземпляр Nginx (например, “api-gateway”, “frontend-proxy”)
  • Измените otel_service_name в соответствии с вашим окружением, чтобы в HyperDX было проще различать источники
Что делает эта конфигурация
Что трассируется: Каждый запрос к Nginx создает спан трассировки, в котором отображаются:
  • Метод запроса и путь
  • Код состояния HTTP
  • Длительность запроса
  • Временная метка
Атрибуты спана: Директивы otel_span_attr добавляют метаданные к каждой трассировке, что позволяет фильтровать и анализировать запросы в HyperDX по коду состояния, методу, маршруту и т. д.После внесения этих изменений проверьте конфигурацию Nginx:
Если проверка прошла успешно, перезагрузите Nginx:
3

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

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

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

Для пользователей, которые хотят протестировать интеграцию трассировки nginx перед настройкой рабочих систем, мы предоставляем демо-набор данных с заранее сгенерированными трассировками Nginx с реалистичными шаблонами трафика.
1

Запустите ClickStack

Если ClickStack у вас ещё не запущен, запустите его с помощью:
Подождите около 30 секунд, пока ClickStack полностью инициализируется, прежде чем переходить дальше.
  • Порт 8080: веб-интерфейс HyperDX
  • Порт 4317: конечная точка OTLP gRPC (используется модулем nginx)
  • Порт 4318: конечная точка OTLP HTTP (используется для демо-трассировок)
2

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

Скачайте файл с примерами трассировок и сдвиньте временные метки к текущему времени:
Датасет включает:
  • 1 000 спанов трассировки с реалистичными временными характеристиками
  • 9 разных конечных точек с различающимися шаблонами трафика
  • ~93% успешных запросов (200), ~3% ошибок клиента (404), ~4% ошибок сервера (500)
  • Задержки в диапазоне от 10 мс до 800 мс
  • Исходные шаблоны трафика сохранены, но сдвинуты к текущему времени
3

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

Задайте свой ключ API как переменную окружения (если он ещё не задан):
Как получить ключ API:
  1. Откройте HyperDX по URL вашего ClickStack
  2. Перейдите в Settings → API Keys
  3. Скопируйте свой ключ API для приёма данных
Затем отправьте трассировки в ClickStack:
Запуск на localhostВ этом демо предполагается, что ClickStack запущен локально на localhost:4318. Для удалённых инстансов замените localhost на hostname вашего ClickStack.
Вы должны увидеть ответ вида {"partialSuccess":{}}, который означает, что трассировки успешно отправлены. Все 1 000 трассировок будут приняты ClickStack.
4

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

  1. Откройте HyperDX и войдите в свою учётную запись (возможно, сначала потребуется её создать)
  2. Перейдите в Search view и выберите в поле source значение Traces
  3. Установите временной диапазон 2025-10-25 13:00:00 - 2025-10-28 13:00:00
Вот что вы должны увидеть в Search view:
Отображение часового поясаHyperDX отображает временные метки в локальном часовом поясе вашего браузера. Демо-данные охватывают диапазон 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC). Широкий временной диапазон гарантирует, что вы увидите демо-трассировки независимо от своего местоположения. После этого можно сузить диапазон до 24 часов для более наглядных визуализаций.

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

Чтобы помочь вам начать мониторинг трассировок в ClickStack, мы предоставляем основные визуализации для данных трассировок.
1

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

2

Импортируйте преднастроенный дашборд

  1. Откройте HyperDX и перейдите в раздел Dashboards.
  2. Нажмите “Import Dashboard” в правом верхнем углу в меню с многоточием.
  1. Загрузите файл nginx-trace-dashboard.json и нажмите “Finish Import”.
3

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

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

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

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

Убедитесь, что модуль nginx загружен:
Вы должны увидеть ссылки на модуль OpenTelemetry. Проверьте сетевое подключение:
Подключение к конечной точке OTLP gRPC должно выполниться успешно. Убедитесь, что ключ API задан:
Должен выводиться ваш ключ API (не пустой). Проверьте журналы ошибок nginx:
Проверьте наличие ошибок, связанных с OpenTelemetry. Убедитесь, что nginx получает запросы:

Следующие шаги

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

Переход в production

В этом руководстве трассировки отправляются напрямую из модуля Nginx OpenTelemetry в конечную точку OTLP ClickStack. Для production-развертываний мы рекомендуем запускать собственный OTel Collector в роли шлюза, чтобы обеспечить батчинг и устойчивость к сбоям. Описание production-конфигурации см. в разделе Отправка данных OpenTelemetry.
Последнее изменение 25 июня 2026 г.