מדריך למשתמש Cat-Scan¶

הבעיה בתמונה אחת¶

משפך QPS

Google שולחת למכרז שלך זרם אדיר של בקשות הצעת מחיר. בכל שנייה, עשרות אלפי שאילתות זורמות מבורסת Authorized Buyers לעבר נקודת הקצה שלך. המכרז שלך מעריך כל אחת מהן, מחליט אם להציע הצעת מחיר, ומגיב — והכל תוך אלפיות שנייה בודדות.

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

התרשים למעלה מתאר את זה כגשם. ה-QPS של Google הוא הזרביב בחלק העליון; הטיפות מתפזרות על פני שטח רחב. המכרז שלך הוא הדלי הקטן בתחתית. כל מה שמחמיץ את הדלי (הטיפות שנופלות ימינה ושמאלה) הוא בזבוז. שילמת על זה. לא קיבלת דבר בתמורה.

Cat-Scan קיים כדי להרחיב את הדלי ולצמצם את הגשם.

הוא עושה זאת על ידי מתן נראות לאן הבזבוז מתרחש (אילו אזורים גאוגרפיים, אילו מפרסמים, אילו גדלי מודעות, אילו קריאייטיבים) ואת הכלים לעצור אותו במקור, באמצעות תצורות הפרה-טרגוט שמספקת Google.

למה זה קשה יותר ממה שנדמה¶

Google Authorized Buyers נותנת לך רק 10 תצורות פרה-טרגוט לכל מושב, בתוספת קטגוריות גאוגרפיות גסות (מזרח ארה"ב, מערב ארה"ב, אירופה, אסיה). אין API לדוחות. כל נתוני הביצועים מגיעים מייצוא CSV שנשלח בדוא"ל. ממשק המשתמש של AB לפרה-טרגוט הוא פונקציונלי אך מקשה לראות את התמונה המלאה על פני תצורות, או לבטל שינוי שהשתבש.

Cat-Scan סוגר את הפערים האלה:

הוא בונה מחדש דיווח מייצוא CSV (העלאה ידנית או קליטה אוטומטית מ-Gmail), עם הסרת כפילויות בעת הייבוא כך שעיבוד חוזר לעולם לא סופר פעמיים.
הוא מציג את משפך ה-RTB המלא, מ-QPS גולמי דרך הצעות מחיר, זכיות, חשיפות, קליקים והוצאה, עם פירוט לפי כל ממד: גאוגרפיה, מפרסם, גודל מודעה, קריאייטיב, תצורה.
הוא מספק ניהול פרה-טרגוט בטוח עם היסטוריה, שינויים מדורגים, תצוגה מקדימה של הרצת ניסיון, וחזרה לאחור בלחיצה אחת.
הוא מריץ אופטימייזר שמדרג פלחים ומציע שינויי תצורה, עם מסילות בטיחות לתהליך העבודה (זהיר / מאוזן / אגרסיבי) כך ששום שינוי לא נכנס לפרודקשן ללא בדיקה.

למי מיועד המדריך הזה¶

למדריך הזה שני מסלולים כי Cat-Scan משרת שני תפקידים שונים מאוד:

קוני מדיה ומנהלי קמפיינים משתמשים ב-Cat-Scan כדי להבין לאן התקציב שלהם הולך, למצוא בזבוז, לנהל קריאייטיבים, לכוונן פרה-טרגוט ולאשר הצעות אופטימיזציה. הם חושבים במונחים של CPM, אחוזי זכייה ו-ROAS. הפרקים שלהם מתמקדים במה שממשק המשתמש מציג, מה המספרים אומרים ואילו פעולות לבצע.

מהנדסי DevOps ומהנדסי פלטפורמה משתמשים ב-Cat-Scan כדי לפרוס, לנטר ולפתור בעיות במערכת. הם חושבים בקונטיינרים, נקודות קצה לבדיקת תקינות ותוכניות שאילתות. הפרקים שלהם מתמקדים בארכיטקטורה, צינורות פריסה, פעולות מסד נתונים ומדריכי תגובה לתקריות.

