varnishncsa

СИНОПСИС

varnishncsa [-a] [-b] [-c] [-C] [-d] [-D] [-E] [-F ] [-f ] [-g ] [-h] [-j] [-k ] [-L ] [-n

ОПИСАНИЕ

Утилита varnishncsa считывает журналы общей памяти varnishd(1) и отображает их в формате Apache/NCSA «комбинированный».

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

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

-a

При записи в файл, добавить в него данные, а не перезаписывать. Этот параметр не имеет эффекта без параметра -w.

-b

Журналировать запросы бэкенда. Если не указан параметр -c, то только запросы бэкенда будут вызывать строки журнала.

-c

Журналировать запросы клиента. Это значение по умолчанию. Если указан параметр -b, то для журналирования запросов клиента необходим параметр -c.

-C

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

-d

Обработать записи журнала в начале журнала и выйти.

-D

Запустить в режиме демона.

-E

Отобразить запросы ESI, подразумевает режим клиента.

-F <format>

Установить строку формата выходного журнала.

-f <formatfile>

Считать формат вывода из файла. Считает одну строку из указанного файла и использует ее в качестве формата.

-g <request|vxid>

Группировка записей журнала. По умолчанию группировка по vxid.

-h

Вывести использование программы и выйти.

-j

Подготовить форматирующие спецификаторы для совместимости с JSON. При экранировании символов используйте JSON-стиль \uXXXX, а не C-стиль \xXX. Пустые строки будут заменены на "" вместо "-", а пустые целые числа — на null. Используйте -F или -f в сочетании с -j для записи JSON-журналов.

-k <num>

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

-L <limit>

Устанавливает верхний предел неполных транзакций, хранимых до завершения самой старой транзакции. При этом генерируется запись предупреждения. Эта настройка сохраняет верхнюю границу использования памяти при выполнении запросов. По умолчанию 1000 транзакций.

-n <dir>

Указывает рабочую директорию varnishd (также известную как имя экземпляра) для получения журналов. Если -n не указан, используется имя хоста.

-P <file>

Записать PID процесса в указанный файл.

-Q <file>

Указывает файл, содержащий запрос VSL для использования. При указании нескольких параметров -Q или -q все запросы рассматриваются как если бы использовался оператор «или» для их объединения.

-q <query>

Указывает запрос VSL для использования. При указании нескольких параметров -q или -Q все запросы рассматриваются как если бы использовался оператор «или» для их объединения.

-r <filename>

Считать журнал в двоичном формате из файла. Файл можно создать с помощью varnishlog -w filename. Если имя файла -, журналы считываются со стандартного ввода. Не может работать в режиме демона.

-R <limit[/duration]>

Ограничить вывод указанным пределом. Транзакции, превышающие предел, будут подавлены. Предел задается как максимальное количество транзакций (в зависимости от выбранного метода группировки) и необязательный период времени. Если период не указан, используется значение по умолчанию s. Поле duration может быть отформатировано как в VCL (например, -R 10/2m) или как простой временной интервал без префикса (например, -R 5/m). При группировке в -g raw режиме эта настройка не может быть использована вместе с -i, -I, -x или -X, и рекомендуется использовать -q.

-t <seconds|off>

Тайм-аут ожидания подключения к VSM до возврата ошибки. Если установлен, подключение к VSM будет повторяться каждую 0,5 секунды в течение этого количества секунд. Если ноль, подключение будет предпринято только один раз и немедленно завершится неудачей, если не удастся. Если установлено «off», подключение не будет завершаться ошибкой, позволяя утилите начать и ждать неопределенно долго появления экземпляра Varnish. По умолчанию 5 секунд.

-V

Вывести информацию о версии и выйти.

-w <filename>

Перенаправить вывод в файл. Файл будет перезаписан, если не был указан параметр -a. Если приложение получает SIGHUP в режиме демона, файл будет переоткрыт, позволяя старому быть удалённым. Этот параметр необходим при работе в режиме демона. Если имя файла -, varnishncsa записывает в стандартный вывод и не может работать в режиме демона.

--optstring

Вывести параметр optstring в getopt(3) для помощи в написании сценариев обёртки.

РЕЖИМЫ

По умолчанию varnishncsa работает в «режиме клиента». В этом режиме журнал будет похож на то, что создал бы веб-сервер без varnish. Режим клиента можно явно выбрать, используя параметр -c.

Если указан переключатель -b, varnishncsa будет работать в «режиме бэкенда». В этом режиме будут регистрироваться запросы, сгенерированные varnish для бэкендов. Если не указан -c, запросы клиентов, полученные varnish, будут проигнорированы.

При запуске varnishncsa в режимах бэкенда и клиента настоятельно рекомендуется включить форматирующую спецификацию %{Varnish:side}x для различения запросов бэкенда и клиента.

Запросы клиентов, которые приводят к пайпу (т. е. return(pipe) в vcl), не будут генерировать логи в режиме бэкенда. Это потому, что varnish не генерирует запросы, но просто передает байты в обоих направлениях. Однако экземпляр varnishncsa, работающий в обычном режиме, может увидеть этот случай, используя форматировщик %{Varnish:handling}x, который будет «pipe».

В режиме бэкенда некоторые поля в строке формата получают другое значение. В частности, форматирующие поля подсчета байтов (%b, %I, %O) учитывают varnish в качестве клиента.

Возможно запуск двух экземпляров varnishncsa, одного в режиме бэкенда и одного в режиме клиента, записывая в разные файлы.

ФОРМАТ

Укажите используемый формат журнала. Если формат не указан, используется стандартный формат журнала:

%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"

Поддерживаются управляющие последовательности \n и \t.

Поддерживаемые форматировщики:

%b

В режиме клиента, размер ответа в байтах, без HTTP-заголовков. В режиме бэкенда, количество полученных байтов от бэкенда, без HTTP-заголовков. В формате CLF, т.е. «-», а не 0, когда байты не отправляются.

%D

В режиме клиента, время обработки запроса в микросекундах. В режиме бэкенда, время от отправки запроса до получения всего тела. Эквивалентно %{us}T.

%H

Протокол запроса. По умолчанию HTTP/1.0, если не известен.

%h

Удаленный хост. По умолчанию «-», если не известен. В режиме бэкенда — IP-адрес сервера бэкенда.

%I

В режиме клиента, общее количество полученных байтов от клиента. В режиме бэкенда, общее количество отправленных байтов бэкенду.

%{X}i

Содержимое заголовка запроса X. Если заголовок встречается несколько раз в одной транзакции, используется последнее значение.

%l

Имя удаленного пользователя журнала. Всегда «-».

%m

Метод запроса. По умолчанию «-», если не известен.

%{X}o

Содержимое заголовка ответа X. Если заголовок встречается несколько раз в одной транзакции, используется последнее значение.

%O

В режиме клиента, общее количество отправленных байтов клиенту. В режиме бэкенда, общее количество полученных байтов от бэкенда.

%q

Строка запроса. По умолчанию пустая строка, если отсутствует.

%r

Первая строка запроса. Синтезируется из других полей, поэтому может не соответствовать запросу дословно. См. раздел ПРИМЕЧАНИЯ.

%s

Статус, отправленный клиенту. В режиме бэкенда, статус, полученный от бэкенда.

%t

В режиме клиента, время получения запроса в формате HTTP даты/времени. В режиме бэкенда, время отправки запроса.

%{X}t

В режиме клиента, время получения запроса в формате, указанном в X. В режиме бэкенда, время отправки запроса. Формат времени соответствует strftime(3) с расширениями:

• %{sec}: количество секунд с эпохи
• %{msec}: количество миллисекунд с эпохи
• %{usec}: количество миллисекунд с эпохи
• %{msec_frac}: дробная часть миллисекунды
• %{usec_frac}: дробная часть микросекунды

Расширения не могут быть объединены друг с другом или с strftime(3) в одной спецификации. Используйте несколько %{X}t спецификаций вместо этого.

%T

В режиме клиента, время обработки запроса в секундах. В режиме бэкенда, время от отправки запроса до получения всего тела. Эквивалентно %{s}T.

%{X}T

В режиме клиента, время обработки запроса в формате, указанном в X. В режиме бэкенда, время от отправки запроса до получения всего тела. Формат времени может быть одним из следующих: s (то же, что %T), ms или us (то же, что %D).

%U

URL запроса без строки запроса. По умолчанию «-», если не известен.

%u

Удаленный пользователь из аутентификации.

%{X}x

Расширенные переменные. Поддерживаемые переменные:

Varnish:time_firstbyte

Время с момента начала обработки запроса до отправки первого байта клиенту в секундах. В режиме бэкенда: время с момента отправки запроса на бэкенд до получения всего заголовка.

Varnish:hitmiss

В режиме клиента, одна из строк «hit» или «miss», в зависимости от того, был ли запрос попаданием в кэш или промахом. Труба, пропуск и синтез считаются промахами. В режиме бэкенда это поле пустое.

Varnish:handling

В режиме клиента, одна из строк «hit», «miss», «pass», «pipe» или «synth», указывающих, как обрабатывался запрос. В режиме бэкенда это поле пустое.

Varnish:side

Сторона бэкенда или клиента. Одно из двух значений, «b» или «c», в зависимости от того, где был сделан запрос. В чистом режиме бэкенда или клиента это поле будет постоянным.

Varnish:vxid

VXID транзакции varnish.

VCL_Log:key

Значение, установленное std.log(“key:value”) в VCL.

VSL:tag:record-prefix[field]

Значение записи VSL для заданной комбинации тег-префикс записи-поле. Тег обязателен, другие компоненты необязательны.

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

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

По умолчанию «-», если тег не найден, префикс записи не совпадает или поле находится вне границ. Если тег встречается несколько раз в одной транзакции, используется первое значение.

СИГНАЛЫ

• SIGHUP

  Перезапись файла журнала (см. опцию -w) в режиме демона, прервать цикл и корректно завершиться при работе в фоновом режиме.

• SIGUSR1

  Очистить все незавершенные транзакции.

ПРИМЕЧАНИЯ

Форматировщик %r эквивалентен «%m http://%{Host}i%U%q %H». Это отличается от поведения %r в Apache, эквивалентного «%m %U%q %H». Кроме того, при использовании форматировщика %r, если заголовок Host встречается несколько раз в одной транзакции, используется первое значение.

ПРИМЕР

Вывести второе поле записи Begin, соответствующее VXID родительской транзакции:

varnishncsa -F "%{VSL:Begin[2]}x"

Вывести всю запись Timestamp, связанную с длительностью обработки:

varnishncsa -F "%{VSL:Timestamp:Process}x"

Вывести в формате JSON, используя флаг -j, чтобы гарантировать, что вывод является корректным JSON для всех входных данных:

varnishncsa -j -F '{"size": %b, "time": "%t", "ua": "%{User-Agent}i"}'

СМОТРИТЕ ТАКЖЕ

varnishd varnishlog varnishstat VSL

ИСТОРИЯ

Утилита varnishncsa была разработана Poul-Henning Kamp в сотрудничестве с Verdens Gang AS и Varnish Software AS. Эта страница руководства была первоначально написана Dag-Erling Smørgrav <des@des.no>, а затем обновлена Martin Blix Grydeland и Pål Hermunn Johansen.

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

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

• Copyright (c) 2006 Verdens Gang AS
• Copyright (c) 2006-2016 Varnish Software AS