# פקודות ChatOps

להלן מבנה אחיד לכל פקודה: מתי להשתמש, פרמטרים, הרשאות, מה לחפש בפלט, ודוגמה קצרה אם יש ערך מוסף.

## כרטיסיות חיפוש (Ctrl/Cmd+K)
- ניתן לפתוח את החיפוש הגלובלי (`Ctrl/Cmd+K`) ולמצוא כל פקודת ChatOps במהירות. הכרטיסים מוזנים מקובץ `webapp/static/data/commands.json` ולכן חובה לעדכן אותו בכל פעם שמוסיפים פקודה חדשה.
- הכרטיסים מפנים חזרה לעמוד זה – לחיצה על `/cache_clear_stale`, `/status_worker` או `/version_history` תגלול ישירות לסקשן המתאים כאן.
- מידע נוסף על מבנה הקטלוג נמצא ב-:doc:`/webapp/commands-catalog`.

## /status
- מתי להשתמש: כשצריך תמונת מצב מהירה על תעבורה/לטנסי + Health בסיסי.
- פרמטרים:
  - `--since <duration>` – חלון אחורה מעכשיו. תומך `m`/`h`/`d` (לדוגמה: `15m`, `2h`, `1d`)
  - `--from <iso8601> --to <iso8601>` – חלון זמן ספציפי (לחקירת עבר)
  - (אופציונלי ב-/errors בלבד: `--endpoint`, `--min_severity`)
