9. Поддерживаемые фильтры

Ниже перечислены официально поддерживаемые фильтры и принимаемые ими параметры. В зависимости от параметров сборки некоторые фильтры могут быть недоступны. Список доступных фильтров выводится командой haproxy -vv.

См. также: «filter».

9.1. Трассировка

filter trace [name <name>] [random-forwarding] [max-fwd <max>] [hexdump]

Аргументы:

<name>               — произвольное имя, указываемое в сообщениях.
                     Если имя не задано, используется "TRACE".

<quiet>              подавляет сообщения трассировки.

<random-forwarding>  включает пересылку случайного объёма разобранных данных.
                     По умолчанию фильтр пересылает все ранее разобранные
                     данные. С этим параметром пересылается только случайная
                     часть разобранных данных.

<max>                — максимальный объём данных, пересылаемых за один раз.
                     Параметр "max-fwd" можно сочетать с пересылкой случайного
                     объёма данных. <max> должен быть положительным целым
                     числом. 0 означает отсутствие ограничения.

<hexdump>             выводит дамп всех данных, пересылаемых серверу и клиенту.

Этот фильтр можно использовать как основу для разработки новых фильтров. Он определяет все обратные вызовы и для каждого из них выводит в стандартный поток ошибок (stderr) сообщение с полезными сведениями. Это может пригодиться для отладки работы других фильтров или самого HAProxy.

Параметры <random-parsing> и/или <random-forwarding> удобны для проверки поведения фильтра, разбирающего данные, которыми обмениваются клиент и сервер: они добавляют задержки при обработке.

9.2. Сжатие HTTP

filter comp-req

Включает фильтр, явно пытающийся сжимать запросы HTTP в соответствии с настройками «compression». Неявно задаёт «compression direction request».

filter comp-res

Включает фильтр, явно пытающийся сжимать ответы HTTP в соответствии с настройками «compression». Неявно задаёт «compression direction response».

filter compression (устарел)

Псевдоним для обратной совместимости, функционально эквивалентный одновременному включению фильтров «comp-req» и «comp-res». Для настройки нужного поведения необходимо использовать директиву «compression»:

В HAProxy 1.7 сжатие HTTP было перенесено в фильтр. Для включения и настройки сжатия HTTP по-прежнему необходимо использовать директиву «compression». Если другие фильтры не используются, этого достаточно. Этого также достаточно при включённом кеше или fcgi-app. В таком случае сжатие всегда выполняется после сохранения ответа в кеше. Но если для того же слушателя/фронтенда/бэкенда используется хотя бы один фильтр, отличный от кеша или fcgi-app, для включения сжатия HTTP обязательно нужно явно добавить строку filter. Это необходимо для определения порядка выполнения фильтров.

См. также: «compression», раздел 9.4 о фильтре кеша и раздел 9.5 о фильтре fcgi-app.

9.3. Механизм вынесения обработки потоков (SPOE)

filter spoe [engine <name>] config <file>

Аргументы:

<name>      — имя обработчика, по которому в файле конфигурации ищется
            нужная область. Если имя не задано, разбирается весь файл.

<file>      — путь к файлу конфигурации обработчика. Файл может содержать
            конфигурации нескольких обработчиков. В этом случае каждая
            часть должна находиться в собственной области.

Stream Processing Offload Engine (SPOE) — фильтр, взаимодействующий с внешними компонентами. Он позволяет выносить отдельные виды обработки потоков во внешние уровни приложения. Эти внешние компоненты и сведения, которыми они обмениваются с HAProxy, в основном настраиваются в отдельных файлах. Также требуются выделенные бэкенды, определённые в конфигурации HAProxy.

SPOE взаимодействует с внешними компонентами по собственному двоичному протоколу Stream Processing Offload Protocol (SPOP).

Когда SPOE используется для потока, создаётся отдельный поток для взаимодействия с внешним компонентом. Основной поток является родительским для этого потока «SPOE». Это означает, что из потока «SPOE» можно получать переменные основного потока. Дополнительные сведения приведены в разделе 2.8 о переменных.

Полные сведения о настройке SPOE и спецификации SPOP приведены в «doc/SPOE.txt».

9.4. Кеш

filter cache <name>

Аргументы:

<name>      — имя секции cache, которую будет использовать этот фильтр.

