Чому стандартного журналу подій недостатньо?
Інтеграція перестала працювати. Дані не надходять із зовнішньої системи, угоди не оновлюються, вебхук мовчить. Розробник питає: «А запит взагалі дійшов?» — і відповіді немає, тому що логів немає. Без логування 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 у файл або в БД.
Наприклад, на одному з проектів ми виявили, що вебхук не приходив через помилку SSL-сертифіката, яку можна було відловити лише за допомогою проксі-логгера. Це заощадило клієнту дні простою.
Для серверних застосунків (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 годин.