Apache: Модуль Apache mod_log

RU EN

Пункт 158. Модуль Apache mod_log_config

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

Этот модуль предоставляет три директивы: TransferLog создание файла журнала, LogFormat установка пользовательского формата и CustomLog определение файла журнала и формата за один шаг. Директивы TransferLog и CustomLog можно использовать несколько раз на каждом сервере, чтобы каждый запрос регистрировался в нескольких файлах.

Пользовательские форматы журнала

Аргумент формата для директив LogFormat и CustomLog является строкой. Эта строка используется для записи каждого запроса в файл журнала. Он может содержать буквенные символы, скопированные в файлы журналов, и управляющие символы в стиле C "\n" и "\t" для обозначения новой строки и табуляции. Буквенные кавычки и обратные косые черты должны быть экранированы обратными косыми чертами.

Характеристики самого запроса регистрируются путем помещения % директив " " в строку формата, которые заменяются в лог-файле на следующие значения:

Строка формата Описание

%% Знак процента.

%a IP-адрес клиента запроса (см. mod_remoteip модуль).

%{c}a Базовый одноранговый IP-адрес соединения (см. mod_remoteip модуль).

%A Локальный IP-адрес.

%B Размер ответа в байтах, без учета заголовков HTTP.

%b Размер ответа в байтах, без учета заголовков HTTP. В формате CLF, т.е. ' - ' вместо 0, если байты не отправлены.

%{VARNAME}C Содержимое файла cookie VARNAME в запросе, отправленном на сервер. Полностью поддерживаются только файлы cookie версии 0.

%D Время, необходимое для обслуживания запроса, в микросекундах.

%{VARNAME}e Содержимое переменной окружения VARNAME .

%f Имя файла.

%h Имя удаленного хоста. Зарегистрирует IP-адрес, если HostnameLookups установлено Off значение по умолчанию. Если он регистрирует имя хоста только для нескольких хостов, возможно, у вас есть директивы управления доступом, в которых они упоминаются по имени. См. документацию «Требуется хост».

%H Протокол запроса.

%{VARNAME}i Содержимое строки заголовка в запросе, отправленном на сервер. На это влияют изменения, сделанные другими модулями (например , ). Если вас интересует, каким был заголовок запроса до того, как большинство модулей изменило бы его, используйте для копирования заголовка во внутреннюю переменную среды и зарегистрируйте это значение с помощью описанного выше. VARNAME: mod_headers mod_setenvif %{VARNAME}e

%k Количество запросов проверки активности, обработанных в этом соединении. Интересно, если KeepAlive используется, так что, например, «1» означает первый запрос проверки активности после начального, «2» — второй и т. д.; в противном случае это всегда 0 (указывает на первоначальный запрос).

%l Имя удаленного журнала (из identd, если указано). Это вернет дефис, если mod_ident он не присутствует и IdentityCheck не установлен On .

%L Идентификатор журнала запросов из журнала ошибок (или '-', если для этого запроса в журнал ошибок ничего не внесено). Найдите соответствующую строку журнала ошибок, чтобы увидеть, какой запрос вызвал какую ошибку.

%m Метод запроса.

%{VARNAME}n Содержимое примечания VARNAME из другого модуля.

%{VARNAME}o Содержимое строки заголовка в ответе. VARNAME:

%p Канонический порт сервера, обслуживающего запрос.

%{format}p Канонический порт сервера, обслуживающего запрос, или фактический порт сервера, или фактический порт клиента. Допустимые форматы canonical : local , или remote .

%P Идентификатор дочернего процесса, который обслужил запрос.

%{format}P Идентификатор процесса или потока дочернего элемента, обслужившего запрос. Допустимые форматы pid : , tid и hextid . hextid требуется APR 1.2.0 или выше.

%q Строка запроса (с префиксом a ? , если строка запроса существует, в противном случае — пустая строка).

%r Первая строка запроса.

%R Обработчик, генерирующий ответ (если есть).

%s Положение дел. Для запросов, которые были внутренне перенаправлены, это статус исходного запроса . Используйте %>s для окончательного статуса.

%t Время получения запроса в формате [18/Sep/2011:19:18:28 -0400] . Последнее число указывает на смещение часового пояса от GMT.

%{format}t

Время в форме, заданной форматом, которое должно быть в расширенном strftime(3) формате (возможно локализовано). Если формат начинается с begin: (по умолчанию), время берется в начале обработки запроса. Если он начинается с end: , это время, когда запись в журнал записывается, ближе к концу обработки запроса. Помимо форматов, поддерживаемых strftime(3) , поддерживаются следующие токены форматов:

