Sticky Notes Warmup – פתרון ביצועים משולב
===========================================

מבצע "Sticky Notes Warmup" מחולק לשני נדבכים משלימים: העלאת timeout מידית (מוכחת בשטח)
וחימום אינדקסים לפני שה-process מקבל תעבורה (שיפור קוד שעדיין נבחן). המסמך מרכז את כל
ההנחיות התפעוליות כך שהצוות ידע מה עובד ומה עדיין תחת מעקב.

רקע קצר
--------
- הנתיב `/api/sticky-notes/reminders/summary` נתקע כי `_ensure_indexes()` הופעל בכל בקשה
  וננעל על `_db_lock`.
- בהיעדר warmup, כל worker ניסה לבנות אינדקסים מחדש בעת בקשת משתמש והוביל ל-timeouts.

התרופה המיידית (מוכחת)
-----------------------
- העלאת timeout של Gunicorn ל־180 שניות פתרה מיד את התקיעות והחזירה את ה-WebApp להיות
  חד בכל הקלקה.
- זהו קו ההגנה הראשון, גם אם חימום האינדקסים נחשב "מאושר" בהמשך.

.. code-block:: bash

   export GUNICORN_CMD_ARGS="--timeout 180 --graceful-timeout 180"

Warmup מבני (עדיין בתהליך אימות)
---------------------------------
- בעת העלייה, אנחנו מפעילים warmup שמריץ את `_ensure_indexes()` פעם אחת (best-effort)
  ומסמן דגל גלובלי/Redis בשם ``sticky_notes_indexes_ready_v1``.
- ה-warmup רץ ברקע ולא אמור לחסום את השרת: ב-Wsgi/Flask הוא ירוץ ב-thread דמון, ואם הוא
  נקרא מתוך סביבת async עם event loop הוא ירוץ דרך executor כדי לא לתקוע את הלולאה.
- כל בקשה בודקת את הדגל ורק אם הוא חסר מפעילה שוב את החימום, כך שנמנעים מנעילה
  חוזרת על `_db_lock`.
- למרות שהקוד כבר נפרס, אין לנו עדיין נתוני פרודקשן שמוכיחים שהחימום לבדו מספיק,
  ולכן אסור להסיר את ה-timeout הנדיב.

איפוס הדגל בעת שינוי אינדקסים
------------------------------
1. עדכנתם אינדקס (שינוי שם, הוספה, הסרה) בקולקציית Sticky Notes? מחקו את המפתח.
2. אפשר להשתמש בפקודה:

   .. code-block:: bash

      redis-cli DEL sticky_notes_indexes_ready_v1

3. לחלופין, עדכנו את גרסת הדגל (למשל ``sticky_notes_indexes_ready_v2``) כדי לאלץ warmup.

מה לאמת לפני rollout מלא
--------------------------
- להריץ rollout קטן או בדיקת staging ולוודא שהאירוע ``sticky_indexes_warmup`` מופיע לכל worker
  עם ``stage=done`` ו-``duration_ms`` (אידאלית פעם אחת לכל process).
- אם אתם רואים ``stage=failed`` עם שגיאת DB (למשל אין חיבור למונגו בזמן עלייה) זה אומר שהחימום
  לא הצליח, אבל הוא עדיין נחשב best-effort ולא אמור להפיל את השרת — צריך לטפל בזמינות/הרשאות DB
  או להריץ ריטריי/rollout נוסף.
- למדוד latency אחרי ה-warmup ולוודא שלא חזרו timeouts.
- לתעד ב-Postmortem האם הבעיה נפתרה ע"י timeout, warmup או שניהם.

מה לעשות אם latency קופץ שוב
-----------------------------
- לבדוק שה-environment כולל את ההגדרה ``GUNICORN_CMD_ARGS`` מהקטע לעיל.
- לחפש בלוגים האירוע ``sticky_indexes_warmup``:

  - ``stage=done``: החימום הצליח (בדקו שזה לא חוזר בלולאה).
  - ``stage=failed``: החימום נכשל (לרוב DB לא זמין / הרשאות / timeout).
  - היעדר אירוע: יכול להעיד שהדגל כבר קיים (לא בוצע warmup) או שהקוד לא הופעל בסביבת העלייה.
- לאפס את ``sticky_notes_indexes_ready_v1`` ולפקח מחדש על הלוגים.

המלצה רשמית
------------
- לשלב את שני הפתרונות תמיד: Timeout נדיב מכסה cold start איטי, והחימום מוריד את
  הסיכוי שניכנס שוב לנעילת אינדקסים.
- אל תעדכנו את המסמכים החיצוניים או תכנית rollout לפני שקיימת הוכחה באחד הסביבות
  (Staging/Production Canary) שהלוג ``sticky_indexes_warmup`` אכן רץ בהצלחה.