Demo
Demo
База знаний PMTA›Блок <acct-file>›Директива§ 3.3.11.12

record-fields

<acct-file>критичноХаб задаёт сам

Какие поля попадают в записи выбранного вида
в конфигурации это строкаrecord-fields all fields for each selected typeвнутри блока <acct-file>
Колонки, которых потом не восстановить

Строка задаёт набор колонок для одного вида записей, и пишется отдельно для каждого вида. Умолчание — *.

Звёздочка — не «все поля», а набор по умолчанию. Описание директивы говорит «all», но таблицы полей уточняют: * даёт поля, помеченные звёздочкой. Время первой попытки, число повторов, шифрование и прокси в него не входят — их называют явно.

Язык списка простой и стоит запомнить целиком:

Запись Значит
* поля по умолчанию для этого вида
timeLogged,orig,rcpt только перечисленные
*,!orcpt поля по умолчанию, кроме указанного
*,header_Message-Id поля по умолчанию плюс заголовок письма

Произвольный заголовок — это header_ИМЯ. Так в учёт попадает всё, что вы сами проставили в письме: идентификатор рассылки, идентификатор получателя в вашей базе, что угодно. Это единственный способ связать запись учёта со своей стороной.

Не выбранное поле не восстановить. Внизу по потоку оно даст не ошибку, а пустоту, и никакая обработка его не вернёт.

Часть полей открывается другими строками. Время первой попытки появляется только при track-time-first-attempt; текст user-string — только если перечислить поле userString.

Главная ловушка — сузить список ради размера файла. Экономия выходит небольшая: строки учёта короткие, а на диске всё равно доминируют временные ошибки, если их не вынесли отдельно. Цена же — навсегда потерянная возможность ответить на вопрос, которого пока не задали.
Что делает Хаб. Пишет — в обоих блоках учёта. Основа у каждого вида — звёздочка, стандартный набор полей. К доставкам и отказам (d, b) добавлены timeFirstAttempt, totalSecondsQueued и numRetries: в звёздочку они не входят (§ 12.2.1), а без них не посчитать, где уходит время доставки. К жалобам в блоке телеметрии добавлен header_feedback-id — заголовок с идентификатором жалобы.

Выбор осознанный: узкий набор экономил бы немного, а вопросы к телеметрии со временем прибавляются. Разбирает пачку наш приёмник, и лишние поля ему ничего не стоят.

Рекомендуемые значения

Начинать стоит со звёздочки и сужать только по измеренной причине:

Значение Когда
* (умолчание) почти всегда
*,header_ИМЯ нужна связка со своей базой
*,!поле одно поле мешает — например, длинное
перечисление внешнее требование к составу данных

У каждого вида записей свой список — строка повторяется по одной на вид.

Звёздочка по умолчанию, её смысл по таблицам полей, исключения и header_XXX — из руководства (§ 3.3.11.12, § 12.2.1–12.2.7). Разбор нашего выбора — по коду Хаба.
Пример в конфигурации
# набор по умолчанию у каждого вида, плюс заголовок жалобы у feedback-loop
<acct-file /var/log/pmta/mtahub-webhook.json>
    records d, b, rb, t, feedback-loop
    record-fields d  *    record-fields b  *
    record-fields f  *,header_feedback-id
</acct-file>
Строка пишется по одной на вид записей. Заголовок письма попадает в учёт только так — перечислением header_ИМЯ.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

Типичные ошибки и проблемы

что делают не так и чем это кончается3 ошибки▶

Сужают набор полей и обнаруживают потерю через месяц

наш опыт

Чем чреватоВнизу по потоку не выбранное поле даёт пустоту, а не ошибку. Замечают это тогда, когда впервые понадобилось ответить на вопрос с его участием, — и прошлые записи уже не восстановить.
Как заметитьВ аналитике колонка есть, а значений в ней нет ни у одной записи.
Как правильноВозвращать * и сужать только по требованию, а не ради экономии.

Ждут заголовок письма в учёте без явного перечисления

§ 3.3.11.12

Чем чреватоЗвёздочка означает все стандартные поля вида. Заголовки письма в неё не входят и добавляются только записью header_ИМЯ.
Как заметитьЗаголовок в письме есть, в учёте его нет.
Как правильноДописать *,header_ИМЯ для нужного вида записей.

Пишут одну строку на все виды записей

наш опыт

Чем чреватоСтрока относится к одному виду, названному первым словом. Виды, для которых её не написали, берут умолчание — и это работает, но выглядит как настройка, которой нет.
Как заметитьНабор полей задан «для всех», а в файле у разных видов он разный.
Как правильноПисать по строке на вид либо сознательно опираться на умолчание.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
record-fields <field-list>
Значения
список полей через запятую; * — все, ! — исключить, header_ИМЯ — заголовок письма
Умолчание
all fields for each selected type § 3.3.11.12
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<acct-file>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строка живёт внутри своего <acct-file> и относится к одному виду записей в нём. Разные блоки учёта могут писать один и тот же вид с разным набором полей.
⇄

Связанные директивы

4 связи

Без чего не работает

records<acct-file>Колонки задаются для вида записей, выбранного той строкой. § 3.3.11.12

Зависит от

track-time-first-attemptGlobalОткрывает поле времени первой попытки; без него его нечего перечислять. § 3.3.1.41

Работают в паре

map-header-to-field<acct-file>Дополняет: та строка кладёт в готовое поле содержимое заголовка письма. § 3.3.11.10

Где применяется

Договор о телеметрииВторая из двух строк, задающих, что попадёт в учёт. § 3.3.11.12

Сюда ссылаются

user-string<acct-file>Строка попадёт в файл, только если поле userstring перечислено там. § 3.3.11.8

Как проверить на узле
Для файла CSV состав колонок виден в заголовке — первой строке файла:
head -1 "$(ls -t /var/log/pmta/acct-*.csv | head -1)"
Для формата JSON поля видны в любой записи: head -1 файл.json. Если ожидаемого поля нет, проверьте две вещи — перечислено ли оно здесь и не требует ли оно отдельной строки, как время первой попытки.
◇

Что ещё почитать

3 статьи

◇Что узел рассказывает о себе и по каким каналамСемь поверхностей наблюдения: веб-монитор, консоль в четырёх форматах, журнал, учёт, поиск по учёту, метрики и выгрузка во внешнюю аналитику.◇Договор о телеметрииОдин блок описывает выход учёта целиком: какие виды записей, какие поля, куда они идут, как сменяются файлы и что обезличивается.◇Как устроена запись учётаКак устроена запись учёта: вид записи в первом столбце, дальше поля, состав которых настраивается.

В Хабе
Значение
Хаб подбирает сам — темп, стадия прогрева, метрики
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Разобраться с доставляемостью · Собрать телеметрию
Важность
критично
Соседние настройки блока <acct-file>:recordsiso-timessyncmap-header-to-fieldmove-toВсе 26 директив блока →