vsl-query

Выражения запроса Varnish VSL

Раздел руководства:: 7

ОБЗОР

Выражения запроса Varnish VSL извлекают транзакции из журнала общей памяти Varnish и выполняют запросы к транзакциям перед отображением совпадений.

Транзакция — это набор строк журнала, которые относятся к одному событию, например, запросу клиента или запросу к бэкенду. API отслеживает журнал и собирает все записи журнала, составляющие транзакцию, прежде чем сообщать о ней. Транзакции также могут быть сгруппированы, то есть транзакции бэкенда отображаются вместе с транзакцией клиента, которая её инициировала.

Запрос выполняется на группе транзакций. Выражение запроса истинно, если в группе есть запись журнала, удовлетворяющая условию. Оно ложно только если ни одна из записей журнала не удовлетворяет условию. Выражения запросов можно комбинировать с помощью булевых функций. Помимо записей журнала, можно выполнять запросы к идентификаторам транзакций (vxid).

ГРУППИРОВАНИЕ

При группировании транзакций используется иерархическая структура, показывающая, какая транзакция инициировала другую. Уровень увеличивается на единицу при «инициировании» связи, поэтому, например, транзакция бэкенда будет иметь уровень на единицу выше, чем транзакция клиента, которая её инициировала при промахе кэша. Транзакции перезапуска запроса не увеличивают свой уровень для предсказуемости.

Уровни начинаются с 1, за исключением использования сырого режима, где они всегда будут 0.

Режимы группирования:

session

Все транзакции, инициированные клиентом, отображаются вместе. Клиентские соединения открыты для использования HTTP keep-alive, поэтому не определено, когда будет сообщено о сессии. Если срок ожидания транзакции истекает, будет сообщено о незавершенной сессии. Нетранзакционные данные (vxid == 0) не отображаются.
request

Транзакции группируются по запросу, где набор включает сам запрос, а также любые запросы бэкенда или подзапросы ESI. Данные сессии и нетранзакционные данные (vxid == 0) не отображаются.
vxid

Транзакции не группируются, поэтому каждый vxid отображается полностью. Сессии, запросы, запросы ESI и запросы бэкенда отображаются по отдельности. Нетранзакционные данные не отображаются (vxid == 0). Это значение по умолчанию.
raw

Каждая запись журнала будет составлять свою транзакцию. Все данные, включая нетранзакционные данные, будут отображаться.

Иерархия транзакций

Пример иерархии транзакций с использованием режима группировки по запросам

Lvl 1: Client request (cache miss)
  Lvl 2: Backend request
  Lvl 2: ESI subrequest (cache miss)
    Lvl 3: Backend request
    Lvl 3: Backend request (VCL restart)
    Lvl 3: ESI subrequest (cache miss)
      Lvl 4: Backend request
  Lvl 2: ESI subrequest (cache hit)

ИСПОЛЬЗОВАНИЕ ПАМЯТИ

API будет использовать указатели на данные журнала общей памяти как можно дольше, чтобы минимизировать использование памяти. Но поскольку журнал общей памяти является кольцевым буфером, данные будут перезаписываться в конечном итоге, поэтому API создаёт локальные копии ссылочных данных журнала, когда varnishd приближается к перезаписи ещё не обработанного контента.

Этот процесс предотвращает потерю данных журнала во многих сценариях, но это не гарантия: переполнение, когда varnishd «обходит» процесс чтения журнала в кольцевом буфере, всё ещё может произойти, когда клиенты API не могут продолжать чтение и/или копирование, например, из-за блокировки вывода.

Хотя это не связано с группировкой по принципу, копирование данных журнала особенно важно для группировки сессий вместе с долгоживущими клиентскими подключениями — для этой группировки процесс клиента API журнала, вероятно, будет потреблять значительное количество памяти. Поскольку группировка vxid также регистрирует (потенциально долгоживущие) сессии, ей также может потребоваться память для копий записей журнала, но значительно меньше, чем группировке сессий.

ЯЗЫК ЗАПРОСОВ

Выражение запроса состоит из критериев выбора записей и, необязательно, оператора и значения для сопоставления с выбранными записями.

<record selection criteria> <operator> <operand>

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

vxid <numerical operator> <integer>

Запрос vxid позволяет напрямую выбрать конкретную транзакцию, идентификатор которой можно получить из X-Varnish HTTP-заголовка, стандартной страницы ошибки «guru meditation» или Begin и Link записей журнала.

Запрос должен помещаться на одной строке, но можно передавать несколько запросов одновременно, по одному запросу на строку. Пустые строки игнорируются, и список запросов обрабатывается как если бы использовался оператор «или» для их объединения.

Например, этот список запросов:

# catch varnish errors
*Error

# catch backend errors
BerespStatus >= 500

эквивалентен этому запросу:

(*Error) or (BerespStatus >= 500)

