журнал

Включает и настраивает протоколирование HTTP-запросов (также известное как журналы доступа).

Директива log применяется к именам хостов блока сайта, в котором она находится, если не переопределено с помощью поддирективы hostnames.

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

Чтобы добавить пользовательские поля в записи журнала, используйте директиву log_append.

Синтаксис
Модули вывода
- stderr
- stdout
- discard
- файл
- сетевой
Модули форматирования
Примеры

По умолчанию, заголовки с потенциально конфиденциальной информацией (Cookie, Set-Cookie, Authorization и Proxy-Authorization) будут записаны как REDACTED в журналах доступа. Это поведение можно отключить с помощью глобального параметра сервера log_credentials.

Синтаксис

log [<logger_name>] {
	hostnames <hostnames...>
	no_hostname
	output <writer_module> ...
	format <encoder_module> ...
	level  <level>
}

logger_name — это необязательная переопределённое имя логгера для данного сайта.

По умолчанию имя логгера генерируется автоматически, например, log0, log1 и так далее в зависимости от порядка сайтов в Caddyfile. Это полезно только если вы хотите надёжно ссылаться на вывод этого логгера из другого логгера, определённого в глобальных параметрах. См. пример ниже.
hostnames — это необязательная переопределённое имя хостов, к которым применяется этот логгер.

По умолчанию логгер применяется к именам хостов блока сайта, т. е. к адресам сайта. Это полезно, если вы хотите определить разные логгеры для каждого поддомена в блоке сайта с подстановкой (*) wildcard site block. См. пример ниже.
no_hostname — предотвращает ассоциацию логгера с какими-либо именами хостов блока сайта. По умолчанию логгер ассоциируется с адресом сайта, в котором находится директива log.

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

По умолчанию: stderr.
format — описывает способ кодирования или форматирования журналов. См. format модули ниже.

По умолчанию: console, если stderr определено как терминал, json в противном случае.
level — это минимальный уровень записи для логирования. По умолчанию: INFO.

Обратите внимание, что журналы доступа в настоящее время выдают только INFO и ERROR уровень журналов.

Модули вывода

Поддиректива output позволяет настраивать место записи журналов.

stderr

Стандартная ошибка (консоль, по умолчанию).

output stderr

stdout

Стандартный вывод (консоль).

output stdout

discard

Без вывода.

output discard

файл

Файл. По умолчанию файлы журналов вращаются ("роллируются"), чтобы предотвратить исчерпание дискового пространства.

Вращение журналов обеспечивается lumberjack

output file <filename> {
	mode          <mode>
	roll_disabled
	roll_size     <size>
	roll_uncompressed
	roll_local_time
	roll_keep     <num>
	roll_keep_for <days>
}

<filename> — путь к файлу журнала.
mode — это Unix режим/разрешения файла журнала. Режим состоит из от 1 до 4 восьмеричных цифр (так же как числовой формат, принимаемый командой Unix chmod, за исключением того, что режим со всеми нулями интерпретируется как режим по умолчанию 600). Например, 644 предоставляет чтение/запись владельцу файла журнала, но только чтение группе владельца и другим пользователям; 600 предоставляет чтение/запись владельцу файла журнала и никакого доступа никому другому.

По умолчанию: 600
roll_disabled отключает вращение журнала. Это может привести к истощению дискового пространства, поэтому используйте это только если ваши файлы журналов поддерживаются каким-то другим способом.
roll_size — размер, при достижении которого файл журнала будет свёрнут. Текущая реализация поддерживает разрешение мегабайт; дробные значения округляются до ближайшего целого мегабайта. Например, 1.1MiB округляется до 2MiB.

По умолчанию: 100MiB
roll_uncompressed отключает сжатие gzip журналов.

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

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

По умолчанию: 10
roll_keep_for — время хранения сжатых файлов в виде строки длительности. Текущая реализация поддерживает разрешение в днях; дробные значения округляются до ближайшего целого дня. Например, 36h (1,5 дня) округляется до 48h (2 дня). По умолчанию: 2160h (90 дней)