- ברירת מחדל: 5 דקות אחרונות.
- Timezone: אם לא צוין אזור זמן ב-ISO8601, מניחים **UTC** (ומציינים זאת בפלט).
- Safety: חלון מקסימלי 24 שעות (כדי למנוע שאילתות כבדות).
- הרשאות: מנהלים בלבד (ובצ'אטים מורשים).
- מה לחפש בפלט:
  - Total Requests בחלון
  - Latency percentiles: p50/p95/p99
  - Slowest Endpoints בחלון
  - Active Requests (רגעי) + Health בסיסי (DB/Redis/Sentry/OTEL)
- דוגמאות:
```
/status --since 15m
/status --from 2025-12-16T10:00 --to 2025-12-16T10:15
```

## /health
- מתי להשתמש: אותו צורך כמו /status, לטובת משתמשים שמכירים את השם הישן.
- פרמטרים: כמו /status
- הרשאות: כולם (בצ'אט מורשה)
- מה לחפש בפלט: זהה ל-/status; הפקודה היא אליאס מלא ולכן צריכה להחזיר אותו פלט בדיוק.

## /uptime
- מתי להשתמש: לבדוק אחוז זמינות היסטורי ומשך פעילות מאז העלייה האחרונה.
- פרמטרים: אופציונלי `window=<minutes|hours>` (ברירת מחדל: 24h)
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: uptime%, משך מאז restart, החרגות (planned maintenance) אם קיימות.

## /system_info
- מתי להשתמש: לבדוק עומסי CPU/זיכרון/דיסק בחתך רגעי.
- פרמטרים: ללא
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: אחוזי CPU, שימוש RAM, swap, גרסת מערכת, env רלוונטי (לדוגמה `ASSET_VERSION`).

## /check commands
- מתי להשתמש: כשצריך לוודא **אילו פקודות Slash באמת רשומות בקוד בזמן ריצה** (כולל פקודות שלא מופיעות בתפריט של טלגרם), ולראות מה “מוסתר” מהתפריט.
- פרמטרים: `commands` (חובה). בלי פרמטרים (`/check`) הפקודה מציגה רק את פקודות התפריט של טלגרם (Public/Personal).
- הרשאות: מנהלים בלבד (`ADMIN_USER_IDS`)
- מה לחפש בפלט:
  - `All Registered Commands (runtime)` – הרשימה האמיתית של `CommandHandler` שנרשמו ב־`Application`
  - `Hidden Commands` – פקודות שבקוד אבל לא בתפריט טלגרם
  - `Menu-only` – פקודות שבתפריט אבל לא קיימות בקוד (עוזר לזהות דריפט/שאריות קונפיג)
- הערה: הפקודה לא מנסה להסיק פקודות שמופעלות דרך `MessageHandler`/כפתורים/טקסט חופשי — רק מה שנרשם כ־Slash.
- דוגמה:
```
/check commands
```

## /metrics
- מתי להשתמש: לשלוף dump מלא של מדדי Prometheus לצורך ניתוח חיצוני.
- פרמטרים: ללא
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: קובץ `.txt` שמכיל את כל המטריקות; ודא שהבוט מציין אם נחתך או נשלח בקובץ.

## /observe
- מתי להשתמש: לסקירה מהירה של בריאות השירות בלי רעש.
- פרמטרים: אופציונליים `source=db|memory|all`, `window=5m|1h|24h`
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: סטטוס latency/error-rate/uptime + ציון מקור הנתונים, ספירת alerts קצרה, cooling מצב נוכחי.

## /observe -v (מפורט)
- מתי להשתמש: כשצריך פירוט רחב יותר (alerts מפורקים, שגיאות אחרונות, sinks).
- פרמטרים: כמו /observe
- הרשאות: מנהלים בלבד
- מה לחפש בפלט:
  - Latency/Error Rate עם ספים אדפטיביים
  - Alerts DB מול Memory (כולל critical count)
  - Recent Errors (N≤5)
  - Cooling/Sinks סטטוס
- דוגמה:
```
/observe -v window=5m source=all
```

## /observe -vv (מפורט מאוד)
- מתי להשתמש: כשצריך גם מזהי התראות אחרונים מה-DB להמשך תחקור/ביטול.
- פרמטרים: כמו /observe
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: כל מה שפורט ב-/observe -v ועוד SECTION של `Recent Alert IDs (DB, N≤10)`.

## /errors
- מתי להשתמש: לקבל את 10 השגיאות האחרונות שחזרו מהמערכת.
- פרמטרים:
  - `--since <duration>` או `--from <iso8601> --to <iso8601>`
  - `--endpoint /path` (אופציונלי)
  - `--min_severity ERROR` (אופציונלי; תומך גם WARNING/CRITICAL וכו')
  - עדיין נתמך גם פורמט ישן `service=...` / `endpoint=...` לטובת תאימות
- ברירת מחדל: כמו היום – Top ב-5/30/120 דקות + Sentry issues אם מוגדר.
- הרשאות: מנהלים בלבד (נבדק גם throttling)
- מה לחפש בפלט:
  - Top Error Signatures + Counts
  - דגימות של `request_id`/`trace_id` (אם קיימים)
  - קישור Sentry לפי חתימה (כשאפשר) + פקודת המשך: `/errors examples <signature>`

### סטטוסי תוצאות (Mappings)
- אנו ממפים תוצאות לסטטוסים אחידים לצורך ניתוח מהיר ודשבורדים:
  - `2xx` – הצלחה
  - `cancelled` – פעולה שבוטלה ע"י משתמש/זרימה
  - `error`/`5xx` – כשל כללי
- לייבלים משלימים במטריקות: `status`, `cache_hit`.

## /alerts
- מתי להשתמש: לראות את 5 ההתראות האחרונות שנוצרו (DB + קורלציה).
- פרמטרים: אופציונלי `severity=<critical|high|low>`
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: שם כלל ההתראה, severity, זמן פתיחה, האם קיימת השתקה פעילה.

## /jobs
- מתי להשתמש: כשצריך נראות מרוכזת לריצות רקע **וגם לפעולות משתמש** שרצות ברקע (Drive/Reminders/Batch) – כולל לוגים וסטטוסים.
- פרמטרים:
  - ללא פרמטרים: סיכום כללי לפי קטגוריות
  - `active` – רשימת הרצות פעילות עכשיו
  - `failed` – כשלים אחרונים + קישור ללוגים ב-WebApp
  - `<job_id>` – פרטי Job ספציפי + היסטוריית הרצות קצרה
  - `<category>` – למשל `backup`, `sync`, `batch`, `cache`, `cleanup`, `monitoring`, `other`
- הרשאות: לפי מדיניות ה-ChatOps/אדמין (בדומה לשאר הפקודות המנהליות).
- מה לחפש בפלט:
  - סטטוס `running/failed/skipped/completed`
  - `run_id` וקישור ישיר ל-`/jobs/monitor?run_id=...`
  - אם קישורים לא נראים תקין – ודאו ש-`WEBAPP_URL` מוגדר בסביבה.
- דוגמאות:
```
/jobs
/jobs active
/jobs failed
/jobs drive_123456
/jobs batch
```

## /incidents
- מתי להשתמש: מעבר מהיר על יומן התקלות האחרון (Incident Memory).
- פרמטרים: אופציונלי `limit=<n>` (ברירת מחדל 5)
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: תאריך/שעה, תקציר, בעלים, סטטוס (ongoing/resolved).

## /triage
- מתי להשתמש: תחקור מהיר של תקלה פעילה לפי `request_id`.
- פרמטרים: `request_id=<id>` אופציונלי (אם אין – מוצגות חריגות חמות ביותר)
- הרשאות: מנהלים בלבד (עם הגבלת קצב)
- מה לחפש בפלט: Root cause משוער, גרפים רלוונטיים, Playbooks מומלצים.

## /predict
- מתי להשתמש: כשצריך תחזית חריגות ב-3 השעות הקרובות.
- פרמטרים: ללא
- הרשאות: כולם
- מה לחפש בפלט: מגמת latency/error (🔴/🟢/⚪), "confidence", התרעות צפויות.

## /accuracy
- מתי להשתמש: לבחון את דיוק מודל החיזוי לאורך זמן.
- פרמטרים: אופציונלי `window=<days>` (ברירת מחדל 7)
- הרשאות: כולם
- מה לחפש בפלט: אחוז התאמות, FP/FN יומיים, הערות על drift אם קיים.

## /rate_limit
- מתי להשתמש: לבדוק את מכסת GitHub API והצריכה העכשווית.
- פרמטרים: ללא
- הרשאות: מנהלים בלבד (עם throttling)
- מה לחפש בפלט: remaining/limit/reset_time לכל מחלקה (core/search/graph), התרעות על backoff.

## /enable_backoff
- מתי להשתמש: להכריח את המערכת לעבור למצב חסכון בקריאות GitHub (למשל בעת rate limit נמוך).
- פרמטרים: אופציונלי `reason=<text>`
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: אישור מצב חדש, timeouts שיוחלו, רמז כיצד לבטל.

## /disable_backoff
- מתי להשתמש: לחזור לפעילות רגילה אחרי שהסיכון חלף.
- פרמטרים: ללא
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: אישור ביטול וחיווי שאין throttling פעיל.

## /sen
- מתי להשתמש: לקבל קישור ישיר ללוח Sentry עבור האירועים החמים.
- פרמטרים: אופציונלי `project=<name>` או `query="..."`
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: לינקים מוכנים (טלגרם תומך בכפתורים) ומדד severities.

## /lang
- מתי להשתמש: לזהות במהירות את שפת הקובץ/התוכן בבוט (Source of Truth).
- פרמטרים: אופציונלי `<file_name>`; ניתן להשיב ב-reply עם קוד או לצרף בלוק ```
- הרשאות: כולם
- מה לחפש בפלט: `language` ו-`reason` (מקור ההכרעה: shebang/סיומת/שם/תוכן).
- דוגמה:
```
/lang run
```
Reply עם:
```bash
#!/usr/bin/env bash
python main.py
```
פלט צפוי:
```
🧠 שפה: bash
📄 קובץ: `run`
ℹ️ סיבה: shebang (bash/sh)
```

## /lang_debug
- מתי להשתמש: דיבוג מפורט של החלטת הדטקטור (conflict name↔content, "למה text?").
- פרמטרים: אופציונלי `<file_name>`; קוד עובר ב-reply/בלוק ``` כמו ב-/lang.
- הרשאות: כולם
- מה לחפש בפלט: shebang, base/ext, אותות Python, סמני Markdown, החלטה סופית.

## /dm
- מתי להשתמש: שליחת הודעה פרטית למשתמש בודד (למשל להודיע על סטטוס "פרימיום 💎").
- פרמטרים: `<user_id|@username> <message...>`
- הרשאות: מנהלים בלבד (`ADMIN_USER_IDS`)
- מה לחפש בפלט: חיווי הצלחה/כישלון; במקרה של חסימה יוצג `blocked`.

## /silence
- מתי להשתמש: השתקה זמנית של התראה/תבנית בזמן תחזוקה או תחקור.
- פרמטרים: `<name|pattern> <duration> [reason...] [severity=<level>] [--force]`
- הרשאות: מנהלים בלבד (עם throttling)
- מה לחפש בפלט: מזהה ההשתקה, זמן תפוגה, האם הופעלה בכוח (`--force`).
- דוגמה:
```
/silence "High Latency" 2h reason=maintenance
```

## /unsilence
- מתי להשתמש: ביטול השתקה קיימת לפי מזהה או תבנית.
- פרמטרים: `<silence_id|pattern>`
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: אישור מחיקה, ואם לא נמצא – הודעה מפורטת.

## /silences
- מתי להשתמש: אינבנטורי של כל ההשתקות הפעילות כדי לוודא שאין השתקה שנשכחה.
- פרמטרים: אופציונלי `limit=<n>` (ברירת מחדל 50)
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: מזהה, pattern, severity, זמן סיום.

## /cache_stats
- מתי להשתמש: לבדוק האם Redis פעיל ומה ה-hit-rate העדכני.
- פרמטרים: ללא
- הרשאות: כולם (אם יש Redis)
- מה לחפש בפלט: enabled/disabled, used_memory, connected_clients, Hit Rate עם אמוג'י מצב.

## /clear_cache
- מתי להשתמש: לנקות את הקאש האישי (למשל אחרי שינוי הרשאות או קבצים רבים).
- פרמטרים: ללא
- הרשאות: כולם
- מה לחפש בפלט: מספר הערכים שנמחקו והערה שהפעולות הבאות יהיו מעט איטיות עד שהקאש יתמלא מחדש.

## /cache_warm
- מתי להשתמש: לחמם מראש את קאש `/api/stats` עבור המשתמש כדי לזרז טעינות בדשבורד.
- פרמטרים: ללא
- הרשאות: כולם (דורש חיבור DB תקין)
- מה לחפש בפלט: "✅ קאש חומם" או הודעת שגיאה אם DB לא זמין.

## /cache_clear_stale
- מתי להשתמש: כשאחוז ה-RAM בשרת מזנק בגלל Redis וצריך ניקוי עדין של מפתחות שפג תוקפם.
- פרמטרים: אופציונלי `max=<סריקות>` ו-`ttl=<שניות>` (ברירת מחדל 1000 / 60).
- הרשאות: מנהלים בלבד (מכבד SAFE_MODE ו-`DISABLE_CACHE_MAINTENANCE`).
- מה לחפש בפלט: מספר המפתחות שנמחקו, הערה אם SAFE_MODE חסם את ההרצה.

## /debug_cache
- מתי להשתמש: בזמן תחקור Hit Rate נמוך, כדי לראות בלוגים של פעולות cache (HIT/MISS/SET) לפי מפתח.
- פרמטרים: `<seconds>` (מספר שלם בשניות). `0` מכבה.
- הרשאות: מנהלים בלבד
- מה לחפש בפלט: הודעה שהדיבאג הופעל/כובה + `debug_until` (UTC). בזמן החלון הזה יופיעו בשרת לוגים `cache HIT/MISS/SET key=...`.

## /status_worker
- מתי להשתמש: בזמן חשד לעומס בתורים/Push Worker כדי לוודא שה-sidecar מגיב.
- פרמטרים: אופציונלי `url=<https://worker>` או `path=/healthz`.
- הרשאות: מנהלים בלבד.
- מה לחפש בפלט: סטטוס HTTP ו-latency של `/healthz`, חיווי האם `PUSH_REMOTE_DELIVERY_ENABLED` ו-`PUSH_DELIVERY_TOKEN` מוגדרים.

## /version_history
- מתי להשתמש: לבדוק האם התרעה קרתה מיד אחרי Deployment ולצרף פרטי actor/request_id.
- פרמטרים: אופציונלי `limit=<n>` (ברירת מחדל 5) ו-`hours=<חלון>` (ברירת מחדל 6h).
- הרשאות: מנהלים בלבד.
- מה לחפש בפלט: טבלת זמנים של Deployment events, כולל actor/request_id ולינק להמשך בדיקת observability.