Cortex Framework Observability

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

‫Cortex Framework מסווג את יכולת הצפייה בשני מחזורי החיים השונים שלו:

1. יכולת מעקב בזמן הפריסה: מעקב אחרי טעינת ההגדרות, קומפילציה של תבניות, בדיקות אימות, פעולות פריסה וטלמטריה של API במהלך ההרצה של כלי ה-CLI.
2. מעקב בזמן ריצה: מעקב אחר הביצוע, התקדמות צינור הנתונים, ביצועי השאילתות, טענות לגבי איכות הנתונים והתראות אוטומטיות לגבי צינורות הנתונים שנפרסו ופועלים בתוך Google Cloud.

---

ניראות בזמן הפריסה

התכונה 'יכולת צפייה בזמן הפריסה' מתמקדת בהרצה של כלי ה-CLI (לדוגמה: uv run cortex-build,‏ uv run cortex-deploy,‏ uv run cortex-build-and-deploy,‏ uv run cortex-demo,‏ uv run cortex-kc-sync).

רישום ביומן של המסוף המקומי

כשמריצים פקודות CLI, ‏ Cortex Framework מתעד את ההתקדמות ישירות במסוף (stdout).

• רמת היומן: כברירת מחדל, היומנים מופקים ברמה INFO.
• הדגשות חזותיות: ההודעות מקבלות קידוד צבעוני כדי להדגיש שגיאות ואזהרות באופן דינמי:
  • ‫❌ Errors (אדום) – שגיאות קריטיות שגורמות להפסקת ההרצה.
  • ‫⚠️ אזהרות (כתום) שמצביעות על חריגות פוטנציאליות בהגדרה או על בעיות שלא חוסמות את הפעולה.
• חותמת זמן ומקור: בכל שורה ביומן מוצגים זמן הביצוע והשמות של המחלקה או המודול הפעילים ב-Python, למעקב מדויק.

קבצים מקומיים של יומני רישום קבועים

בכל הרצת פקודה, כלי התזמור של Python מעביר אוטומטית את יומן ההרצה המלא לקובץ יומן זמני בספריית temp של המערכת:

/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log

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

Google Cloud אימות הסביבה

לפני שמבצעים פעולות של בנייה, פריסה או סנכרון, מנוע התזמור מפעיל את כלי השירות GcpEnvironmentChecker. הבדיקה הזו מאמתת:

1. Required APIs: מאשר שממשקי API חיוניים Google Cloud מופעלים (לדוגמה, bigquery.googleapis.com, dataform.googleapis.com).
2. קיום של מערך נתונים: המערכת בודקת שמערכי הנתונים הנדרשים של הנתונים הגולמיים ושל היעד קיימים או שאפשר ליצור אותם.
3. מיקומים ואזורים: מוודא שערכות הנתונים של היעד תואמות לאזורים הגיאוגרפיים של ערכות הנתונים של המקור.
4. קיבולת והגדרות: אימות של הגדרות ההזמנה והגדרות הקטלוג.

כל אי התאמה נרשמת ביומן כשגיאה, עם רמזים מומלצים לפתרון הבעיה לפני ביצוע Google Cloud קריאות שירות.

Telemetry

במהלך תהליכי הפריסה והסנכרון, Cortex Framework רושם ביומן נתוני טלמטריה אנונימיים לגבי האימוץ, הווריאנט וגרסת המסגרת של Google Cloud. לפרטים על אופן הפעולה ולהוראות להשבתת הטלמטריה, אפשר לעיין במאמר בנושא טלמטריה.

---

יכולת תצפית בזמן ריצה

אחרי שיוצרים ומפעילים את Cortex Framework, שכבות הנתונים ומוצרי הנתונים התואמים פועלים באופן מלא ב-Dataform וב-BigQuery. כתוצאה מכך, אפשרות הצפייה בזמן ריצה משולבת ישירות עם Google Cloud חבילות תפעוליות.

רישום ביומן של הרצת פייפליין

כל צינורות הנתונים שנפרסו נרשמים ביומן באמצעות Cloud Logging וכלי ההרצה:

• יומני ביצוע של Dataform: מערכת Dataform מתעדת כל אירוע הידור וביצוע. אפשר לגשת לפרטים האלה במסוף Google Cloud או באופן פרוגרמטי באמצעות Dataform API.
• היסטוריית המשימות ב-BigQuery: כל טבלה ותצוגה שנוצרו על ידי צינורות Dataform מריצות שאילתות SQL בתוך BigQuery. נתוני שימוש מפורטים במשאבים, ביצועי שאילתות, בייטים שעברו עיבוד וחותמות זמן של ביצועים מתועדים בהיסטוריית המשימות של BigQuery.

מעקב אחרי צינורות עיבוד נתונים

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

1. ממשק המשתמש באינטרנט של Dataform: עוברים אל מסוף Dataform כדי:
   • בודקים את מודלי הנתונים המהודרים ומציגים את הגרף המהודר.
   • בודקים את הסטטוס של הגדרות ההפצה, התבניות שעברו קומפילציה והסביבות הפעילות.
   • לבדוק את ההיסטוריה ואת הפרטים של הרצות קודמות ונוכחיות של תהליכי עבודה.
2. שילוב עם Cloud Monitoring: מעקב אחרי מדדים של צינורות Dataform, כמו משך הביצוע, קומפילציות פעילות ושיעורי הכשלים של משימות בתהליכי עבודה, באמצעות חלוניות מותאמות אישית בלוח הבקרה.

התראות ואיכות הנתונים

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

הצהרות על איכות הנתונים

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

• אפשר לספק קובץ טענות מותאם אישית באמצעות הפרמטר --assertions: bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
• במהלך ההרצה של צינור הנתונים, Dataform מריץ את שאילתות האימות האלה. אם שאילתת האסרשן מחזירה שורה אחת או יותר, האימות נכשל וביצוע צינור הנתונים מסומן מיד כנכשל.
• מידע נוסף על כתיבת כללי אימות נתונים זמין במסמכי התיעוד הרשמיים של Dataform בנושא הצהרות.

קובץ הצהרה לדוגמה (assertions.sqlx)

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

config {
  type: "assertion",
  description: "Ensure customer_number_kunnr is not null and unique"
}

-- Check for NULL values
(
  SELECT
    "customer_number_kunnr is NULL" AS error_message
  FROM
    ${ref("customers")}
  WHERE
    customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
  SELECT
    CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
  FROM
    ${ref("customers")}
  GROUP BY
    customer_number_kunnr,
    client_mandt
  HAVING
    COUNT(*) > 1
)

מדיניות התראות בענן

אפשר להגדיר Google Cloud מדיניות התראות רגילה כדי להודיע לצוותי ההנדסה או התפעול כשמתעוררות בעיות:

• התראות מבוססות-יומן: אפשר ליצור התראות ב-Cloud Logging שמופעלות כשמזוהים ביומנים אירועי שגיאה, ביצועים שנכשלו של תהליכי עבודה או בעיות בקומפיילר.
• התראות שמבוססות על מדדים: אפשר להגדיר ערכי סף ב-Cloud Monitoring על סמך משך הביצוע או כשלים בהידור.
• ערוצי התראות: אפשר להגדיר את ההתראות האלה כך שהבעיות יועברו לערוצי התקשורת המועדפים של הצוות