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

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

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

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

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

Аргументы:

<name>               is an arbitrary name that will be reported in
                     messages. If no name is provided, "TRACE" is used.

<quiet>              inhibits trace messages.

<random-forwarding>  enables the random forwarding of parsed data. By
                     default, this filter forwards all previously parsed
                     data. With this parameter, it only forwards a random
                     amount of the parsed data.

<max>                is the maximum amount of data that can be forwarded at
                     a time. "max-fwd" option can be combined with the
                     random forwarding. <max> must be an positive integer.
                     0 means there is no limit.

<hexdump>             dumps all forwarded data to the server and the client.

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

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

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

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

Аргументы:

<name>      is the engine name that will be used to find the right scope in
            the configuration file. If not provided, all the file will be
            parsed.

<file>      is the path of the engine configuration file. This file can
            contain configuration of several engines. In this case, each
            part must be placed in its own scope.

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>      is name of the cache section this filter will use.

Кеш использует фильтр для сохранения кешируемых ответов. Чтобы определить, как и когда использовать кеш, необходимо применять правила 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>      is name of the fcgi-app section this filter will use.

Приложение 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>        is the OpenTracing filter id that will be used to find the
            right scope in the configuration file. If no filter id is
            specified, 'ot-filter' is used as default.  If scope is not
            specified in the configuration file, it applies to all defined
            OpenTracing filters.

<file>      is the path of the OpenTracing configuration file. The same
            file can contain configurations for multiple OpenTracing
            filters simultaneously. In that case we do not need to define
            scope so the same configuration applies to all filters or each
            filter must have its own scope defined.

Более подробная документация по работе, настройке и использованию фильтра находится в каталоге 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>      is the filter name that will be used by 'set-bandwidth-limit'
            actions to reference a specific bandwidth limitation filter.

<size>      is max number of bytes that can be forwarded over the period.
            The value must be specified for per-stream and shared bandwidth
            limitation filters. It follows the HAProxy size format and is
            expressed in bytes.

<pattern>   is a sample expression rule as described in section 7.3. It
            describes what elements will be analyzed, extracted, combined,
            and used to select which table entry to update the counters. It
            must be specified for shared bandwidth limitation filters only.

<table>     is an optional table to be used instead of the default one,
            which is the stick-table declared in the current proxy. It can
            be specified for shared bandwidth limitation filters only.

<time>      is the default time period used to evaluate the bandwidth
            limitation rate. It can be specified for per-stream bandwidth
            limitation filters only. It follows the HAProxy time format and
            is expressed in milliseconds.

<min-size>  is the optional minimum number of bytes forwarded at a time by
            a stream excluding the last packet that may be smaller. This
            value can be specified for per-stream and shared bandwidth
            limitation filters. It follows the HAProxy size format and is
            expressed in bytes.

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

Порядок определения этих фильтров важен. Если для потока включено несколько фильтров пропускной способности, они применяются в порядке определения. Важно понимать, что влияет и порядок определения остальных фильтров. Например, в зависимости от того, определён ли фильтр сжатия 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».