Перейти к содержимому
BXWiki

Свой журнал решения - файл, ротация, что писать

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

Решение

Пишем в свой файл:

\Bitrix\Main\Diag\Debug::writeToFile(
    ['order' => $orderId, 'code' => $httpCode, 'ms' => $ms],
    date('Y-m-d H:i:s') . ' sync',
    '/local/logs/sync.log'
);
// свой файл, а не общий журнал ошибок: чужие записи не мешают разбору

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

Кладём в запись то, что нужно при разборе:

// что случилось, с чем именно, чем закончилось и сколько заняло
$line = sprintf("%s order=%s action=%s result=%s ms=%d",
    date('c'), $orderId, 'send', $ok ? 'ok' : 'fail:' . $error, $ms);
// по такой строке ищут grep-ом: заказ, действие, результат, время

Запись отвечает на вопрос «что и с чем случилось». Строка без номера заказа и без результата не помогает: она сообщает, что код работал, но не говорит, чем всё кончилось.

Не даём файлу вырасти:

/etc/logrotate.d/vendor-sync
/home/site/local/logs/*.log {
    daily
    rotate 14
    compress
    missingok
}

Файл журнала без ротации однажды съедает диск. Сначала он растёт незаметно, потом на нём падает база, и виноватым выглядит сайт, а не забытая настройка ротации.

Убираем из журнала лишнее:

$payload['token'] = '***';           // ключи в журнал не пишут никогда
unset($payload['phone'], $payload['email']);   // персональные данные тоже лишние
Debug::writeToFile($payload, 'request', '/local/logs/sync.log');
// на стенде эти же места удобнее смотреть пошаговым отладчиком

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

Уровни записей стоит завести с самого начала. Обычный ход обмена пишут коротко, а подробности - только при разборе: журнал, где каждая мелочь занимает десять строк, никто не читает.

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

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

Читать журнал стоит уметь до того, как он понадобится. Пара строк с командами поиска по номеру заказа и по результату, записанная рядом с решением, экономит полчаса в тот вечер, когда разбираться придётся кому-то другому.

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

В журнале записи, но разобрать сбой нечем.

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

На сервере кончилось место.

Файл журнала растёт месяцами без всякой ротации и без всякой регулярной чистки. Ротацию файлов настраивают вместе с самим журналом, а не годом позже него.

В журнале нашлись ключи от чужого сервиса.

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

Нужного запуска в журнале нет.

Журнал завели уже после сбоя, при разборе. Он окупается только тогда, когда пишется заранее.

Журнал невозможно читать глазами.

Каждая мелочь пишется подробно и занимает по десять строк в самом журнале. Подробности включают только на время разбора.

Частые вопросы

Чем свой журнал лучше штатного журнала событий?

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

Где хранить файлы журналов?

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

Сколько хранить записи?

Обычно две недели: этого хватает на разбор и не съедает диск. Важные события дублируют в свою таблицу.

Нужен ли журнал на стенде?

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

Смежное

Первоисточник