שני המסלולים חולקים בסיס משותף (תחילת העבודה, מילון מונחים) והפרקים מפנים זה לזה כאשר תהליכי עבודה חופפים. קונה מדיה שמדווח "רעננות הנתונים שבורה" ומהנדס DevOps שמאתר באג בשאילתה מאחוריה צריכים להיות מסוגלים להצביע על אותו ערך במילון המונחים ולהבין אחד את השני.

כיצד לקרוא מדריך זה¶

חלק 0 הוא לכולם. התחילו כאן.
חלק I הוא מסלול קוני המדיה. אם אתם עובדים בקמפיינים, אופטימיזציה או רכישה, זה המסלול שלכם.
חלק II הוא מסלול ה-DevOps. אם אתם פורסים, מנטרים או מנהלים את Cat-Scan, זה המסלול שלכם.
חלק III הוא מקור עיון משותף: מילון מונחים, שאלות נפוצות ואינדקס API.

אין צורך לקרוא לינארית. כל פרק עומד בפני עצמו. עקבו אחר הקישורים שמתאימים לתפקיד שלכם.

תוכן עניינים¶

חלק 0: תחילת העבודה¶

כולם קוראים את זה.

פרק 0: מהו Cat-Scan? מה הפלטפורמה עושה, למי היא מיועדת, ומושגי הליבה שצריך לפני כל דבר אחר: מושבים, QPS, פרה-טרגוט, משפך ה-RTB.
פרק 1: כניסה למערכת שיטות אימות (Google OAuth, חשבונות מקומיים), דף ההתחברות, מה לעשות כשהכניסה נכשלת, וכיצד בורר המושבים עובד.
פרק 2: ניווט בלוח הבקרה סרגל הצד, מעבר בין מושבים, בורר השפה, רשימת המשימות להגדרת חשבון חדש, וכיצד הדפים מאורגנים.

חלק I: מסלול קוני מדיה¶

לקוני מדיה, מנהלי קמפיינים ומהנדסי אופטימיזציה.

פרק 3: הבנת משפך ה-QPS שלך דף הבית. כיצד לקרוא את פירוט המשפך: חשיפות, הצעות מחיר, זכיות, הוצאה, אחוז זכייה, CTR, CPM. מה "בזבוז" אומר במונחים מוחשיים. כרטיסי תצורה ומה השדות שלהם שולטים.
פרק 4: ניתוח בזבוז לפי ממד שלוש תצוגות ניתוח הבזבוז ומתי להשתמש בכל אחת:
גאוגרפי (/qps/geo): אילו מדינות וערים צורכות QPS מבלי להמיר.
מפרסמים (/qps/publisher): אילו דומיינים ואפליקציות מתפקדים מתחת לציפיות.
גודל (/qps/size): אילו גדלי מודעות מקבלים תעבורה אך אין להם קריאייטיב תואם. Google שולחת כ-400 גדלים שונים; רובם אינם רלוונטיים למודעות תצוגה בגודל קבוע.
פרק 5: ניהול קריאייטיבים גלריית הקריאייטיבים (/creatives): עיון לפי פורמט, סינון לפי דרגת ביצועים, חיפוש לפי מזהה. תמונות ממוזערות, תגיות פורמט, אבחון יעד. קיבוץ קמפיינים (/campaigns): גרור ושחרר, קיבוץ אוטומטי בינה מלאכותית, מאגר הלא-משויכים.
פרק 6: תצורת פרה-טרגוט מה תצורת פרה-טרגוט שולטת (אזורים גאוגרפיים, גדלים, פורמטים, פלטפורמות, QPS מקסימלי). כיצד לקרוא כרטיס תצורה. החלת שינויים עם תצוגה מקדימה של הרצת ניסיון. ציר הזמן של היסטוריית השינויים (/history). חזרה לאחור: כיצד זה עובד, למה זה קיים ומתי להשתמש בזה.
פרק 7: האופטימייזר (BYOM) Bring Your Own Model: רישום נקודת קצה חיצונית לדירוג, אימות שלה, הפעלתה. מחזור החיים דירוג-הצעה-אישור-החלה. הגדרות תהליך עבודה: זהיר, מאוזן, אגרסיבי. כלכלה: CPM אפקטיבי, קו בסיס עלויות אירוח, סיכום יעילות. כיצד נראית הצעה וכיצד להעריך אחת.
פרק 8: המרות וייחוס חיבור מקור המרות. שילוב פיקסל. הגדרת Webhook: חתימות HMAC, סודות משותפים, הגבלת קצב. בדיקות מוכנות. סטטיסטיקות קליטה. מה "בריאות המרות" אומר וכיצד לקרוא את דף סטטוס האבטחה.
פרק 9: ייבוא נתונים כיצד נתונים מגיעים ל-Cat-Scan, ולמה זה חשוב. העלאת CSV ידנית (/import): גרור ושחרר, מיפוי עמודות, תיקוף, העלאה בנתחים לקבצים גדולים. ייבוא אוטומטי מ-Gmail: כיצד זה עובד, כיצד לבדוק סטטוס, מה קורה כשזה נכשל. רשת רעננות הנתונים: מה "יובא" מול "חסר" אומר לכל תאריך וסוג דוח. הבטחות הסרת כפילויות.
פרק 10: קריאת הדוחות שלך סטטיסטיקות הוצאה, פאנלים של ביצועי תצורה, מדדי יעילות נקודת קצה. כיצד לפרש מגמות. מה הפירוט היומי מציג. השוואות תמונות מצב: לפני ואחרי שינוי פרה-טרגוט.

