Tracing ממוקד בנקודות חמות

מדריך קצר להתמקדות ב‑Tracing בנקודות בעלות השפעה גבוהה (Hotspots) בבוט וב‑WebApp.

תרשימי זרימה

זרימת bot.update

        graph TD
    A[bot.update Request] --> B[Process Update]
    B --> C[DB Operations]
    C --> D[External APIs]
    D --> E[Response]

    style A fill:#e1f5fe
    style E fill:#c8e6c9

מאפיינים מומלצים ל‑Spans (bot.update)

  • status: ”ok“/“error“

  • user_id_hash: מזהה מוצפן

  • chat_id_hash: מזהה צ’אט מוצפן

  • retry_count: 0–3

  • duration_ms

  • update_type: message/callback/inline

זרימת web.request

        graph LR
    A[HTTP Request] --> B[Flask WebApp]
    B --> C[Search with Cache]
    C --> D[Response]

    style A fill:#fff3e0
    style D fill:#f3e5f5

מאפיינים מומלצים ל‑Spans (web.request)

  • http.status_code

  • component: ”flask.webapp“

  • cache_hit: true/false

  • user_id_hash

  • method: GET/POST/PUT/DELETE

  • path

טבלת ”היכן עוטפים“

כיסוי דקורטור

מודול

פונקציה

דקורטור

מאפיינים נרשמים

סטטוס

search_engine

search()

@traced("search")

query, results_count, status

מיושם

database

get_user_files()

@traced("db.get_user_files")

user_id_hash, file_count, status

מיושם

integration

share_code()

@traced("integration.share_code")

platform, code_size, status

מיושם

services/code_service

validate_code_input(), analyze_code(), extract_functions()

@traced("code_service.*")

language, code.length, status

מיושם

http_sync

request()

@traced("http_sync.request")

http.status_code, status, duration_ms, retry_count

מיושם

auth

verify_token()

@traced("auth")

token_type, valid, user_role

בפייפליין

cache

get/set()

@traced("cache")

key, hit/miss, ttl

בפייפליין

דוגמת Trace Viewer

לפני השיפור:

[REQUEST] ────────────────────────── 2500ms
  └── [HANDLER] ──────────────────── 2400ms

אחרי השיפור:

[bot.update] ────────────────────────── 2500ms
  ├── [db.get_user_files] ─ 200ms
  │   └── attributes: {status: "ok", user_id_hash: "a3f2...", file_count: 5}
  ├── [search_engine.search] ────── 1800ms
  │   └── attributes: {status: "ok", query: "python", results: 42}
  └── [integration.share_code] ── 400ms
      └── attributes: {status: "ok", platform: "github"}

[web.request] ────────────────────────── 1200ms
  ├── attributes: {component: "flask.webapp", http.status_code: 200}
  └── [search] ─────── 900ms
      └── attributes: {cache_hit: true, status: "ok"}

הטמעת דקורטור ושימוש בפונקציות עזר

from observability_instrumentation import traced, start_span, set_current_span_attributes

# שימוש בדקורטור
@traced("search_engine.search")
async def search(query: str):
    set_current_span_attributes({
        "query": query,
        "status": "in_progress"
    })
    try:
        results = await perform_search(query)
        set_current_span_attributes({
            "results_count": len(results),
            "status": "ok"
        })
        return results
    except Exception as e:
        set_current_span_attributes({
            "status": "error",
            "error_message": str(e)
        })
        raise

# Span ידני
async def complex_operation():
    with start_span("custom_operation") as span:
        set_current_span_attributes({"step": "processing"})
        # ... לוגיקה ...

Best Practices

  1. מתי להוסיף Span: פעולות I/O, לוגיקה עסקית >100ms, נקודות כשל.

  2. מאפיינים חשובים: תמיד status, user_id_hash; לפי הקשר: cache_hit, retry_count, error_message.

  3. טיפ: השתמשו ב‑set_current_span_attributes() לעדכון מאפיינים לאורך הפעולה.

  4. אל תעשה: אל תעטפו פונקציות קטנות (<10ms), אל תכללו מידע רגיש, אל תיצרו spans בתוך לולאות טייטות.

ראו גם