сетевой

Сеточная сокета. Если сокета выйдет из строя, он выведет журналы в stderr, пока пытается подключиться снова.

output net <address> {
	dial_timeout <duration>
	soft_start
}

<address> — адрес для записи журналов.
dial_timeout — время ожидания успешного подключения к сокету журнала. Вывод логов может быть заблокирован на срок до этого, если сокета выйдет из строя.
soft_start проигнорирует ошибки при подключении к сокету, позволяя загрузить конфигурацию, даже если удалённая служба логирования не работает. Журналы будут выводиться в stderr.

Модули форматирования

Поддиректива format позволяет настроить способ кодирования (форматирования) журналов. Она появляется внутри блока log.

В дополнение к синтаксису для каждого отдельного кодировщика, эти общие свойства могут быть заданы для большинства кодировщиков:

format <encoder_module> {
	message_key     <key>
	level_key       <key>
	time_key        <key>
	name_key        <key>
	caller_key      <key>
	stacktrace_key  <key>
	line_ending     <char>
	time_format     <format>
	time_local
	duration_format <format>
	level_format    <format>
}

message_key Ключ для поля сообщения записи журнала. По умолчанию: msg
level_key Ключ для поля уровня записи журнала. По умолчанию: level
time_key Ключ для поля времени записи журнала. По умолчанию: ts
name_key Ключ для поля имени записи журнала. По умолчанию: name
caller_key Ключ для поля вызывающей функции записи журнала.
stacktrace_key Ключ для поля стека вызовов записи журнала.
line_ending Коды завершения строки.
time_format Формат для временных меток.

По умолчанию: wall_milli, если формат по умолчанию console, unix_seconds_float в противном случае.

Может быть одним из:
- unix_seconds_float Дробное число секунд с эпохи Unix.
- unix_milli_float Дробное число миллисекунд с эпохи Unix.
- unix_nano Целое число наносекунд с эпохи Unix.
- iso8601 Пример: 2006-01-02T15:04:05.000Z0700
- rfc3339 Пример: 2006-01-02T15:04:05Z07:00
- rfc3339_nano Пример: 2006-01-02T15:04:05.999999999Z07:00
- wall Пример: 2006/01/02 15:04:05
- wall_milli Пример: 2006/01/02 15:04:05.000
- wall_nano Пример: 2006/01/02 15:04:05.000000000
- common_log Пример: 02/Jan/2006:15:04:05 -0700
- Или любая совместимая строка форматирования времени; см. документацию Go для получения подробной информации.
Обратите внимание, что части строки форматирования являются специальными константами для макета; так, 2006 — год, 01 — месяц, Jan — месяц в виде строки, 02 — день. Не используйте фактические текущие числовые значения даты в строке форматирования.
time_local Журналы с локальным временем системы вместо значения по умолчанию UTC.
duration_format Формат для промежутков времени.

По умолчанию: seconds.

Может быть одним из:
- s, second или seconds Дробное число секунд, прошедших.
- ms, milli или millis Дробное число миллисекунд, прошедших.
- ns, nano или nanos Целое число наносекунд, прошедших.
- string Используя встроенный формат Go, например 1m32.05s или 6.31ms.
level_format Формат для уровней.

По умолчанию: color, если формат по умолчанию console, lower в противном случае.

Может быть одним из:
- lower Строчные буквы.
- upper Заглавные буквы.
- color Заглавные буквы с ANSI-цветами.

консоль

Кодировщик консоли форматирует запись журнала для удобства чтения человеком, сохраняя при этом некоторую структуру.

format console

json

Форматирует каждую запись журнала как объект JSON.

format json

Фильтр

Разрешает фильтрацию по полям.

format filter {
	fields {
		<field> <filter> ...
	}
	<field> <filter> ...
	wrap <encode_module> ...
}

