Перейти к основному содержанию
Перейти к основному содержанию

Мониторинг трасс Nginx с помощью ClickStack

TL;DR

В этом руководстве показано, как собирать распределённые трассы из существующей установки Nginx и визуализировать их в ClickStack. Вы узнаете, как:

  • Добавить модуль OpenTelemetry в Nginx
  • Настроить Nginx на отправку трасс на OTLP-эндпоинт ClickStack
  • Проверить, что трассы появляются в HyperDX
  • Использовать готовую панель для визуализации характеристик запросов (задержка, ошибки, пропускная способность)

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

Требуемое время: 5–10 минут

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

В этом разделе рассматривается, как добавить распределённое трассирование в вашу существующую установку Nginx, установив модуль OpenTelemetry и настроив его на отправку трейсов в ClickStack. Если вы хотите протестировать интеграцию до настройки собственной установки, вы можете воспользоваться нашим предварительно настроенным стендом и примером данных в следующем разделе.

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

Установка модуля OpenTelemetry для Nginx​

Проще всего добавить трассировку в Nginx с помощью официального образа Nginx со встроенной поддержкой OpenTelemetry.

Использование образа nginx:otel​

Замените ваш текущий образ Nginx версией с поддержкой OpenTelemetry:

# В вашем docker-compose.yml или Dockerfile \{#in-your-docker-composeyml-or-dockerfile}
image: nginx:1.27-otel

Этот образ включает предустановленный модуль ngx_otel_module.so, готовый к использованию.

Примечание

Если вы запускаете Nginx вне Docker, обратитесь к документации OpenTelemetry для Nginx для инструкций по ручной установке.

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

Добавьте конфигурацию OpenTelemetry в файл nginx.conf. Конфигурация загружает модуль и направляет трейсы в OTLP-эндпоинт ClickStack.

Сначала получите ваш ключ API:

  1. Откройте HyperDX по вашему URL ClickStack
  2. Перейдите в Settings → API Keys
  3. Скопируйте ваш Ingestion API Key
  4. Установите его как переменную окружения: export CLICKSTACK_API_KEY=your-api-key-here

Добавьте это в ваш nginx.conf:

load_module modules/ngx_otel_module.so;

events {
    worker_connections 1024;
}

http {
    # Конфигурация экспортера OpenTelemetry
    otel_exporter {
        endpoint <clickstack-host>:4317;
        header authorization ${CLICKSTACK_API_KEY};
    }
    
    # Имя сервиса для идентификации этого экземпляра nginx
    otel_service_name "nginx-proxy";
    
    # Включение трассировки
    otel_trace on;
    
    server {
        listen 80;
        
        location / {
            # Включить трассировку для этого location
            otel_trace_context propagate;
            otel_span_name "$request_method $uri";
            
            # Добавить детали запроса в трейсы
            otel_span_attr http.status_code $status;
            otel_span_attr http.request.method $request_method;
            otel_span_attr http.route $uri;
            
            # Ваша существующая конфигурация прокси или приложения
            proxy_pass http://your-backend;
        }
    }
}

Если вы запускаете Nginx в Docker, передайте переменную окружения в контейнер:

services:
  nginx:
    image: nginx:1.27-otel
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

Замените <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 -t

Если тест прошёл успешно, перезагрузите Nginx:

# Для Docker \{#for-docker}
docker-compose restart nginx

# Для systemd \{#for-systemd}
sudo systemctl reload nginx

Проверка трейсов в HyperDX​

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

Просмотр трассировок

Демонстрационный набор данных​

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

Запуск ClickStack​

Если ClickStack у вас ещё не запущен, запустите его с помощью:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

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

  • Порт 8080: веб-интерфейс HyperDX
  • Порт 4317: OTLP gRPC endpoint (используется модулем nginx)
  • Порт 4318: OTLP HTTP endpoint (используется для демонстрационных трасс)

Загрузка демонстрационного набора данных​

Скачайте файл с демонстрационными трассами и обновите метки времени на текущее время:

# Загрузить трассы
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json

Набор данных включает:

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

Отправка трасс в ClickStack​

Установите свой API key как переменную окружения (если он ещё не установлен):

export CLICKSTACK_API_KEY=your-api-key-here

Получение вашего API key:

  1. Откройте HyperDX по вашему ClickStack URL
  2. Перейдите в Settings → API Keys
  3. Скопируйте свой Ingestion API Key

Затем отправьте трассы в ClickStack:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nginx-traces-sample.json
Запуск на localhost

В этом примере предполагается, что ClickStack запущен локально на localhost:4318. Для удалённых экземпляров замените localhost на имя хоста вашего ClickStack.

Вы должны увидеть ответ вида {"partialSuccess":{}}, указывающий, что трассы были успешно отправлены. Все 1 000 трасс будут приняты в ClickStack.

Проверка трасс в 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 часов для более наглядных визуализаций.

Просмотр трасс

Дашборды и визуализация​

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

Скачать конфигурацию дашборда​

Импортируйте готовый дашборд​

  1. Откройте HyperDX и перейдите в раздел Dashboards.
  2. Нажмите «Import Dashboard» в правом верхнем углу под значком с многоточием.
Импорт дашборда
  1. Загрузите файл nginx-trace-dashboard.json и нажмите «Finish import».
Завершение импорта

Дашборд будет создан со всеми преднастроенными визуализациями.​

Примечание

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

Пример дашборда

Поиск и устранение неисправностей​

Трейсы не отображаются в HyperDX​

Убедитесь, что модуль Nginx загружен:

nginx -V 2>&1 | grep otel

Вы должны увидеть упоминания модуля OpenTelemetry.

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

telnet <clickstack-host> 4317

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

Проверьте, что API-ключ задан:

echo $CLICKSTACK_API_KEY

В результате вы должны увидеть ваш API‑ключ (не пустой).

Проверьте логи ошибок nginx:

# Для Docker \{#for-docker}
docker logs <nginx-container> 2>&1 | grep -i otel

# Для systemd \{#for-systemd}
sudo tail -f /var/log/nginx/error.log | grep -i otel

Проверьте, нет ли ошибок, связанных с OpenTelemetry.

Проверьте, что nginx получает запросы:

# Проверьте журналы доступа для подтверждения трафика \{#check-access-logs-to-confirm-traffic}
tail -f /var/log/nginx/access.log

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

Если вы хотите продолжить изучение возможностей, ниже приведены варианты для экспериментов с вашей панелью мониторинга:

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