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

otel: Динамический модуль NGINX OpenTelemetry

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

  • RedHat Enterprise Linux 7, 8, 9 и 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-otel

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-otel

Включите модуль, добавив следующее в верхнюю часть файла /etc/nginx/nginx.conf:

load_module modules/ngx_otel_module.so;

Этот документ описывает nginx-module-otel v0.1.2, выпущенный 15 марта 2025 года.

Что такое OpenTelemetry

OpenTelemetry (OTel) — это фреймворк наблюдаемости для мониторинга, трассировки, устранения неполадок и оптимизации приложений. OTel позволяет собирать телеметрические данные из развернутого стека приложений.

Что такое NGINX Native OTel Module

Динамический модуль ngx_otel_module позволяет NGINX Open Source или NGINX Plus отправлять телеметрические данные на OTel коллектор. Он поддерживает распространение W3C trace context, экспорт трасс OpenTelemetry Protocol (OTLP)/gRPC и предлагает несколько преимуществ по сравнению с существующими модулями OTel, включая:

Улучшенная производительность

Реализации OTel от третьих сторон снижают производительность обработки запросов до 50%, когда трассировка включена. NGINX Native модуль ограничивает это влияние примерно до 10-15%.

Простота настройки

Настройка и конфигурация могут быть выполнены прямо в конфигурационных файлах NGINX.

Динамическое управление на основе переменных

Возможность динамически управлять параметрами трассировки, используя куки, токены и переменные. Пожалуйста, смотрите наш пример Ratio-based Tracing для получения дополнительных деталей.

Кроме того, NGINX Plus, доступный в рамках коммерческой подписки, позволяет динамически управлять параметрами выборки через NGINX Plus API и модули key-value store.

Включение модуля OTel

Следуя вышеуказанным шагам установки, модуль будет установлен в /etc/nginx/modules по умолчанию. Загрузите модуль, добавив следующую строку в верхнюю часть основного конфигурационного файла NGINX, расположенного по адресу /etc/nginx/nginx.conf.

load_module modules/ngx_otel_module.so;

Настройка модуля

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

Примеры

Используйте эти примеры для настройки некоторых распространенных случаев использования OTel трассировки.

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

Этот пример отправляет телеметрические данные для всех http-запросов.

http {
    otel_exporter {
        endpoint localhost:4317;
    }

    otel_trace on;

    server {
        location / {
            proxy_pass http://backend;
        }
    }
}

Трассировка на основе родителя

В этом примере мы наследуем контексты трассировки от входящих запросов и записываем спаны только если родительский спан был выбран для выборки. Мы также передаем контексты трассировки и решения о выборке на вышестоящие серверы.

http {
    server {
        location / {
            otel_trace $otel_parent_sampled;
            otel_trace_context propagate;

            proxy_pass http://backend;
        }
    }
}

Трассировка на основе соотношения

В этом примере на основе соотношения трассировка настроена для процента трафика (в данном случае 10%):

http {
    # трассировать 10% запросов
    split_clients $otel_trace_id $ratio_sampler {
        10%     on;
        *       off;
    }

    # или мы можем трассировать 10% пользовательских сессий
    split_clients $cookie_sessionid $session_sampler {
        10%     on;
        *       off;
    }

    server {
        location / {
            otel_trace $ratio_sampler;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

Сбор и просмотр трасс

Существует несколько методов и доступных программных пакетов для просмотра трасс. Для быстрого старта Jaeger предоставляет контейнер "все в одном" для сбора, обработки и просмотра данных трасс OTel. Следуйте этим шагам, чтобы скачать, установить, запустить и использовать OTel-сервисы Jaeger.

Журнал изменений

Смотрите нашу страницу релизов, чтобы отслеживать обновления.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-otel.