Подключение трейсинга Nginx в Proto Observability Platform

На этой странице:

• Введение
• Установка модуля трейсинга для Nginx версии >= 1.22.0
• Работа модуля трейсинга с настройками по умолчанию
• Настройка с помощью директив конфигурации
  • protoobp_service_name
  • protoobp_environment
  • protoobp_sample_rate
  • protoobp_agent_url
  • protoobp_tag
  • protoobp_delegate_sampling
  • protoobp_enable
  • protoobp_disable
  • protoobp_trace_locations
• Настройка с помощью переменных окружения
  • POBP_AGENT_HOST
  • POBP_ENV
  • POBP_INSTRUMENTATION_TELEMETRY_ENABLED
  • POBP_SERVICE
  • POBP_VERSION
  • POBP_TRACE_128_BIT_TRACEID_GENERATION_ENABLED
  • POBP_TRACE_SAMPLE_RATE
• Если Nginx работает в Kubernetes
• Поддерживаемые версии Nginx
• Установка и настройка для версий Nginx < 1.22

Введение

Общий процесс подключения Nginx:

1. Установка ProtoOBP Агента
2. Установка модуля трейсинга
3. Конфигурация трейсера
4. Настройка Агента для сбора метрик Nginx (не зависит от модуля трейсинга)

Установка модуля трейсинга для Nginx версии >= 1.22.0

1. Скачайте архив текущей версии трейсера с модулями для всех версий Nginx:

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-nginx/1.2.1/ngx_http_protoobp_module-1.2.1.tar.gz" --output ngx_http_protoobp_module-1.2.1.tar.gz
   
   tar -xzvf ngx_http_protoobp_module-1.2.1.tar.gz
   

   Структура содержимого архива:

   <номер версии трейсера>/<номер версии Nginx>/ngx_http_protoobp_module.so

2. Скопируйте модуль, соответствующий вашей версии Nginx из каталога с номером версии трейсера (например, 1.2.1) в каталог с модулями nginx:

   cp 1.2.1/1.22.0/ngx_http_protoobp_module.so /usr/lib/nginx/modules/
   

3. Инициализируйте модуль в самой верхней части основного конфигурационного файла Nginx (например /etc/nginx/nginx.conf):

   load_module modules/ngx_http_protoobp_module.so;
   

Работа модуля трейсинга с настройками по умолчанию

По умолчанию, без какой-либо настройки, у трейсера для Nginx будет следующее поведение:

• отправка трейсов агенту по адресу http://localhost:8126
• создание одного спана на каждый запрос
• имя сервиса: nginx

Для большинства сценариев потребуется настройка модуля, например, указание адреса агента и имени сервиса.

Настройка с помощью директив конфигурации

Поведение модуля Nginx Protoobp может быть настроено с помощью специальных директив в файле конфигурации nginx.

Конфигурационные файлы Nginx имеют иерархическую структуру:

# "main" context

events {
    # ...
}

http {
    # "http" context

    server {
        # "server" context
        listen 80;

        location /ping {
            # "location" context
            # ...
        }

        location /auth {
            if ($request_method = POST) {
                # "if" context
                # ...
            }
            # ...
        }
    }
}

Каждый контекст наследует свою конфигурацию от окружающего контекста. Контексты расположенные ближе к “главному” контексту, находятся на “более высоком уровне”, а контексты, более глубоко вложенные контексты находятся на “более низком уровне”.

Например, в конфигурации выше, location /ping наследует всю свою конфигурацию от окружающего server, который, в свою очередь, наследует свою конфигурацию от окружающего контекста “main”.

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

Модуль трассировки Protoobp определяет следующие директивы конфигурации.

protoobp_service_name

• синтаксис protoobp_service_name <name>
• по умолчанию: nginx
• контекст: http

Устанавливает имя службы, которое будет ассоциироваться с каждым спаном, созданным этим модулем.

protoobp_environment

• синтаксис protoobp_environment <environment>
• по умолчанию: (no value)
• контекст: http

Устанавливает имя окружения, в котором работает nginx. Общие значения включают prod, dev и staging.

protoobp_sample_rate

• синтаксис protoobp_sample_rate <rate> [on|off]
• по умолчанию: N/A
• контекст: http, server, location

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

<rate> – это число от 0.0 до 1.0, включительно. Ноль означает «никогда», а единица – «всегда», 0,5 означает «половину времени», т.е. 50%.

Опционально укажите третий аргумент, представляющий собой переменное выражение, которое должно оцениваться как on или off. Если оно принимает значение on, выбирается соответствующая частота сэмплирования. Если оно имеет значение off, то связанная частота семплирования игнорируется. Любое другое значение ведет себя как off и регистрирует ошибку. Если третий аргумент опущен, то по умолчанию принимается значение on.