Вложенные поля можно ссылаться, представляя уровень вложенности с помощью >. Другими словами, для объекта, такого как {"a":{"b":0}}, внутреннее поле можно указать как a>b.

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

Указание wrap является необязательным; если оно опущено, выбирается значение по умолчанию в зависимости от того, является ли текущий модуль вывода stderr или stdout, и представляет ли он собой интерактивную консоль, в этом случае выбирается console, в противном случае выбирается json.

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

Доступные фильтры:

Удалить

Помечает поле для пропуска при кодировании.

<field> delete

Переименовать

Переименовать ключ поля журнала.

<field> rename <key>

Заменить

Помечает поле для замены предоставленной строкой во время кодирования.

<field> replace <replacement>

ip_mask

Маскирует IP-адреса в поле с помощью маски CIDR, т.е. количества битов из IP, которые сохранить, начиная с левой стороны. Если поле является массивом строк (например, заголовки HTTP), каждая строка в массиве маскируется. Значение может быть запятой-разделенной строкой IP-адресов.

Существует отдельная настройка для IPv4 и IPv6 адресов, так как у них разное общее количество битов.

Чаще всего фильтруемые поля:

request>remote_ip для непосредственно подключенного клиента
request>client_ip для разобранного "реального клиента", когда trusted_proxies настроен
request>headers>X-Forwarded-For если стоит за обратным прокси

<field> ip_mask [<ipv4> [<ipv6>]] {
	ipv4 <cidr>
	ipv6 <cidr>
}

запрос

Помечает поле для выполнения одного или нескольких действий, чтобы манипулировать частью запроса поля URL. Чаще всего фильтруемым полем является request>uri.

<field> query {
	delete  <key>
	replace <key> <replacement>
	hash    <key>
}

Доступные действия:

Удалить удаляет заданный ключ из запроса.
Заменить заменяет значение заданного ключа запроса на замену. Полезно для вставки маркера маскировки; вы увидите, что ключ запроса был в URL, но значение скрыто.
Хешировать заменяет значение заданного ключа запроса первыми 4 байтами SHA-256 хэша значения, в нижнем регистре, в шестнадцатеричном формате. Полезно для маскировки значения, если оно конфиденциально, при этом можно заметить, имело ли каждый запрос разное значение.

Помечает поле для выполнения одного или нескольких действий по манипулированию значением заголовка HTTP Cookie. Чаще всего фильтруемым полем является request>headers>Cookie.

<field> cookie {
	delete  <name>
	replace <name> <replacement>
	hash    <name>
}

Доступные действия:

Удалить удаляет заданный куки по имени из заголовка.
Заменить заменяет значение заданного куки на замену. Полезно для вставки маркера маскировки; вы увидите, что куки был в заголовке, но значение скрыто.
Хешировать заменяет значение заданного куки первыми 4 байтами SHA-256 хэша значения, в нижнем регистре, в шестнадцатеричном формате. Полезно для маскировки значения, если оно конфиденциально, при этом можно заметить, имело ли каждый запрос разное значение.

Если для одного имени куки определено много действий, будет применено только первое.

regexp

Помечает поле для применения замены регулярного выражения во время кодирования. Если поле является массивом строк (например, заголовки HTTP), каждая строка в массиве имеет примененные замены.

<field> regexp <pattern> <replacement>

Язык регулярных выражений, используемый — RE2, включён в Go. Смотрите справочник по синтаксису RE2 и обзор синтаксиса Go regexp.

В строке замены группы захвата можно ссылаться с помощью ${group}, где group — это либо имя, либо номер группы захвата в выражении. Группа захвата 0 — это полное совпадение регулярного выражения, 1 — первая группа захвата, 2 — вторая группа захвата и так далее.

Хеш

Помечает поле для замены на первые 4 байта (8 шестнадцатеричных символов) SHA-256 хэша значения во время кодирования. Если поле — массив строк (например, заголовки HTTP), каждый элемент массива хешируется.

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

