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

Самый простой способ добавить трассировку в Nginx — использовать официальный образ Nginx со встроенной поддержкой OpenTelemetry.

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

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

# В вашем docker-compose.yml или Dockerfile
image: nginx:1.27-otel

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

Добавьте конфигурацию 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 следующее:

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 или приложения
            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.

Что делает эта конфигурация

Что трассируется: Каждый запрос к Nginx создаёт спан трассировки, в котором отображаются:

• Метод запроса и путь
• Код состояния HTTP
• Длительность запроса
• Временная метка

Атрибуты спана: Директивы otel_span_attr добавляют метаданные к каждой трассировке, что позволяет фильтровать и анализировать запросы в HyperDX по коду состояния, методу, маршруту и т. д.

После внесения этих изменений проверьте конфигурацию Nginx:

nginx -t

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

# Для Docker
docker-compose restart nginx

# Для systemd
sudo systemctl reload nginx

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

Если 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 (используется модулем nginx)
• Порт 4318: конечная точка OTLP HTTP (используется для демо-трассировок)

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

# Скачать трассировки
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 мс
• Исходные шаблоны трафика сохранены, но сдвинуты к текущему времени

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

export CLICKSTACK_API_KEY=your-api-key-here

Как получить ключ API:

1. Откройте HyperDX по URL вашего ClickStack
2. Перейдите в Settings → API Keys
3. Скопируйте свой ключ API для приёма данных

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

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

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

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

Вот что вы должны увидеть в Search view:

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

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

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