מדוע יומן האירועים הסטנדרטי אינו מספיק
אינטגרציה מפסיקה לעבוד. נתונים לא מגיעים ממערכת חיצונית, עסקאות לא מתעדכנות, ה-webhook נשאר שקט. מפתח שואל, "האם הבקשה בכלל הגיעה לשרת?"—ואין תשובה כי אין יומנים. ללא תיעוד בקשות API, ניפוי באגים באינטגרציה הופך לניחוש. נתקלנו בזה עשרות פעמים. המהנדסים שלנו מציעים תיעוד בקשות API מוכן: proxy logger, middleware, ניטור והתראות. אנו מעריכים את הפרויקט שלך תוך יום אחד ומבטיחים ניפוי באגים שקוף. אתה צריך לראות: איזו בקשה נכנסה, עם אילו פרמטרים, מה Bitrix24 החזיר, וכמה זמן לקחה התשובה. רק כך ניתן לאתר את הבעיה—בין אם היא בצד של Bitrix24, בצד האינטגרציה או ברשת. גישה זו מקצרת את זמן האבחון משעות לדקות.
המגבלות של יומן האירועים המובנה
היומן אירועים המובנה (הגדרות → כלים → יומן אירועים) מתעד אירועי מערכת: התחברויות, שינויי תצורה, שגיאות מודולים. עבור בקשות API, הוא לוכד:
- שגיאות REST API —
QUERY_LIMIT_EXCEEDED,ACCESS_DENIED,INVALID_TOKEN - התקנה והסרה של יישומים
- הפעלת מטפלי אירועים
מגבלה: יומן האירועים אינו מתעד קריאות API מוצלחות—רק שגיאות ואירועי מערכת. לתיעוד מלא, נדרשים כלים נוספים.
תיעוד Webhooks נכנסים ויוצאים
Webhooks הם שיטת האינטגרציה הפופולרית ביותר, והקשה ביותר לניפוי באגים. Webhooks נכנסים (כתובות URL שקוראות ל-Bitrix24 מבחוץ) אינם מתועדים כברירת מחדל. Webhooks יוצאים (Bitrix24 קורא לכתובת URL חיצונית באירוע) מתועדים ביומן תהליכים עסקיים רק אם הופעלו מתוך BP.
עבור webhooks נכנסים, הפתרון הוא בצד האינטגרציה:
- Proxy logger — שירות מתווך בין המערכת החיצונית ל-Bitrix24. כל הבקשות עוברות דרך ה-proxy, אשר מתעד את גוף הבקשה, כותרות, תשובת Bitrix24 וזמן הביצוע. ניתן ליישם אותו על nginx (יומן גישה + תיעוד גוף בקשה) או ברמת היישום. proxy logger מספק 90% יותר מידע מאשר יומן האירועים.
- Middleware ביישום — אם האינטגרציה כתובה ב-PHP, Node.js או Python, הוסף middleware שמתעד כל בקשה יוצאת ל-API של Bitrix24 לקובץ או למסד נתונים.
עבור יישומי שרת (OAuth) ב-Bitrix24 Marketplace, קיים סעיף "מפתחים → יומן קריאות REST API" המציג ספירות קריאות, שגיאות וסטטיסטיקות מתודות. הוא זמין רק עבור יישומים שפורסמו.
עבור יישומים מותאמים אישית (לא מה-marketplace), אנו ממליצים על תיעוד ברמת לקוח ה-HTTP:
| מה לתעד | דוגמה |
|---|---|
| מתודת API | crm.deal.update |
| פרמטרים | {id: 123, fields: {STAGE_ID: "WON"}} |
| סטטוס HTTP | 200, 503 |
| גוף התשובה | {result: true} או {error: "..."} |
| זמן הבקשה | 2023-10-01T12:00:00Z |
| משך זמן | 340 ms |
השוואת שיטות תיעוד
| שיטה | רמת פירוט | מורכבות | המלצה |
|---|---|---|---|
| יומן אירועים | שגיאות בלבד | נמוכה | אבחון מהיר |
| Proxy logger | מלא | בינונית | Webhooks נכנסים |
| Middleware | מלא | בינונית | יישומי שרת |
| יומן קריאות REST API | סטטיסטיקות | נמוכה | יישומי Marketplace |
ניטור והתראות
יומנים שימושיים רק כאשר מנתחים אותם. המלצות:
-
מונה שגיאות — עקוב אחר מספר שגיאות ה-API בשעה האחרונה. עלייה ב-
QUERY_LIMIT_EXCEEDEDמצביעה על חריגה ממגבלות. עלייה ב-ACCESS_DENIEDמרמזת על פקיעת token. - זמן תגובה — אם זמן התגובה הממוצע קופץ מ-200 אלפיות שנייה ל-2 שניות, הבעיה ככל הנראה בצד של Bitrix24 (עומס, תחזוקה).
- התראות — שלח הודעות דרך Telegram/דוא"ל כאשר: מתרחשות 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 } מה כלול בשירות שלנו
- התקנת proxy logger עבור webhooks נכנסים: תיעוד בקשות ותשובות
- תיעוד middleware עבור יישומי שרת (PHP, Node.js, Python)
- יומנים מובנים: מתודה, פרמטרים, סטטוס, זמן, משך זמן
- חיבור יומנים למערכת ניטור (ELK, Loki, Grafana)
- התראות על שגיאות API, חריגות ממגבלות, timeouts
- מדיניות סיבוב יומנים ושמירה
- תיעוד והדרכת צוות
התהליך שלנו ולוחות זמנים
- איסוף נתונים — הבנת זרימת האינטגרציה שלך וצרכי התיעוד.
- ניתוח — זיהוי כל נקודות קריאת ה-API (webhooks נכנסים, בקשות יוצאות, משימות מתוזמנות).
- עיצוב — בחירת הכלים המתאימים (proxy logger, middleware, או שניהם).
- הערכה — מתן מחיר קבוע בהתאם למורכבות.
- יישום — פריסת תשתית התיעוד.
- בדיקות — אימות שכל הקריאות מתועדות כראוי.
- השקה — עלייה לאוויר עם ניטור והתראות.
לוחות זמנים:
- תיעוד בסיסי (proxy logger או middleware): 1–2 ימים
- עם ניטור והתראות: עד 3 ימים
מקרה אמיתי: קיצור זמן הניפוי ב-90%
בפרויקט אחרון עם אינטגרציית CRM בעלת תעבורה גבוהה, הלקוח בילה עד 8 שעות בניפוי באגים של webhooks שנכשלו. לאחר יישום proxy logger עם יומנים מובנים ולוחות מחוונים של Grafana, הם יכלו לזהות בעיות תוך פחות מ-15 דקות. המפתח היה לראות את מטען הבקשה בפועל ואת התשובה זה לצד זה. זה קיצר את הזמן הממוצע לפתרון תקלות אינטגרציה משעות לדקות.
עם ניסיון של למעלה מ-10 שנים ב-Bitrix24, אנו מבטיחים מערכת תיעוד שקופה וניתנת לתחזוקה. צור קשר כדי לדון בפרויקט שלך ולקבל ייעוץ תוך 24 שעות.