Директивы protoobp_sample_rate в контекстах конфигурации нижнего уровня имеют приоритет над директивами в контекстах конфигурации более высокого уровня. Если несколько директив на одном уровне конфигурации, то их выражения on/off проверяются по порядку. Первая директива, выражение которой оценивается в on, будет применяться на этом уровне конфигурации.

Например, рассмотрим следующую выдержку из файла конфигурации nginx:

 1  http {
 2      map $http_x_request_category $healthcheck_toggle {
 3          healthcheck    on;
 4          default    off;
 5      }
 6
 7      protoobp_sample_rate 0 $healthcheck_toggle;
 8      protoobp_sample_rate 0.1;
 9
10      server {
11          listen 80;
12
13          location / {
14              proxy_pass http://upstream;
15          }
16
17          location /admin {
18              protoobp_sample_rate 1.0;
19              proxy_pass http://admin-portal;
20          }
21      }
22  }

У location / в строке 13 нет собственного protoobp_sample_rate, поэтому он наследует его от окружающих контекстов конфигурации. Не существует директивы protoobp_sample_rate непосредственно в блоке server, но но она есть в блоке http. Первая находится в строке 7 и является условной, основанной на значении переменной $healthcheck_toggle, которая определена в map в строке 2.

Запрос, направляющийся к location /, будет сэмплирован на 0% (то есть данные ), если заголовок X-Request-Category имеет значение healthcheck, согласно параметру protoobp_sample_rate в строке 7. Если заголовок X-Request-Category отсутствует или имеет значение, отличное от healthcheck, то запрос будет сэмплироваться с частотой 10%, согласно protoobp_sample_rate в строке 8.

Запрос, который направляется к location /admin, будет сэмплирован на 100%, согласно параметру protoobp_sample_rate в строке 18.

Применяемая директива protoobp_sample_rate, если таковая имеется, аннотируется в span запроса в виде тега nginx.sample_rate_source. Этот тег имеет следующий формат:

<nginx file path>:<line>#<dupe>

Например,

/etc/nginx/nginx.conf:23#1

• <nginx file path> – это путь к файлу конфигурации nginx, который содержит директиву protoobp_sample_rate.
• <line> – это номер строки, где находится директива.
• <dupe> – это индекс директивы среди всех директив protoobp_sample_rate, которые появляются в той же строке. Как правило, каждая директива находится в отдельной строке, поэтому <dupe>, скорее всего, всегда 1.

protoobp_agent_url

• синтаксис protoobp_agent_url <url>
• по умолчанию: http://localhost:8126
• контекст: http

Укажите URL-адрес, по которому можно связаться с агентом Protoobp. Поддерживаются следующие форматы:

• http://<domain or IP>:<port>
• http://<domain or IP>
• http+unix://<path to socket>
• unix://<path to socket>

Если порт не указан, по умолчанию используется значение 8126.

protoobp_tag

• синтаксис protoobp_tag <key> <value>
• контекст: http, server, location

Установить на активном в данный момент span тег, имя которого – указанный <key> и значение которого является результатом оценки указанного <значения> в контексте текущего запроса. <значение> – это строка, которая может содержать $-переменные (включая те, которые предоставляются этим модулем).

protoobp_delegate_sampling

• синтаксис protoobp_delegate_sampling [on|off]
• по умолчанию off
• контекст http, server, location

Если on, и если nginx принимает решение о семплировании трейса (т.е. если nginx является первым сервисом в трейсе), то делегировать решение о сэмплировании upstream сервису.

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

По умолчанию делегирование сэмплирования отключено. Аргументом директивы может быть выражение переменной, которое оценивается как on или off. Если аргумент директивы опущен, то действует так, как если бы это было on.

protoobp_enable

• синтаксис protoobp_enable
• контекст http, server, location

Включает трассировку Protoobp в текущем контексте конфигурации. Это отменяет любые директивы protoobp_disable на более высоких уровнях, и может быть отменено директивами protoobp_disable на более низких уровнях.

Когда трассировка включена, для каждого запроса создается span, а контекст трейса передается проксируемому сервису.

Трейсинг включен по умолчанию.

protoobp_disable

• синтаксис protoobp_disable
• контекст http, server, location

Отключение трассировки Protoobp в текущем контексте конфигурации. Это отменяет любые директивы protoobp_enable на более высоких уровнях и может быть переопределено директивой protoobp_enable на более низких уровнях.

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

