Налаштування логування API-запитів Bitrix24
Інтеграція перестала працювати. Дані не приходять із зовнішної системи, угоди не оновлюються, вебхук мовчить. Розробник запитує: «А запит взагалі дійшов?» — і відповіді немає, тому що логів немає. Без логування API-запитів відладка інтеграції — це гадання. Потрібно бачити: який запит прийшов, з якими параметрами, що повернув Б24, скільки часу зайняв ответ. Тільки тоді можна зрозуміти, де проблема — на стороні Б24, інтеграції або мережі.
Журнал подій Bitrix24
Вбудований інструмент логування — Журнал подій (Параметри → Інструменти → Журнал подій). Він фіксує системні события: авторизації, зміни параметрів, помилки модулів. Для API-запитів журнал фіксує:
- Помилки REST API —
QUERY_LIMIT_EXCEEDED,ACCESS_DENIED,INVALID_TOKEN - Установку та видалення додатків
- Запуск обробників подій (event handlers)
Обмеження: журнал подій не логує успішні API-виклики — тільки помилки та системні события. Для повного логування потрібні додаткові інструменти.
Логування вебхуків
Вебхуки — найпоширеніший спосіб інтеграції, і найскладніший для відладки. Вхідний вебхук (URL для виклику Б24 зовні) не логує виклики за замовчуванням. Вихідний вебхук (Б24 викликає зовнішній URL при события) логує результат у журналі бізнес-процесів, якщо вебхук викликається з BP.
Для логування вхідних вебхуків рішення на стороні інтеграції:
- Прокси-логгер — проміжний сервіс між зовнішньою системою та Б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, перевищення лімітів, таймаути
- Ротація логів та політика зберігання