<field> hash

Добавить

Добавляет поле(я) ко всем записям журнала.

format append {
	fields {
		<field> <value>
	}
	<field> <value>
	wrap <encode_module> ...
}

Это наиболее полезно для добавления информации о экземпляре Caddy, генерирующем записи журнала, возможно, через переменную среды. Значения полей могут быть глобальными плейсхолдерами (например, {env.*}), но не плейсхолдерами на основе запроса из-за записи журналов вне контекста HTTP-запроса.

Блок fields можно опустить, и поля можно указать непосредственно внутри блока append.

Примеры

Включить логирование доступа в стандартный логикатор.

Другими словами, по умолчанию это ведёт логи в stderr, но это можно изменить, переконфигурировав default логикатор с помощью log глобального параметра:

example.com {
	log
}

Записать логи в файл (с автоматическим разворотом логов, который включен по умолчанию):

example.com {
	log {
		output file /var/log/access.log
	}
}

Настроить автоматический разворот логов:

example.com {
	log {
		output file /var/log/access.log {
			roll_size 1gb
			roll_keep 5
			roll_keep_for 720h
		}
	}
}

Удалить заголовок запроса User-Agent из логов:

example.com {
	log {
		format filter {
			request>headers>User-Agent delete
		}
	}
}

Замаскировать несколько чувствительных куки. (Обратите внимание, что некоторые чувствительные заголовки по умолчанию записываются со значениями по умолчанию; смотрите log_credentials глобальный параметр для включения ведения журнала значений заголовка Cookie):

example.com {
	log {
		format filter {
			request>headers>Cookie cookie {
				replace session REDACTED
				delete secret
			}
		}
	}
}

Маскировать адрес удалённого компьютера из запроса, сохраняя первые 16 битов (т.е. 255.255.0.0) для IPv4-адресов и первые 32 бита для IPv6-адресов.

Обратите внимание, что начиная с Caddy v2.7, оба remote_ip и client_ip записываются, где client_ip — это "настоящий IP", когда trusted_proxies настроен:

example.com {
	log {
		format filter {
			request>remote_ip ip_mask 16 32
			request>client_ip ip_mask 16 32
		}
	}
}

Добавить идентификатор сервера из переменной среды ко всем записям журнала и связать его с filter для удаления заголовка:

example.com {
	log {
		format append {
			server_id {env.SERVER_ID}
			wrap filter {
				request>headers>Cookie delete
			}
		}
	}
}

Чтобы писать отдельные файлы логов для каждого поддомена в блоке сайта с подстановкой звёздочек wildcard site block, переопределяя hostnames для каждого логикатора. Это использует snippet для избежания повторения:

(subdomain-log) {
	log {
		hostnames {args[0]}
		output file /var/log/{args[0]}.log
	}
}
*.example.com {
	import subdomain-log foo.example.com
	@foo host foo.example.com
	handle @foo {
		respond "foo"
	}
	import subdomain-log bar.example.com
	@bar host bar.example.com
	handle @bar {
		respond "bar"
	}
}

Чтобы записать логи доступа для определённого поддомена в два разных файла с различными форматами (один с transform-encoder плагином, а другой с json).

Это работает путём переопределения имени логикатора как foo в блоке сайта, а затем включения логов доступа, созданных этим логикатором, в два логикатора в глобальных параметрах с include http.log.access.foo:

{
	log access-formatted {
		include http.log.access.foo
		output file /var/log/access-foo.log
		format transform "{common_log}"
	}
	log access-json {
		include http.log.access.foo
		output file /var/log/access-foo.json
		format json
	}
}
foo.example.com {
	log foo
}

© 2015-2025 Matthew Holt and The Caddy Authors
Licensed under the Apache License 2.0.
Caddy is a registered trademark of Stack Holdings GmbH.
https://caddyserver.com/docs/caddyfile/directives/log