По умолчанию трассировка Protoobp включена. Эта директива позволяет отключить ее.

protoobp_trace_locations

• синтаксис protoobp_trace_locations on|off
• по умолчанию: off
• контекст: http, server, location

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

По умолчанию эта опция off, так что для каждого запроса создается только один span.

Настройка с помощью переменных окружения

Трейсер поддерживает следующие переменные окружения для конфигурирования:

POBP_AGENT_HOST

Устанавливает имя хоста агента ProtoOBP. Если значение не задано, то по умолчанию используется localhost.

В случае использования агента, запущенного в Docker или docker compose – укажите имя контейнера.

POBP_ENV

Устанавливает имя окружения, в котором работает nginx. Общие значения включают prod, dev и staging.

POBP_INSTRUMENTATION_TELEMETRY_ENABLED

Рекомендуемое значение: false.

POBP_SERVICE

Имя сервиса для отображения в интерфейсе. Если не указано – значение будет равно nginx

POBP_VERSION

Версия сервиса, передается в теге version.

POBP_TRACE_128_BIT_TRACEID_GENERATION_ENABLED

Рекомендуемое значение false, так как не все остальные трейсеры еще поддерживают 128 битный формат trace_id.

POBP_TRACE_SAMPLE_RATE

Процент сэмплирования трейсов. Число от 0.0 до 1.0 включительно. Ноль означает «никакие трейсы не собираются», а единица – «все трейсы собираются». 0,6 означает, что будет собрано 60% трейсов.

Если Nginx работает в Kubernetes

Убедитесь, что у вас успешно установлен и настроен ProtoOBP Агент для Kubernetes.

Дополнительно необходимо передать поду переменную окружения POBP_AGENT_HOST со значением IP адреса воркер-ноды, а также переменные окружения для связи трейсов с инфраструктурой (имя k8s кластера нужно задать вручную).

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<CONTAINER_NAME>"
        image: "<CONTAINER_IMAGE>/<TAG>"
        env:
          - name: POBP_SERVICE
            value: api-gateway			
          - name: POBP_AGENT_HOST
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: POD_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          - name: POD_NAME
            valueFrom:
              fieldRef:
                fieldPath: metadata.name
          - name: POBP_TAGS
            value: "pod_name:$(POD_NAME),node:$(NODE_NAME),kube_namespace:$(POD_NAMESPACE),kube_cluster_name:<my_cluster_name>"            
            

Поддерживаемые версии Nginx

Поддерживаются все версии базовых Docker образов Nginx от 1.16.0 до 1.27.4.

• Если у вас Nginx версии >= 1.22, используйте версию трейсера 1.2.1.
• Если у вас Nginx версии < 1.22, используйте версию трейсера 2.3.0.

Обратите внимание, что версия трейсера 2.3.0 является архивной, а 1.2.1 – текущей и активной (контринтуитивная особенность версионирования).

Установка и настройка для версий Nginx < 1.22

1. Скачайте модуль для вашей версии Nginx (cписок поддерживаемых версий):

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-nginx/2.3.0/<nginx-version>-nginx-module.tar.gz" --output <nginx-version>-nginx-module.tar.gz
   
   tar -xzvf <nginx-version>-nginx-module.tar.gz
   

2. Скопируйте полученый файл из папки protoobp в каталог с модулями nginx:

   cp protoobp/libngx_http_protoobp_module.so /usr/lib/nginx/modules/
   

3. Инициализируйте модуль в самой верхней части основного конфигурационного файла Nginx (например /etc/nginx/nginx.conf):

   load_module modules/libngx_http_protoobp_module.so;
   

4. Добавьте в секцию http конфигурации NGINX параметры ProtoOBP модуля:

   http {
       protoobp {
         "service": "<my_nginx_name>", # Имя сервиса
         "sample_rate": 1, #процент сэмплирования, 100 – все вызовы, 10 – данные будут собираться только с 10% вызовов
       }
       ...
   }
   

Если NGINX запускается в контейнере, то в конфигурации необходимо указать адрес ProtoOBP агента:

  http {
      protoobp {
        "service": "<my_nginx_name>", # Имя сервиса
        "sample_rate": 1, #процент сэмплирования, 100 – все вызовы, 10 – данные будут собираться только с 10% вызовов
        "agent_host": "<protoobp-agent>", # Укажите IP адрес хоста, где запущен ProtoOBP агент, доступные из сети Docker контейнера. В случае если агент запускается в виде Docker контейнера, то достаточно указать имя контейнера
        "agent_port": 8126 # порт по умолчанию
      }
      ...
  }