`sec`	количество секунд с начала Эпохи
`msec`	количество миллисекунд с начала Эпохи
`usec`	количество микросекунд с начала Эпохи
`msec_frac`	доля миллисекунды
`usec_frac`	доля микросекунды

Эти токены нельзя комбинировать друг с другом или strftime(3) форматировать в одной и той же строке формата. Вместо этого вы можете использовать несколько токенов. %{format}t

%T Время, необходимое для обслуживания запроса, в секундах.

%{UNIT}T Время, затраченное на обслуживание запроса, в единицах времени, заданных UNIT . Допустимыми единицами измерения являются ms миллисекунды, us микросекунды и s секунды. Использование s дает тот же результат, что и %T без форматирования; использование us дает тот же результат, что и %D . Объединение %T с юнитом доступно в версии 2.4.13 и более поздних.

%u Удаленный пользователь, если запрос был аутентифицирован. Может быть поддельным, если статус возврата ( %s ) равен 401 (неавторизованный).

%U Запрошенный путь URL, не включая строку запроса.

%v Канонический ServerName сервер, обслуживающий запрос.

%V Имя сервера согласно UseCanonicalName настройке.

%X

Статус подключения после завершения ответа:

`X` "="	Соединение прервано до завершения ответа.
`+` "="	Соединение может поддерживаться после отправки ответа.
`-` "="	Соединение будет закрыто после отправки ответа.

%I Получено байтов, включая запрос и заголовки. Не может быть нулем. Вам нужно включить mod_logio , чтобы использовать это.

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

%S Байты переданы (получены и отправлены), включая запрос и заголовки, не могут быть равны нулю. Это комбинация %I и %O. Вам нужно включить mod_logio , чтобы использовать это.

%{VARNAME}^ti Содержимое строк трейлера в запросе, отправленном на сервер. VARNAME:

%{VARNAME}^to Содержимое строк трейлера в ответе, отправленном с сервера. VARNAME:

Модификаторы

Отдельные элементы могут быть ограничены для печати только для ответов с определенными кодами состояния HTTP, поместив список кодов состояния, разделенных запятыми, сразу после «%». Список кодов состояния может предваряться знаком " ! " для обозначения отрицания.

Строка формата	Значение
`%400,501{User-agent}i`	Регистрирует `User-agent` только ошибки 400 и 501 ошибку. `"-"` Для других кодов состояния будет регистрироваться литеральная строка .
`%!200,304,302{Referer}i`	Регистрирует `Referer` все запросы, которые не возвращают один из трех указанных кодов, " `-` " в противном случае.

Модификаторы «<» и «>» могут использоваться для запросов, которые были внутренне перенаправлены, чтобы выбрать, следует ли обращаться к исходному или окончательному (соответственно) запросу. По умолчанию % директивы %s, %U, %T, %D, и %r смотрят на исходный запрос, в то время как все остальные смотрят на окончательный запрос. Так, например, %>s может использоваться для записи окончательного состояния запроса и %<u может использоваться для записи исходного аутентифицированного пользователя по запросу, который внутренне перенаправляется на неаутентифицированный ресурс.

Примечания к формату

Из соображений безопасности, начиная с версии 2.0.46, непечатаемые и другие специальные символы в и %r экранируются с помощью последовательностей, где чч обозначает шестнадцатеричное представление необработанного байта. Исключениями из этого правила являются и , перед которыми ставится обратная косая черта, а также все пробельные символы, которые записываются в их нотации в стиле C ( , , и т. д.). В версиях до 2.0.46 для этих строк не выполнялось экранирование, поэтому вам нужно было быть очень осторожным при работе с необработанными файлами журнала. %i %o \xhh " \ \n \t

Начиная с httpd 2.0, в отличие от 1.3, строки формата %b и %B представляют не количество байтов, отправленных клиенту, а просто размер в байтах ответа HTTP (который будет отличаться, например, если соединение прервано или если SSL используется). Формат %O , предоставленный , mod_logio будет регистрировать фактическое количество байтов, отправленных по сети.

Примечание: mod_cache реализован как быстрый обработчик, а не как стандартный обработчик. Таким образом, %R строка формата не будет возвращать никакой информации об обработчике, когда задействовано кэширование содержимого.

Примеры

Некоторые часто используемые строки формата журнала:

