Модуль ngx_otel_module

• Пример конфигурации
• Директивы
• otel_exporter
• otel_service_name
• otel_resource_attr
• otel_trace
• otel_trace_context
• otel_span_name
• otel_span_attr
• Атрибуты span по умолчанию
• Встроенные переменные

Модуль ngx_otel_module обеспечивает поддержку распределённой трассировки OpenTelemetry. Модуль поддерживает распространение контекста W3C и протокол экспорта OTLP/gRPC.

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

Модуль также доступен в виде готового пакета nginx-module-otel пакета начиная с версии 1.25.3, а также в пакете nginx-plus-module-otel в составе нашей коммерческой подписки начиная с версии 1.23.4.

Пример конфигурации

load_module modules/ngx_otel_module.so;

events {
}

http {

    otel_exporter {
        endpoint localhost:4317;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            otel_trace         on;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

Директивы

Задаёт параметры экспорта данных OTel:

endpoint [(http|https)://]host:port;

Конечная точка OTLP/gRPC, принимающая данные телеметрии. Поддержка TLS добавлена в версии 0.1.2.

trusted_certificate path;

файл сертификатов CA в формате PEM, используемый для проверки конечной точки TLS (начиная с версии 0.1.2). По умолчанию используется предоставляемый ОС пакет сертификатов CA.

header name value;

пользовательский HTTP-заголовок, добавляемый к запросу экспорта телеметрии (начиная с версии 0.1.2).

interval time;

максимальный интервал между двумя экспортами; по умолчанию — 5 секунд.

batch_size number;

максимальное количество span, отправляемых в одном пакете одним рабочим процессом; по умолчанию — 512.

batch_count number;

количество ожидающих отправки пакетов на один рабочий процесс; span, превышающие этот предел, отбрасываются. По умолчанию — 4.

Пример:

otel_exporter {
    endpoint https://otel-example.nginx.com:4317;

    header X-API-Token "my-token-value";
}

Задаёт атрибут «service.name» ресурса OTel.

Задаёт пользовательский атрибут ресурса OTel.

Включает или отключает трассировку OpenTelemetry. Директиву также можно включить, указав переменную:

split_clients "$otel_trace_id" $ratio_sampler {
              10%              on;
              *                off;
}

server {
    location / {
        otel_trace         $ratio_sampler;
        otel_trace_context inject;
        proxy_pass         http://backend;
    }
}

Определяет способ передачи заголовков traceparent/tracestate:

extract

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

inject

добавляет в запрос новый контекст, перезаписывая существующие заголовки, если они есть.

propagate

обновляет существующий контекст (объединяет extract и inject).

ignore

пропускает обработку заголовков контекста.

Задаёт имя span OTel. По умолчанию используется имя location для запроса. Имя может содержать переменные.

Добавляет пользовательский атрибут span OTel. Значение может содержать переменные.

Атрибуты span по умолчанию

Следующие атрибуты span добавляются автоматически:

• http.method
• http.target
• http.route
• http.scheme
• http.flavor
• http.user_agent
• http.request_content_length
• http.response_content_length
• http.status_code
• net.host.name
• net.host.port
• net.sock.peer.addr
• net.sock.peer.port

Встроенные переменные

$otel_trace_id

идентификатор трассировки, к которой относится текущий span, например 56552bc4daa3bf39c08362527e1dd6c4

$otel_span_id

идентификатор текущего span, например 4c0b8531ec38ca59

$otel_parent_id

идентификатор родительского span, например dc94d281b0f884ea

$otel_parent_sampled

флаг «sampled» родительского span; может иметь значение «1» или «0»