Настройка логирования API-запросов Битрикс24
Интеграция перестала работать. Данные не приходят из внешней системы, сделки не обновляются, вебхук молчит. Разработчик спрашивает: «А запрос вообще дошёл?» — и ответа нет, потому что логов нет. Без логирования API-запросов отладка интеграции — это гадание. Нужно видеть: какой запрос пришёл, с какими параметрами, что вернул Б24, сколько времени занял ответ. Только тогда можно понять, где проблема — на стороне Б24, интеграции или сети.
Журнал событий Битрикс24
Встроенный инструмент логирования — Журнал событий (Настройки → Инструменты → Журнал событий). Он фиксирует системные события: авторизации, изменения настроек, ошибки модулей. Для API-запросов журнал фиксирует:
- Ошибки REST API —
QUERY_LIMIT_EXCEEDED,ACCESS_DENIED,INVALID_TOKEN - Установку и удаление приложений
- Срабатывание событий (event handlers)
Ограничение: журнал событий не логирует успешные API-вызовы — только ошибки и системные события. Для полного логирования нужны дополнительные инструменты.
Логирование вебхуков
Вебхуки — самый популярный способ интеграции, и самый сложный для отладки. Входящий вебхук (URL для вызова Б24 извне) не логирует вызовы по умолчанию. Исходящий вебхук (Б24 вызывает внешний URL при событии) логирует результат в журнале бизнес-процессов, если вебхук вызывается из БП.
Для логирования входящих вебхуков решение на стороне интеграции:
- Прокси-логгер — промежуточный сервис между внешней системой и Б24. Все запросы проходят через прокси, который записывает тело запроса, заголовки, ответ Б24 и время выполнения. Можно реализовать на nginx (access log + request body logging) или на уровне приложения.
- Middleware в приложении — если интеграция написана на PHP/Node.js/Python, добавляется middleware, который логирует каждый исходящий запрос к API Б24 в файл или в БД.
Логирование REST API (серверные приложения)
Для серверных приложений (OAuth) в маркетплейсе Б24 есть раздел Разработчикам → Журнал вызовов REST API — показывает количество вызовов, ошибки, статистику по методам. Доступен только для опубликованных приложений.
Для собственных приложений (не из маркетплейса) рекомендуется реализовать логирование на уровне HTTP-клиента:
| Что логировать | Пример |
|---|---|
| Метод API | crm.deal.update |
| Параметры | {id: 123, fields: {STAGE_ID: "WON"}} |
| HTTP-статус ответа | 200, 503 |
| Тело ответа | {result: true} или {error: "..."} |
| Время запроса | 2024-01-15 14:32:07 |
| Длительность | 340 ms |
Мониторинг и алерты
Логи полезны, когда их анализируют. Рекомендации:
-
Счётчик ошибок — отслеживать количество ошибок API за последний час. Рост ошибок
QUERY_LIMIT_EXCEEDED— сигнал о превышении лимитов. РостACCESS_DENIED— возможно, протухли токены. - Время ответа — если среднее время ответа API выросло с 200 мс до 2 с — проблема на стороне Б24 (нагрузка, обслуживание).
- Алерты — уведомление в Telegram/email при: 5+ ошибок подряд, 0 успешных вызовов за последние 30 минут, суточный лимит исчерпан на 80%.
Для централизованного сбора логов используется ELK (Elasticsearch + Logstash + Kibana) или Grafana Loki. Логи из middleware отправляются в систему, где строятся дашборды и настраиваются алерты.
Что настраиваем
- Прокси-логгер для входящих вебхуков: запись запросов и ответов
- Middleware логирования для серверных приложений (PHP/Node.js/Python)
- Структура логов: метод, параметры, статус, время, длительность
- Подключение логов к системе мониторинга (ELK, Loki, Grafana)
- Алерты на ошибки API, превышение лимитов, таймауты
- Ротация логов и политика хранения