Кеш использует фильтр для сохранения кешируемых ответов. Чтобы определить, как и когда использовать кеш, необходимо применять правила HTTP «cache-store» и «cache-use». По умолчанию соответствующий фильтр определяется неявно. Если не используются другие фильтры, кроме fcgi-app или сжатия, этого достаточно. В таком случае фильтр сжатия всегда выполняется после фильтра кеша. Но если для того же слушателя/фронтенда/бэкенда используется хотя бы один фильтр, отличный от сжатия или fcgi-app, для использования кеша обязательно нужно явно добавить строку filter. Это необходимо для определения порядка выполнения фильтров.

См. также: раздел 9.2 о фильтре сжатия, раздел 9.5 о фильтре fcgi-app и раздел 6 о кеше.

9.5. Fcgi-app

filter fcgi-app <name>

Аргументы:

<name>      — имя секции fcgi-app, которую будет использовать этот фильтр.

Приложение FastCGI использует фильтр для вычисления всех пользовательских параметров при обработке запроса и для обработки заголовков ответа. <name> должен ссылаться на существующую секцию fcgi-app. Для указания используемого приложения следует применять директиву «use-fcgi-app». По умолчанию соответствующий фильтр определяется неявно. Если не используются другие фильтры, кроме кеша или сжатия, этого достаточно. Но если для того же бэкенда используется хотя бы один фильтр, отличный от сжатия или кеша, для fcgi-app обязательно нужно явно добавить строку filter. Это необходимо для определения порядка выполнения фильтров.

См. также: «use-fcgi-app», раздел 9.2 о фильтре сжатия, раздел 9.4 о фильтре кеша и раздел 10 о приложениях FastCGI.

9.6. OpenTracing

Фильтр OpenTracing добавляет в HAProxy встроенную поддержку распределённой трассировки. Для этого запрос, соответствующий OpenTracing, отправляется одному из поддерживаемых трассировщиков: Datadog, Jaeger, Lightstep или Zipkin. Обратите внимание: трассировщики перечислены в алфавитном порядке, а не в порядке предпочтения.

Эта возможность доступна только при сборке HAProxy с USE_OT=1.

Фильтр OpenTracing включается явным указанием в конфигурации HAProxy. Если этого не сделать, фильтр OpenTracing никак не участвует в работе HAProxy.

filter opentracing [id <id>] config <file>

Аргументы:

<id>        — идентификатор фильтра OpenTracing, по которому в файле
            конфигурации ищется нужная область. Если идентификатор фильтра
            не указан, по умолчанию используется 'ot-filter'. Если область
            в файле конфигурации не задана, конфигурация применяется ко всем
            определённым фильтрам OpenTracing.

<file>      — путь к файлу конфигурации OpenTracing. Один файл может
            одновременно содержать конфигурации нескольких фильтров
            OpenTracing. В этом случае область можно не задавать, чтобы
            одна конфигурация применялась ко всем фильтрам, либо для каждого
            фильтра должна быть определена отдельная область.

Более подробная документация по работе, настройке и использованию фильтра находится в каталоге addons/ot.

Примечание: фильтр OpenTracing не следует использовать в новых проектах, поскольку сами авторы OpenTracing больше его не развивают и не поддерживают. Поэтому OpenTracing будет объявлен устаревшим в 3.3 и удалён в 3.5. Заменяющий его фильтр на основе OpenTelemetry доступен с 3.4; полные инструкции по сборке сейчас находятся по адресу:

https://github.com/haproxytech/haproxy-opentelemetry/

9.7. Ограничение пропускной способности

filter bwlim-in  <name> default-limit <size> default-period <time> [min-size <sz>]
filter bwlim-out <name> default-limit <size> default-period <time> [min-size <sz>]
filter bwlim-in  <name> limit <size> key <pattern> [table <table>] [min-size <sz>]
filter bwlim-out <name> limit <size> key <pattern> [table <table>] [min-size <sz>]

Аргументы:

<name>      — имя фильтра, которое действия 'set-bandwidth-limit' используют
            для ссылки на конкретный фильтр ограничения пропускной способности.

<size>      — максимальное число байтов, пересылаемых за период. Значение
            должно быть задано как для фильтров с ограничением на отдельный
            поток, так и для фильтров с общим ограничением. Оно соответствует
            формату размеров HAProxy и выражается в байтах.

<pattern>   — правило выражения образца, описанное в разделе 7.3. Определяет,
            какие элементы будут анализироваться, извлекаться, объединяться
            и использоваться для выбора записи таблицы, в которой обновляются
            счётчики. Должно задаваться только для фильтров с общим
            ограничением пропускной способности.

