Почему стандартного журнала событий недостаточно?
Интеграция перестала работать. Данные не приходят из внешней системы, сделки не обновляются, вебхук молчит. Разработчик спрашивает: «А запрос вообще дошёл?» — и ответа нет, потому что логов нет. Без логирования API-запросов отладка интеграции — это гадание. Мы сталкивались с этим десятки раз. Наши инженеры предлагают настройку логирования API-запросов под ключ: прокси-логгер, middleware, мониторинг и алерты. Оценим проект за 1 день и гарантируем прозрачную отладку. Нужно видеть: какой запрос пришёл, с какими параметрами, что вернул Б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) или на уровне приложения. Прокси-логгер даёт на 90% больше информации, чем журнал событий.
- Middleware в приложении — если интеграция написана на PHP/Node.js/Python, добавляется middleware, который логирует каждый исходящий запрос к API Б24 в файл или в БД.
Для серверных приложений (OAuth) в маркетплейсе Б24 есть раздел «Разработчикам → Журнал вызовов REST API» — показывает количество вызовов, ошибки, статистику по методам. Доступен только для опубликованных приложений.
Для собственных приложений (не из маркетплейса) рекомендуется реализовать логирование на уровне HTTP-клиента:
| Что логировать | Пример |
|---|---|
| Метод API | crm.deal.update |
| Параметры | {id: 123, fields: {STAGE_ID: "WON"}} |
| HTTP-статус ответа | 200, 503 |
| Тело ответа | {result: true} или {error: "..."} |
| Время запроса | 2023-10-01T12:00:00Z |
| Длительность | 340 ms |
Сравнение способов логирования
| Способ | Детализация | Сложность | Рекомендация |
|---|---|---|---|
| Журнал событий | Только ошибки | Низкая | Для быстрой диагностики |
| Прокси-логгер | Полная | Средняя | Для входящих вебхуков |
| Middleware | Полная | Средняя | Для серверных приложений |
| Журнал вызовов REST API | Статистика | Низкая | Для приложений из маркетплейса |
Мониторинг и алерты
Логи полезны, когда их анализируют. Рекомендации:
-
Счётчик ошибок — отслеживать количество ошибок API за последний час. Рост ошибок
QUERY_LIMIT_EXCEEDED— сигнал о превышении лимитов. РостACCESS_DENIED— возможно, протухли токены. - Время ответа — если среднее время ответа API выросло с 200 мс до 2 с — проблема на стороне Б24 (нагрузка, обслуживание).
- Алерты — уведомление в Telegram/email при: 5+ ошибок подряд, 0 успешных вызовов за последние 30 минут, суточный лимит исчерпан на 80%.
Для централизованного сбора логов используется ELK (Elasticsearch + Logstash + Kibana) или Grafana Loki. Логи из middleware отправляются в систему, где строятся дашборды и настраиваются алерты.
Пример структуры лога
{ "method": "crm.deal.get", "params": {"id": "123"}, "response": {"result": {}}, "time": "2023-10-01T12:00:00Z", "duration_ms": 340 } Что входит в работу
- Настройка прокси-логгера для входящих вебхуков: запись запросов и ответов
- Middleware логирования для серверных приложений (PHP/Node.js/Python)
- Структура логов: метод, параметры, статус, время, длительность
- Подключение логов к системе мониторинга (ELK, Loki, Grafana)
- Алерты на ошибки API, превышение лимитов, таймауты
- Ротация логов и политика хранения
- Документация и обучение команды
Наш 10-летний опыт с Битрикс24 гарантирует, что вы получите прозрачную и поддерживаемую систему логирования. Закажите настройку — и вы избавитесь от гаданий при отладке интеграций. Свяжитесь с нами, чтобы обсудить ваш проект. Получите консультацию в течение 24 часов.