Модуль ngx_otel_module

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

Модуль ngx_otel_module (1.23.4) предоставляет поддержку распределённого трассирования OpenTelemetry. Модуль поддерживает распространение контекста по стандарту W3C и протокол экспорта OTLP/gRPC.

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

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

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

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

адрес конечной точки OTLP/gRPC, которая будет принимать данные телеметрии.

interval

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

batch_size

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

batch_count

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

Пример:

otel_exporter {
    endpoint    localhost:4317;
    interval    5s;
    batch_size  512;
    batch_count 4;
}

Устанавливает атрибут «service.name» ресурса 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

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

inject

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

propagate

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

ignore

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

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

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

Атрибуты по умолчанию для трассировок

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

• 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

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

$otel_span_id

идентификатор текущей трассировки, например, 4c0b8531ec38ca59

$otel_parent_id

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

$otel_parent_sampled

флаг «sampled» родительской трассировки, может быть «1» или «0»