חלק II: מסלול DevOps¶

למהנדסי פלטפורמה, SRE-ים ומנהלי מערכת.

פרק 11: סקירת ארכיטקטורה טופולוגיית המערכת: FastAPI בצד השרת, Next.js 14 בצד הלקוח, Postgres (Cloud SQL), BigQuery. למה שני מסדי נתונים קיימים (עלות, חביון, צבירה מקדימה, ניהול חיבורים). פריסת קונטיינרים: api, dashboard, oauth2-proxy, cloudsql-proxy, nginx. שרשרת אמון האימות: OAuth2 Proxy קובע X-Email, nginx מעביר אותו, ה-API סומך עליו.
פרק 12: פריסה צינור CI/CD: GitHub Actions build-and-push.yml בונה תמונות בעת דחיפה; deploy.yml מופעל ידנית בלבד (עם אישור DEPLOY). תגיות תמונות ב-Artifact Registry (sha-XXXXXXX). רצף הפריסה: git pull על ה-VM, docker compose pull, יצירה מחדש, ניקוי. אימות לאחר פריסה: בדיקת תקינות, בדיקת חוזה. למה פריסה אוטומטית מושבתת (תקרית ינואר 2026). כיצד לאמת פריסה: curl /api/health | jq .git_sha.
פרק 13: ניטור תקינות ואבחון נקודות קצה לתקינות: /api/health (בדיקת חיים), /system/data-health (שלמות נתונים). דף סטטוס המערכת (/settings/system): Python, Node, FFmpeg, מסד נתונים, דיסק, תמונות ממוזערות. סקריפטים לבדיקת תקינות בזמן ריצה: diagnose_v1_buyer_report_coverage.sh, run_v1_runtime_health_strict_dispatch.sh. אימות קנרית: CATSCAN_CANARY_EMAIL, CATSCAN_BEARER_TOKEN. תהליכי CI: v1-runtime-health-strict.yml ומה PASS/FAIL/BLOCKED אומרים.
פרק 14: פעולות מסד נתונים Postgres בלבד בפרודקשן. Cloud SQL דרך קונטיינר פרוקסי. טבלאות מפתח והיקפן: rtb_daily (~84M שורות), rtb_bidstream (~21M שורות), rtb_quality, rtb_bid_filtering. אינדקסים קריטיים: (buyer_account_id, metric_date DESC). מודל חיבורים: לפי בקשה (ללא מאגר), run_in_executor לביצוע אסינכרוני. מגבלות זמן לשאילתות (SET LOCAL statement_timeout). הגדרות שמירת נתונים. תפקיד BigQuery: מחסן אצוות לנתונים גולמיים; Postgres מגיש נתונים שנצברו מראש לאפליקציה.
פרק 15: מדריך פתרון בעיות דפוסי כשל ידועים וכיצד לפתור אותם:
לולאת התחברות: Cloud SQL Proxy למטה, _get_or_create_oauth2_user נכשל בשקט, /auth/check מחזיר {authenticated:false}, לולאת הפניה בצד הלקוח. תיקון בשלוש שכבות. כיצד לזהות: מונה הפניות בדפדפן, 503 מ-/auth/check.
זמן קצוב של רעננות נתונים: טבלאות גדולות מבצעות סריקות רצפיות במקום להשתמש באינדקסים. תסמינים: /uploads/data-freshness פג תוקף או מחזיר
1. אבחון: pg_stat_activity, EXPLAIN ANALYZE. דפוס תיקון: generate_series + EXISTS.
כשל ייבוא Gmail: /gmail/status מציג שגיאה. בדקו את קונטיינר Cloud SQL Proxy. בדקו ספירת הודעות שלא נקראו.
סדר הפעלה מחדש של קונטיינרים: cloudsql-proxy חייב להיות תקין לפני שה-api מתחיל. סימנים לסדר שגוי: connection refused ביומני ה-API.
פרק 16: ניהול משתמשים והרשאות פאנל הניהול (/admin): יצירת משתמשים (מקומיים ויצירה מקדימה של OAuth), ניהול תפקידים, הרשאות לפי מושב. חשבונות שירות: העלאת JSON של הרשאות GCP, מה זה פותח (גילוי מושבים, סנכרון פרה-טרגוט). משתמשים מוגבלים: מה הם רואים ומה מוסתר. יומן הביקורת: אילו פעולות נרשמות, כיצד לסנן, שמירה.
פרק 17: אינטגרציות חשבונות שירות GCP וחיבור פרויקט. Google Authorized Buyers API: גילוי מושבים, סנכרון תצורת פרה-טרגוט, סנכרון נקודות קצה RTB. אינטגרציית Gmail: OAuth2 לקליטת דוחות אוטומטית. ספקי בינה מלאכותית לשפה: Gemini, Claude, Grok (לזיהוי שפת קריאייטיב והתראות על אי-התאמה). Webhooks של המרות: רישום נקודות קצה, אימות HMAC, הגבלת קצב, ניטור רעננות.

