Интеграция без мониторинга — это бомба замедленного действия: она молчит, пока заказы не перестают доходить до 1С. Логи и наблюдаемость превращают чёрный ящик обмена в управляемую систему. Разбираем, что и как логировать в 1С-Битрикс, как ловить сбои вебхуков и REST и не утопить сервер в записях.
Почему без логов интеграция слепа
Обмен через REST и вебхуки асинхронен и распределён: часть работает на стороне Битрикса, часть — на внешнем сервисе. Когда что-то ломается, без логов вы не ответите на три вопроса: что отправили, что получили в ответ и почему запись не появилась.
Типичная картина без наблюдаемости: менеджер жалуется, что заказы не попадают в CRM, а разработчик не может даже понять, доходил ли вебхук. С логами это вопрос одного запроса к таблице.
- Диагностика — быстро найти причину сбоя.
- Аудит — кто и когда менял данные через интеграцию.
- Разбор инцидентов — восстановить хронологию по логам.
Что именно логировать
Лог должен давать полную картину обмена, но не превращаться в свалку. Минимальный набор полей на каждую операцию:
| Поле | Назначение |
|---|---|
| Временная метка | Когда произошло событие |
| Направление | Входящий / исходящий |
| Метод / событие | Например, crm.deal.add или ONCRMDEALUPDATE |
| Внешний ID | Связь с сущностью на другой стороне |
| Статус | Успех / ошибка / повтор |
| Тело запроса и ответа | Для разбора инцидентов |
| Correlation ID | Сквозная трассировка одной операции |
Инструменты логирования в Битриксе
В 1С-Битрикс есть несколько встроенных механизмов, которые не нужно изобретать заново.
- Журнал событий (
Настройки → Инструменты → Журнал событий) — для аудита действий и системных ошибок. Подходит для редких важных событий. - Функция
AddMessage2Log()— быстрый способ писать в системный лог из своего кода обработчика. - Модуль
bitrix:monitoringи внешние сборщики — для агрегации. - Своя таблица лога на Highload-блоке или в отдельной таблице — для интенсивного обмена, где журнал событий будет узким местом.
Для нагруженных интеграций правильнее вести отдельное хранилище логов, а не забивать штатный журнал: он не рассчитан на тысячи записей в час и замедлит админку.
Обработка сбоев: ретраи и очереди
Лог фиксирует проблему, но систему спасает механика восстановления. Внешний сервис может быть недоступен, REST — вернуть ошибку rate limit. Что с этим делать:
- Ретраи с задержкой. Повторяйте неуспешный запрос с нарастающим интервалом (экспоненциальный backoff), а не в цикле подряд.
- Очередь. События кладите в очередь и обрабатывайте отдельным агентом или воркером — так пик нагрузки не теряется.
- Dead letter. Сообщения, не прошедшие после N попыток, откладывайте в отдельную «мёртвую» очередь для ручного разбора.
- Идемпотентность. Ретрай не должен создавать дубль — проверяйте по внешнему ключу перед повторной записью.
В Битриксе фоновую обработку удобно повесить на агент (CAgent) или на очередь через pull/внешний брокер для интенсивных потоков.
Алерты и метрики
Лог, в который никто не смотрит, бесполезен. Нужны активные уведомления и метрики, которые показывают здоровье обмена.
- Алерт на ошибки. При появлении ошибки — сообщение в Telegram или на почту ответственному. Порог: не на каждую, а на всплеск.
- Метрика «тишины». Если за ожидаемый интервал не пришло ни одного события — это тоже инцидент. Молчание опаснее ошибки.
- Доля ошибок. Процент неуспешных операций от общего числа — ранний индикатор деградации.
- Лаг обработки. Задержка между событием и его обработкой показывает, не растёт ли очередь.
Хранение и ротация логов
Логи растут быстро и способны положить базу данных. Нужна политика хранения.
| Тип лога | Срок хранения | Где хранить |
|---|---|---|
| Полное тело запросов | 7–30 дней | Отдельная таблица / файлы |
| Сводные метрики | Долго | Агрегаты, счётчики |
| Ошибки и инциденты | Дольше обычного | Отдельный журнал |
- Настройте ротацию — удаление или архивацию старых записей по расписанию (агент очистки).
- Тяжёлые тела запросов выносите в файлы или объектное хранилище, в БД держите только ссылку.
- Разделяйте «горячий» короткий лог для разбора и «холодные» агрегаты для аналитики.
Итог
Мониторинг интеграции — это не роскошь, а часть самой интеграции. Логируйте направление, метод, внешний ID, статус и correlation ID; ловите сбои ретраями и очередью; настройте алерты не только на ошибки, но и на подозрительную тишину; и держите логи под контролем через ротацию, чтобы не перегрузить базу.
Мы в B2Bsite закладываем наблюдаемость в обмен с самого старта: сквозная трассировка, dead letter для неотправленного, дашборды доли ошибок и лага. В результате сбой виден команде раньше, чем его успевает заметить клиент, а разбор инцидента занимает минуты, а не дни.
Частые вопросы
Хватит ли штатного журнала событий Битрикса для логов интеграции?
Для редких важных событий и аудита — да. Для интенсивного обмена он станет узким местом и замедлит админку, поэтому логи лучше вести в отдельной таблице или на Highload-блоке.
Что такое correlation ID и зачем он нужен?
Это сквозной идентификатор одной операции, который проходит через все шаги обмена. По нему в логах разных систем можно собрать полную хронологию одной заявки или заказа.
Как правильно повторять неуспешные запросы?
С нарастающей задержкой между попытками (экспоненциальный backoff), а не подряд в цикле. После нескольких неудач сообщение откладывают в отдельную очередь для ручного разбора.
Можно ли писать в лог тело запроса с персональными данными?
Полные персональные данные, токены и номера карт нужно маскировать. Иначе лог сам становится каналом утечки и нарушает требования к защите данных.
Почему тишина в обмене опаснее ошибки?
Ошибка видна и вызывает алерт, а остановившийся обмен молчит. Заказы просто перестают доходить, и без watchdog на отсутствие событий проблему замечают только по жалобам.
Как не дать логам переполнить базу данных?
Настройте ротацию: удаляйте или архивируйте старые записи по расписанию агентом. Тяжёлые тела запросов выносите в файлы, а в БД оставляйте ссылку и сводные метрики.
Как отслеживать здоровье интеграции без ручного просмотра логов?
Настройте метрики — долю ошибок, лаг обработки и число событий за интервал — и алерты на их отклонения. Так о деградации вы узнаёте автоматически, а не листая журнал.
Где в Битриксе запускать фоновую обработку очереди?
Для умеренных потоков подходит агент CAgent на расписании. Для интенсивного обмена лучше внешний брокер очередей и отдельный воркер, чтобы пики не терялись.
Поможем с настройкой и поддержкой Интеграции и связки систем
Поможем с настройкой, доработкой и поддержкой Интеграции и связки систем.