Общий формат журнала (CLF): "%h %l %u %t \"%r\" %>s %b"
Общий формат журнала с виртуальным хостом: "%v %h %l %u %t \"%r\" %>s %b"
Расширенный/комбинированный формат журнала NCSA: "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Формат журнала реферера: "%{Referer}i -> %U"
Формат журнала агента (браузера): "%{User-agent}i"

Вы можете использовать %{format}t директиву несколько раз, чтобы создать формат времени, используя токены расширенного формата, такие как msec_frac :

Отметка времени, включая миллисекунды: "%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"

Вопросы безопасности

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

Директива BufferedLogs

Описание:	Буферизация записей журнала в памяти перед записью на диск
Синтаксис:	`BufferedLogs On\|Off`
По умолчанию:	`BufferedLogs Off`
Контекст:	конфигурация сервера
Положение дел:	База
Модуль:	mod_log_config

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

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

Директива CustomLog

Описание:	Устанавливает имя файла и формат файла журнала
Синтаксис:	`CustomLog file\|pipe format\|nickname [env=[!]environment-variable\| expr=expression]`
Контекст:	конфигурация сервера, виртуальный хост
Положение дел:	База
Модуль:	mod_log_config

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

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

файл

Имя файла относительно ServerRoot .

трубка

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

Безопасность:

Если используется программа, то она будет запущена от имени пользователя, запустившего httpd . Это будет root, если сервер был запущен root; убедитесь, что программа безопасна.

Примечание

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

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

Например, следующие два набора директив имеют одинаковый эффект:

 # CustomLog с никнеймом формата
LogFormat "%h %l %u %t \"%r\" %>s %b" общий
CustomLog "logs/access_log" общий
# CustomLog с явной строкой формата
CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"

Третий аргумент является необязательным и определяет, следует ли регистрировать конкретный запрос. Условием может быть наличие или отсутствие (в случае предложения ' ') определенной переменной в среде сервера. В качестве альтернативы условие может быть выражено как произвольное логическое выражение. Если условие не выполняется, запрос не регистрируется. Ссылки на заголовки HTTP в выражении не приводят к добавлению имен заголовков в заголовок Vary. env=!name

Переменные среды могут быть установлены для каждого запроса с помощью модулей mod_setenvif и/или mod_rewrite . Например, если вы хотите записывать запросы на все изображения GIF на вашем сервере в отдельный файл журнала, но не в ваш основной журнал, вы можете использовать:

 SetEnvIf Request_URI \.gif$ gif-изображение
CustomLog "gif-requests.log" общий env=gif-image
CustomLog "nonngif-requests.log" общий env=!gif-image

Или, чтобы воспроизвести поведение старой директивы RefererIgnore, вы можете использовать следующее:

 Пример SetEnvIf Referer\.com localreferer
CustomLog "referer.log" реферер env=!localreferer

Директива Глобаллог

Описание:	Устанавливает имя файла и формат файла журнала
Синтаксис:	`GlobalLogfile\|pipe format\|nickname [env=[!]environment-variable\| expr=expression]`
Контекст:	конфигурация сервера
Положение дел:	База
Модуль:	mod_log_config
Совместимость:	Доступно в Apache HTTP Server 2.4.19 и более поздних версиях.

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

Директива GlobalLog идентична директиве CustomLog , за исключением следующих отличий:

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

Директива LogFormat

Описание:	Описывает формат для использования в файле журнала
Синтаксис:	`LogFormat format\|nickname [nickname]`
По умолчанию:	`LogFormat "%h %l %u %t \"%r\" %>s %b"`
Контекст:	конфигурация сервера, виртуальный хост
Положение дел:	База
Модуль:	mod_log_config

Эта директива определяет формат файла журнала доступа.

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

Вторая форма директивы LogFormat связывает явный формат с псевдонимом . Затем этот псевдоним можно использовать в последующих директивах LogFormat или CustomLog вместо повторения всей строки формата. Директива LogFormat , определяющая псевдоним, больше ничего не делает , то есть она только определяет псевдоним, фактически не применяет формат и не делает его форматом по умолчанию. Следовательно, это не повлияет на последующие TransferLog директивы. Кроме того, LogFormat нельзя использовать один псевдоним для определения другого псевдонима. Обратите внимание, что псевдоним не должен содержать знаков процента ( % ).

Пример

 LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

Директива TransferLog

Описание:	Укажите расположение файла журнала
Синтаксис:	`TransferLog file\|pipe`
Контекст:	конфигурация сервера, виртуальный хост
Положение дел:	База
Модуль:	mod_log_config

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

Пример

 LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Журналы TransferLog/access_log