אובזרווביליות (Observability)
==============================

מטרות
------
- לוגים מובנים עם ``event`` ו-``error_code``.
- קורלציה בין אירועים באמצעות ``request_id`` ו-``trace_id``.
- מטריקות: ספירות, זמני תגובה, מצב מערכת.
- התראות: הגדרת ספים וזיהוי תקלות אוטומטי.
- פרטיות: טשטוש מידע רגיש (Redaction) ודגימה (Sampling).

קהלי יעד
--------
- סוכני AI: לזיהוי דפוסים וביצוע פעולות תיקון (Remediation).
- מפתחים: לדיבוג מהיר וניטור ביצועים.

תצורה
------
- Structured logging באמצעות ``structlog``.
- OpenTelemetry (אופציונלי): אתחול אוטומטי עם OTLP Exporter.
  
  משתני סביבה עיקריים:
  
  - ``OTEL_EXPORTER_OTLP_ENDPOINT``: ברירת מחדל ``http://localhost:4317``
  - ``OTEL_EXPORTER_INSECURE``: ``true``/``false`` (ברירת מחדל ``false``)
  - ``ENVIRONMENT`` / ``ENV``: שם סביבה לדיווח resource
  - ``APP_VERSION``: גרסה לשיוך ל-``service.version``
  
  מדיניות Fail‑Open::
  אינסטרומנטציה ותיעוד חייבים להיות "שקופים" לפעולה העסקית. אם OTel/Prometheus אינם זמינים
  (ייבוא נכשל, חיבור חסום, או שגיאת תצורה) – המודולים עובדים במצב ``no‑op`` ללא חריגה
  המשביתה את האפליקציה. זה מאפשר להפעיל tracing/metrics בהדרגה ללא סיכון לזמינות.
  
  אינסטרומנטציה אוטומטית:
  - Flask (כשקיים אובייקט ``app``)
  - Requests
  - PyMongo
  
  עבור Flask האתחול קורה ב-``webapp/app.py``. עבור תהליכים ללא Flask (למשל הבוט), האתחול קורה ב-``main.py`` ללא ``flask_app``.
- Prometheus דרך נקודת קצה ``/metrics``.
- Sentry לטיפול בשגיאות.

בחירת Backend ל־Traces
-----------------------
מומלץ להתחיל עם אחד מהבאים (כולם תומכים ב־OTLP):

- Jaeger (פשוט לפריסה מקומית/דוקר)
- Grafana Tempo (סקיילבל, מתאים לשילוב עם Grafana/Prometheus)
- Grafana Cloud (שירות מנוהל)

הגדרת OTLP לסביבות
--------------------
הגדירו משתני סביבה בכל סביבה:

.. code-block:: bash

    # Staging
    export ENVIRONMENT=staging
    export APP_VERSION=1.2.3
    export OTEL_EXPORTER_OTLP_ENDPOINT="http://tempo.staging.svc:4317"
    export OTEL_EXPORTER_INSECURE=true

    # Production
    export ENVIRONMENT=production
    export APP_VERSION=1.2.3
    export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.prod.example.com:4317"
    export OTEL_EXPORTER_INSECURE=false

הערות:

- ב־gRPC ברירת המחדל היא יציאה 4317.
- כאשר עובדים מול TLS פרטי/מאולתר, ניתן להגדיר ``OTEL_EXPORTER_INSECURE=true``.
- ודאו פתיחת פיירוול/Ingress ליצוא ה־OTLP מהאפליקציה.

קישורים
--------
- :doc:`logging_schema`
- :doc:`metrics`
- :doc:`alerts`
- :doc:`sentry`
- :doc:`observability/quick_fix_rules`
- :doc:`runbooks/logging-levels`
- Datasource של Jaeger ב‑Grafana מוגדר תחת ``docker/grafana/provisioning/datasources/prometheus.yml``


אינסטרומנטציה ידנית (Manual Instrumentation)
---------------------------------------------
בנוסף לאינסטרומנטציה האוטומטית של Flask/Requests/PyMongo, ניתן להוסיף טרייסים ומטריקות ידניות עם הדקורטור `@traced` מתוך המודול `observability_instrumentation`.

מאפיינים:

- בטוח להרצה בלי תלות ב־OpenTelemetry (No‑Op אם לא מותקן)
- יוצר Span בשם קבוע שניתן להגדיר
- מודד משך זמן ומסמן חריגות במטריקות (`request.duration`, `errors.total`, `requests.active`)

דוגמאות שימוש:

.. code-block:: python

    from observability_instrumentation import traced

    @traced("bookmarks.toggle")
    def toggle_bookmark(...):
        # קוד הפונקציה
        pass

    @traced("batch.reindex")
    async def reindex_all(...):
        # קוד אסינכרוני
        ...

הערות:

- הדקורטור פועל גם על פונקציות sync וגם על async.
- כאשר מתרחשת חריגה, משך הפעולה נרשם פעם אחת בלבד עם המאפיין ``error=True``.
- עבור Flask, האינסטרומנטציה האוטומטית מוסיפה טרייסים ברמת הבקשה; שימוש ב־`@traced` מומלץ סביב פעולות עסקיות קריטיות בתוך הידלרים או שירותים.

דוקר קומפוז – הפעלה מהירה עם Jaeger
-------------------------------------
לריצה מקומית עם Tracing מלא (Jaeger + Grafana + Prometheus):

.. code-block:: bash

   # הרצת שירותי ניטור + בוט
   docker-compose --profile monitoring up jaeger grafana prometheus code-keeper-bot mongodb

   # גישה ל-Jaeger UI
   # http://localhost:16686

ברירת המחדל ב-Compose שולחת OTLP ל-``http://jaeger:4317``. ניתן לדרוס:

.. code-block:: bash

   export OTEL_EXPORTER_OTLP_ENDPOINT="http://tempo.staging.svc:4317"  # לדוגמה Tempo
   export OTEL_EXPORTER_INSECURE=true
   docker-compose up -d

Quick start – אימות ספאנים ב־Jaeger
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. הריצו את השירותים עם הפרופיל ``monitoring`` (ראו פקודה לעיל).
2. ודאו ש‑``OTEL_EXPORTER_OTLP_ENDPOINT`` מצביע ל‑``http://jaeger:4317`` (ברירת המחדל ב‑Compose).
3. פתחו את Jaeger ב‑``http://localhost:16686`` ובחרו את השירות ``code-keeper-bot`` או ``code-keeper-webapp``.
4. הריצו פעולות כבדות (חיפוש/הורדה/פעולות bulk) ואמתו הופעת spans עם שמות העסקיים מהדקורטור ``@traced``.

כיסוי דקורטור @traced
-----------------------
הוספנו כיסוי ידני במסלולים כבדים:

- ``search.global`` (קיים)
- ``search.suggestions`` (קיים)
- ``files.list`` (קיים)
- ``files.download`` (חדש)
- ``files.bulk_favorite`` (חדש)
- ``files.bulk_unfavorite`` (חדש)
- ``files.bulk_tag`` (חדש)

אימות ב-Staging
----------------
בדקו שהטרייסים מגיעים:

1. הגדירו משתני סביבה בשירות:

   ::

      ENVIRONMENT=staging
      APP_VERSION=1.2.3
      OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.yourdomain:4317
      OTEL_EXPORTER_INSECURE=false

2. שלחו מספר בקשות לנתיבים הכבדים (חיפוש, הורדה, bulk tag/fav).
3. ודאו הופעת השירותים ``code-keeper-webapp`` ו-``code-keeper-bot`` ב-Backend (Jaeger/Tempo).