Можно использовать комментарии, которые будут игнорироваться, они начинаются с символа '#', что может быть полезнее, когда запрос считывается из файла.

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

Например, этот запрос:

BerespStatus >= 500

эквивалентен этому запросу:

BerespStatus \
>= \
500

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

Критерии выбора записей

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

{level}taglist:record-prefix[field]

Список тегов обязателен, остальные компоненты необязательны.

Уровень ограничивает выражение транзакцией на этом уровне. Если уровень не указан, выражение применяется ко всем уровням транзакций. Уровень — это целое положительное число или ноль. Если за уровнем следует символ «+», выражение означает больше или равно. Если за уровнем следует символ «-», выражение означает меньше или равно.

Список тегов — это список тегов VSL записей журнала, разделенных запятыми, к которым должно применяться это выражение. Каждый элемент списка может быть именем тега или шаблоном тега. Шаблоны тегов позволяют использовать «*» в начале или конце имени и будут выбирать все теги, которые соответствуют либо префиксу, либо суффиксу. Один символ «*» выберет все теги.

Префикс записи дополнительно ограничивает соответствия записями, у которых этот префикс является первой частью содержимого записи, за которым следует двоеточие. Часть записи журнала, к которой применяется соответствие, затем ограничивается тем, что следует после префикса и двоеточия. Это полезно при соответствии определённым HTTP-заголовкам. Сопоставление префиксов записи выполняется без учёта регистра.

Поле, если присутствует, обрабатывает запись журнала как список полей, разделённых пробелами, и только n-я часть записи будет сопоставляться. Счёт полей начинается с 1.

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

Операторы

Доступны следующие операторы сравнения:

== != < <= > >=

Числовое сравнение. Содержимое записи будет преобразовано в целое число или число с плавающей точкой перед сравнением, в зависимости от типа операнда.
eq ne

Строковое сравнение. «eq» проверяет равенство строк, «ne» проверяет неравенство.
~ !~

Сопоставление с регулярным выражением. «~» — положительное соответствие, «!~» — отсутствие соответствия.

Операнд

Операнд — это значение, с которым сравниваются выбранные записи.

Операнд может быть заключён в кавычки или без них. Кавычки могут быть одинарными или двойными, а для операндов в кавычках обратная косая черта может использоваться для экранирования кавычек.

Неограниченные операнды могут содержать только следующие символы:

a-z A-Z 0-9 + - _ . *

Доступны следующие типы операндов:

Целое число

Число без дробной части, действительное для числовых операторов сравнения. Тип целого числа используется, когда операнд не содержит символов точки (.) или экспоненты (e). Однако, если запись оценивается как число с плавающей точкой, для сравнения используется только её целая часть.
Число с плавающей точкой

Число с дробной частью, действительное для числовых операторов сравнения. Тип числа с плавающей точкой используется, когда операнд содержит символ точки (.) или экспоненты (e).
Строка

Последовательность символов, действительная для операторов строкового сравнения.
Регулярное выражение

Регулярное выражение PCRE2. Действительно для операторов регулярных выражений.

Булевы функции

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

not <expr>

Инвертирует результат <expr>
<expr1> and <expr2>

Истинно только если <expr1> и <expr2> истинны
<expr1> or <expr2>

Истинно, если <expr1> или <expr2> истинны

Выражения можно группировать с помощью скобок.

ПРИМЕРЫ ВЫРАЖЕНИЙ ЗАПРОСА

Группа транзакций содержит URL-адрес запроса, равный «/foo»
```
ReqURL eq "/foo"
```
Группа транзакций содержит заголовок cookie запроса
```
ReqHeader:cookie
```
Группа транзакций не содержит заголовок cookie запроса
```
not ReqHeader:cookie
```
Запрос клиента, где внутренняя обработка заняла более 800 мс.:
```
Timestamp:Process[2] > 0.8
```
Группа транзакций содержит заголовок user-agent запроса, содержащий «iPod», и время доставки запроса превышает 1 секунду
```
ReqHeader:user-agent ~ "iPod" and Timestamp:Resp[2] > 1.
```
Группа транзакций содержит статус ответа бэкенда, больший или равный 500
```
BerespStatus >= 500
```
Группа транзакций содержит статус ответа запроса 304, но запрос не содержал заголовка if-modified-since
```
RespStatus == 304 and not ReqHeader:if-modified-since
```
Транзакции, у которых были сбои бэкенда или большое время доставки по их подзапросам ESI. (Предполагается режим группировки по запросам).
```
BerespStatus >= 500 or {2+}Timestamp:Process[2] > 1.
```
Нетранзакционные ошибки журнала. (Предполагается режим группировки «raw»).
```
vxid == 0 and Error
```

ИСТОРИЯ

Этот документ изначально был написан Мартином Бликс Гриделандом и был изменён другими.

АВТОРСКИЕ ПРАВА

Этот документ лицензирован так же, как и сам Varnish. Подробности см. в файле LICENCE.