<table>     — необязательная таблица, используемая вместо таблицы по умолчанию,
            то есть stick-table, объявленной в текущем прокси. Может задаваться
            только для фильтров с общим ограничением пропускной способности.

<time>      — период по умолчанию для расчёта ограничения скорости передачи.
            Может задаваться только для фильтров с ограничением на отдельный
            поток. Соответствует формату времени HAProxy и выражается
            в миллисекундах.

<min-size>  — необязательное минимальное число байтов, пересылаемых потоком
            за один раз, кроме последнего пакета, который может быть меньше.
            Значение можно задавать для фильтров с ограничением на отдельный
            поток и с общим ограничением. Оно соответствует формату размеров
            HAProxy и выражается в байтах.

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

Порядок определения этих фильтров важен. Если для потока включено несколько фильтров пропускной способности, они применяются в порядке определения. Важно понимать, что влияет и порядок определения остальных фильтров. Например, в зависимости от того, определён ли фильтр сжатия HTTP до или после фильтра ограничения пропускной способности, ограничение применяется к сжатой полезной нагрузке или к несжатой. То же верно для фильтра кеша.

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

Кроме того, в зависимости от использованного ключевого слова фильтра ограничение может применяться к входящим данным, получаемым от клиента и пересылаемым серверу, либо к исходящим данным, получаемым от сервера и отправляемым клиенту. Для ограничения входящих данных необходимо использовать «bwlim-in», для исходящих — «bwlim-out». В обоих случаях ограничивается пересылка данных на уровне потока.

Ограничение пропускной способности действует на уровне потока, а не соединения. Для протоколов с мультиплексированием (H2, H3 и FastCGI) потоки одного соединения могут иметь разные ограничения.

Для фильтра, ограничивающего отдельные потоки, необходимо определить период и предел по умолчанию. Как следует из названий, это значения по умолчанию для настройки скорости потока. Однако для этого типа фильтра, и только для него, эти значения можно переопределить с помощью выражений образцов при включении фильтра действием TCP/HTTP «set-bandwidth-limit».

Для фильтра с общим ограничением таблица привязок должна хранить сведения о соответствующей скорости передачи байтов в зависимости от того, ограничиваются входящие или исходящие данные. Для ограничения входящих данных необходимо хранить счётчик «bytes_in_rate(<period>)», для исходящих — использовать «bytes_out_rate(<period>)».

Наконец, можно задать минимальное число байтов, которое фильтр ограничения пропускной способности может переслать за один раз для данного потока. Эту настройку следует использовать, чтобы не пересылать слишком маленькие порции данных и уменьшить потребление CPU. Значение нужно выбирать внимательно. Слишком маленькое значение может увеличить потребление CPU, а слишком большое — задержку. Оно также тесно связано с заданным пределом пропускной способности. Если значение слишком близко к этому пределу, могут возникать паузы, необходимые для соблюдения ограничения, поскольку за один раз передаётся слишком много байтов. Результат сильно зависит от конфигурации фильтра. Хорошая отправная точка — около 2 TCP MSS, обычно 2896 байтов, с последующей настройкой по результатам экспериментов.

Пример:

frontend http
    bind *:80
    mode http

    # If this filter is enabled, the stream will share the download limit
    # of 10m/s with all other streams with the same source address.
    filter bwlim-out limit-by-src key src table limit-by-src limit 10m

    # If this filter is enabled, the stream will be limited to download at 1m/s,
    # independently of all other streams.
    filter bwlim-out limit-by-strm default-limit 1m default-period 1s

    # Limit all streams to 1m/s (the default limit) and those accessing the
    # internal API to 100k/s. Limit each source address to 10m/s. The shared
    # limit is applied first. Both are limiting the download rate.
    http-request set-bandwidth-limit limit-by-strm
    http-request set-bandwidth-limit limit-by-strm limit 100k if { path_beg /internal }
    http-request set-bandwidth-limit limit-by-src
    ...

backend limit-by-src
    # The stickiness table used by <limit-by-src> filter
    stick-table type ip size 1m expire 3600s store bytes_out_rate(1s)

См. также: «tcp-request content set-bandwidth-limit», «tcp-response content set-bandwidth-limit», «http-request set-bandwidth-limit» и «http-response set-bandwidth-limit».