Уявіть: ви запустили парсинг каталогу з 10 000 товарів, через годину дивитеся — імпортувалося всього 300. Без логів — гадання: чи джерело повернуло порожню сторінку, чи XPath зламався, чи ліміт пам'яті PHP закінчився на 50 000-му товарі. З логами — одразу бачите, що на 501-му товарі впав memory limit за 128 МБ. Налаштування структурованого логування — не розкіш, а необхідність для будь-якого проєкту з автонаповненням. Наш досвід показує, що правильна конфігурація скорочує час розбору інциденту з годин до хвилин. На одному проєкті ми прискорили пошук помилок у 6 разів, впровадивши єдиний формат з контекстом і ротацією. Розберемо, як організувати логи так, щоб не витрачати час на гадання.
"Без контексту логи — це шум. Ми перестали гадати, коли додали контекст у кожен виклик." — Іван, провідний розробник проєкту з 5000+ сутностей.
Рівні логування
Використовуйте стандартні рівні PSR-3, навіть якщо не підключаєте Monolog. Рівні керують обсягом інформації, що записується:
- DEBUG — кожен HTTP-запит до джерела, час відповіді, розмір body. Вмикається лише під час налагодження через прапорець в адмінці.
- INFO — старт/стоп парсера, кількість оброблених елементів, кількість створених/оновлених записів в інфоблоці.
- WARNING — пропущений елемент (не пройшов валідацію), повільна відповідь джерела (>5 сек), повторна спроба запиту.
- ERROR — виняток під час парсингу, помилка запису в b_iblock_element, невалідна відповідь API.
У продакшні тримайте рівень INFO. Перемикання на DEBUG — через налаштування в b_option або файл /local/parser_debug.flag, без перезапуску та деплою. Ця гнучкість дозволяє безпечно діагностувати проблеми на живому проєкті.
Куди писати логи: файл, b_event_log чи кастомна таблиця?
Вибір сховища залежить від інтенсивності парсингу та вимог до аналітики. Порівняємо варіанти:
| Критерій | Файлова система | b_event_log | Кастомна таблиця |
|---|---|---|---|
| Простота інтеграції | Висока (fopen) | Середня (API Бітрікс) | Низька (міграція) |
| Продуктивність при 1000 записів/хв | Відмінно | Погано (гальмує) | Добре |
| Пошук і фільтрація | grep/awk | Адмінка | SQL-запити |
| Ротація | logrotate | Не потрібна | Налаштовується |
| Аналітичні звіти | Скриптами | Обмежено | Будь-які |
Файлова система. Пишемо в /local/logs/parser/YYYY-MM-DD.log. Формат рядка: [2024-03-15 14:23:01] INFO | source=competitor_a | action=update | iblock_id=12 | element_id=45678 | duration=0.34s. Кожен рядок — одна подія. Роздільник | зручний для grep і awk. Обов'язкові поля: timestamp, level, source, action. Ротація — через logrotate або власний агент, що видаляє файли старші 30 днів. Без ротації логи DEBUG-рівня за тиждень легко займуть гігабайти.
Таблиця b_event_log. Штатний журнал Бітрікс. Виклик CEventLog::Add() з параметрами. Плюс — перегляд через адмінку, фільтрація, доступ для менеджерів без SSH. Мінус — таблиця не розрахована на тисячі записів за хвилину, при інтенсивному парсингу гальмує. Тому b_event_log використовуйте для WARNING і ERROR, а DEBUG пишіть у файл.
Кастомна таблиця. Створюємо таблицю parser_log з полями id, created_at, level, source, action, element_id, message, context (JSON). Індекс по (created_at, level, source). Це оптимальний варіант для проєктів, де парсер — критична підсистема, і потрібні аналітичні запити по логах. Наприклад, можна швидко порахувати кількість помилок за джерелами за останню годину.
Що важливіше: рівень чи контекст?
Рядок «Помилка парсингу» марний. Корисний рядок: «XPath //div[@class="price"]/span повернув 0 вузлів, очікувалося 1, URL: https://source.com/product/123, HTTP 200, body size: 45KB». Контекст дозволяє відтворити проблему без повторного запуску. Мінімальний контекст для кожного рівня:
| Рівень | Обов'язковий контекст |
|---|---|
| DEBUG | URL, HTTP-код, час відповіді, розмір body, User-Agent |
| INFO | Джерело, дія, ID елемента інфоблоку, результат (created/updated/skipped) |
| WARNING | Джерело, URL, причина пропуску, значення поля, очікуваний формат |
| ERROR | Все вище плюс stack trace, memory_get_peak_usage(), вміст $arFields |
Як налаштувати клас ParserLogger?
Створіть клас ParserLogger у /local/php_interface/classes/ (або в просторі імен вашого модуля). Інтерфейс:
ParserLogger::info('import', [ 'source' => 'competitor_a', 'element_id' => 45678, 'action' => 'update', 'fields_changed' => ['PRICE', 'QUANTITY'], ]); Всередині — запис у файл + у b_event_log для рівнів WARNING і вище. Перемикання рівня — через COption::GetOptionString('parser', 'log_level', 'INFO'). Цей підхід дає єдину точку конфігурації.
Покрокова інструкція з впровадження ParserLogger
- Створіть файл
/local/php_interface/classes/ParserLogger.phpз namespaceBitrix\Parser. - Реалізуйте методи debug(), info(), warning(), error() з сигнатурою
function (string $action, array $context = []). - У кожному методі формуйте рядок логу і пишіть у файл через
error_logз прапоромFILE_APPEND. - Для WARNING і ERROR додатково викликайте
CEventLog::Add(). - Додайте метод
setLevel($level), що читає з COption. - Автозавантаження класу пропишіть у
init.php.
Як моніторити помилки автоматично?
Логи самі по собі не допоможуть, якщо їх ніхто не читає. Додайте агент, що запускається кожні 15 хвилин, який рахує кількість ERROR-записів за період. Якщо поріг перевищено, надсилайте сповіщення (поштова подія або Telegram). Це перетворює логування з пасивного інструменту на активну систему моніторингу. На практиці ми бачили, як такий агент допоміг запобігти простою інтернет-магазину: помилка через зміну структури HTML на сайті джерела була помічена через 3 хвилини, а не через 3 години.
Що входить у налаштування логування під ключ
Ми пропонуємо комплексне налаштування логування для вашого проєкту:
- Клас
ParserLoggerз рівнями DEBUG/INFO/WARNING/ERROR і автоматичним записом у файл і b_event_log. - Файлові логи з ротацією в
/local/logs/parser/(зберігання 30 днів). - Можливість перемикання рівня через адмінку без деплою.
- Агент моніторингу помилок зі сповіщеннями.
- Документація з використання та інструкція для команди.
Ми працюємо з Бітріксом більше 10 років, реалізували 50+ проєктів з автонаповненням та інтеграцією 1С. Гарантуємо, що після налаштування ви зможете розбирати будь-яку помилку парсера за хвилини. Оцінимо ваш проєкт безкоштовно — зв'яжіться, щоб обговорити деталі. Замовте налаштування логування під ключ і економте години на налагодженні.