חלק III: מקור עיון¶

משותף לשני המסלולים.

מילון מונחים כל מונח בשתי שפות. עמודת קוני מדיה: "פרה-טרגוט" הוא "הכללים ששולטים אילו בקשות הצעת מחיר מגיעות למכרז שלך." עמודת DevOps: "פרה-טרגוט" הוא "ישות ניתנת לשינוי שמסונכרנת מ-AB API, מאוחסנת ב-pretargeting_configs, חשופה דרך /settings/pretargeting." שניהם צריכים את אותה מילה; אף אחד לא משתמש בהגדרה של השני.
שאלות נפוצות מתויגות לפי קהל יעד. שאלות שקונה מדיה שואל ("למה הכיסוי שלי עומד על 74%?") לצד שאלות שמהנדס DevOps שואל ("למה שער בדיקת התקינות בזמן ריצה נכשל?"). התשובות מקשרות לפרק הרלוונטי.
עיון מהיר ב-API כל 118+ נקודות הקצה מקובצות לפי תחום: ליבה, מושבים, קריאייטיבים, קמפיינים, אנליטיקה, הגדרות, ניהול, אופטימייזר, המרות, אינטגרציות, העלאות, תמונות מצב, אימות. שיטה, נתיב, פרמטרים מפתח ומה הוא מחזיר. לא תחליף למפרט OpenAPI ב-/api/docs, אלא אינדקס נגיש לניווט.