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

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.

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

Возможность динамически управлять параметрами трассировки с помощью cookies, токенов и переменных. Пожалуйста, смотрите наш пример 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.