ניהול מטא-נתונים ושושלת נתונים של Dataform באמצעות Knowledge Catalog

במאמר הזה מוסבר איך משתמשים ב-Knowledge Catalog כדי לצפות במטא-נתונים של מאגרי Dataform, להוסיף למאגרים הערות עם היבטים ולעקוב אחרי שושלת הנתונים של הפעלות של תהליכי עבודה ב-Dataform.

ב-Knowledge Catalog אתם יכולים לאחסן ולנהל את המטא-נתונים שלכם. כברירת מחדל, מאגרי Dataform זמינים ב-Knowledge Catalog בלי הגדרות נוספות. ‫Knowledge Catalog מאחזר באופן אוטומטי את המטא-נתונים הבאים ממאגרי Dataform:

  • שם נכס הנתונים

  • נכס הורה של נכס נתונים

  • המיקום של נכס הנתונים

  • סוג נכס הנתונים

  • הפרויקט התואם ב- Google Cloud

  • מקור מאגר של צד שלישי

  • חשבון שירות

לפני שמתחילים

  1. בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?

    כניסה לדף לבחירת הפרויקט

  2. מפעילים את Dataplex API ואת Data Lineage API, אם הם עדיין לא מופעלים.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, אתם יכולים לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    הפעלת ממשקי ה-API

  3. מוודאים שיש לכם את ההרשאות הנדרשות לניהול זהויות והרשאות גישה (IAM).

התפקידים הנדרשים

כדי לנהל מאגרים של Dataform ולראות את שושלת הנתונים ב-Knowledge Catalog, אתם צריכים את התפקידים המוגדרים מראש של Dataform שנותנים לכם גישה למשאבים של Dataform, ואת התפקידים הנדרשים של Knowledge Catalog.

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

משימה חשבון משתמש התפקיד הנדרש איפה מקצים את התפקיד
תיעוד שושלת היוחסין מהפעלות של תהליכי עבודה חשבון השירות בהתאמה אישית של המאגר, הגדרת הגרסה או הגדרת תהליך העבודה. אם לא מוגדר חשבון שירות בהתאמה אישית, סוכן השירות של Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com). מפיק אירועים של שושלת נתונים (roles/datalineage.producer) הפרויקט שמכיל את המאגר
תיעוד שושלת נתונים מ-Dataform CLI Application Default Credentials שבהם משתמש ה-CLI יוצר אירועים של שושלת נתונים (roles/datalineage.producer) הפרויקט של כל טבלת פלט
הצגת תרשים השושלת המשתמש שצופה בשושלת היוחסין צפייה בשושלת נתונים (roles/datalineage.viewer) הפרויקט שבו מתועד שושלת היוחסין והפרויקט שבו אתם צופים בשושלת היוחסין
פתיחת Dataform מתרשים השושלת המשתמש שצופה בשושלת היוחסין צפייה ב-Dataform (roles/dataform.viewer), או ההרשאות dataform.repositories.get ו-dataform.workflowInvocations.get הפרויקט שמכיל את המאגר
הצגת פרטי הטבלה ב-BigQuery המשתמש שצופה בשושלת היוחסין BigQuery Data Viewer (roles/bigquery.dataViewer) או ההרשאה bigquery.tables.get הפרויקט שבו מאוחסנת הטבלה
הצגת פרטי המשימה ב-BigQuery המשתמש שצופה בשושלת היוחסין צפייה במשאבים ב-BigQuery (roles/bigquery.resourceViewer) או ההרשאה bigquery.jobs.get הפרויקט שמריץ את המשימה

התפקיד "מפיק אירועים של שושלת נתונים" כולל את ההרשאה datalineage.locations.processOpenLineageMessage, שנדרשת כדי לתעד את שושלת הנתונים.

ניהול מטא-נתונים ב-Knowledge Catalog

מאגרי Dataform מתועדים ב-Knowledge Catalog בתור רשומות עם ערכי הרשומות הבאים:

קבוצת רשומות מערכת
קבוצת הרשומות של המערכת למאגרי Dataform היא @dataform. כדי לראות את הפרטים של רשומות המאגר ב-Knowledge Catalog, צריך להציג את קבוצת הרשומות של המערכת dataform. במאמר הצגת הפרטים של קבוצת רשומות שבמסמכי התיעוד של Knowledge Catalog מוסבר איך להציג רשימה של כל הרשומות בקבוצת רשומות.
סוג רשומה במערכת
סוג הרשומה במערכת של מאגרי Dataform הוא dataform-repository. כדי לראות את הפרטים של מאגרי Dataform, צריך להציג את סוג הרשומה dataform-repository במערכת. במאמר הצגת פרטים של סוג רשומה שבמסמכי התיעוד של Knowledge Catalog מוסבר איך להציג פרטים של סוג רשומה שנבחר. במאמר הצגת פרטים של רשומה במסמכי התיעוד של Knowledge Catalog מוסבר איך להציג פרטים של רשומה שנבחרה.

חיפוש נכסים

במאמר חיפוש נכסי נתונים ב-Knowledge Catalog שבמסמכי התיעוד של Knowledge Catalog מוסבר איך לחפש נכסי נתונים ב-Knowledge Catalog.

הוספת הערות למאגרים

כדי לספק הקשר נוסף למאגרי Dataform ב-Knowledge Catalog, אתם יכולים להוסיף היבטים לרשומות של Dataform.

סוג ההיבט של המערכת למאגרי Dataform הוא dataform-repository.

הוראות להוספת הערות לרשומות באמצעות היבטים מופיעות במאמר ניהול היבטים והעשרת מטא-נתונים במסמכי התיעוד של Knowledge Catalog.

מעקב אחרי שושלת הנתונים ב-Knowledge Catalog

‫Dataform מדווח על שושלת נתונים ל-Knowledge Catalog לגבי הפעולות שהוא מריץ בתהליכי עבודה של Dataform ובצינורות עיבוד נתונים של BigQuery. לכל פעולה שבוצעה, תרשים השושלת ב-Knowledge Catalog וב-BigQuery מציג תהליך של Dataform בין הטבלאות שהפעולה קוראת לבין הטבלה שהיא כותבת. לא צריך לשנות את קובצי ה-SQLX כדי לדווח על שושלת נתונים.

אתם יכולים להשתמש בשושלת הנתונים של Dataform למשימות הבאות:

  • ניתוח ההשפעה: זיהוי כל פעולה וטבלה במורד הזרם לפני שמשנים טבלה.

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

  • משילות: הצגת זרימת הנתונים בין פרויקטים וצינור עיבוד הנתונים שהעביר את הנתונים.

  • שושלת נתונים מקצה לקצה: הצגת שושלת הנתונים של Dataform בתרשים אחד, יחד עם שושלת הנתונים מ-BigQuery, מ-Managed Service for Apache Airflow, מ-Managed Service for Apache Spark ומ-Dataflow.

איך פועל שושלת נתונים

‫Dataform שולח אירוע START של OpenLineage ל-Data Lineage API כשפעולה מתחילה. בסיום הפעולה, Dataform שולח אירוע COMPLETE, FAIL או ABORT. כל פעולה של Dataform מופיעה ב-Knowledge Catalog כתהליך עם סוג המקור BIGQUERY_PIPELINES, וכל הפעלה של הפעולה מופיעה כהרצה של התהליך הזה.

בטבלה הבאה מתוארים סוגי הפעולות ב-Dataform שמדווחים על שושלת:

סוג הפעולה שושלת דוחות
טבלה, תצוגה, טבלה מצטברת, תצוגה מהותית, טענת נכוֹנוּת (assertion), תרשים מאפיינים, הכנת נתונים ופעולה עם hasOutput: true כן. דיווח על קישורי שושלת היוחסין של התהליך, ההרצה והטבלה-לטבלה.
פעולה בלי hasOutput: true עיבוד והפעלה בלבד. הקלט והפלט ריקים, ולכן לא נוצר קישור לשושלת היוחסין בין הטבלאות.
הצהרה לא. הצהרות מופיעות רק כקלט לפעולות אחרות.
‫Notebook, בדיקת יחידה של SQL לא

דיווח על שושלת נתונים אף פעם לא גורם להפעלה של תהליך עבודה להיכשל. אם Data Lineage API מושבת, חסרה הרשאה או חריגה מהמכסה, Dataform מדלג על דיווח שושלת היוחסין וההפעלה של תהליך העבודה נמשכת ללא שינויים.

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

איך תהליכי העבודה של Dataform ממופים לשושלת נתונים

בטבלה הבאה מתואר איך ישויות הביצוע של Dataform ממופות למודל המידע של שושלת הנתונים ב-Knowledge Catalog:

אובייקט שושלת נתונים המקבילה ב-Dataform
תהליך פעולה ב-Dataform
הרצה הפעלה אחת של הפעולה בהפעלה של תהליך עבודה
אירוע שושלת קישור מטבלאות הקלט לטבלת הפלט של ההפעלה הזו

הגדרת שושלת נתונים

כדי להגדיר את Dataform לדיווח על שושלת נתונים, פועלים לפי השלבים הבאים:

  1. מפעילים את Data Lineage API‏ (datalineage.googleapis.com) בפרויקט שמכיל את המאגר של Dataform ובפרויקט שבו המשתמשים צופים בשושלת הנתונים.

  2. בפרויקט שמכיל את המאגר, מקצים את התפקיד "מפיק אירועים של שושלת נתונים" (roles/datalineage.producer) לזהות שמריצה את תהליכי העבודה:

    • אם במאגר, בהגדרת הגרסה או בהגדרת תהליך העבודה משתמשים בחשבון שירות בהתאמה אישית, צריך להקצות את התפקיד לחשבון השירות בהתאמה אישית.

    • אם לא הוגדר חשבון שירות בהתאמה אישית, מקצים את התפקיד לסוכן השירות של Dataform‏ (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com).

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

הפעלה או השבתה של שושלת נתונים

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

כדי לשלוט בדיווח על שושלת נתונים במאגר או בצינור עיבוד נתונים ב-BigQuery, מגדירים את המאפיין lineage.enabled בקובץ workflow_settings.yaml:

  1. נכנסים לדף Dataform במסוף Google Cloud .

    כניסה ל-Dataform

  2. בוחרים מאגר ואז בוחרים סביבת עבודה לפיתוח.

  3. בחלונית Files, פותחים את הקובץ workflow_settings.yaml.

  4. כדי להפעיל דיווח על שושלת נתונים, מוסיפים את הבלוק הבא של lineage:

    lineage:
  enabled: true

    כדי לבטל את הדיווח על שושלת הנתונים במאגר אחרי שהתכונה מופעלת כברירת מחדל, מגדירים את enabled ל-false:

    lineage:
  enabled: false

  5. שומרים ודוחפים את השינויים למאגר.

כדי להפסיק את הדיווח על שושלת הנתונים בפרויקט שלם, צריך להשבית את Data Lineage API בפרויקט. השבתת ה-API גם מפסיקה את הדיווח על שושלת הנתונים משירותים אחרים בפרויקט.

הצגת שושלת הנתונים

כדי להציג את שושלת הנתונים של טבלה שנוצרה על ידי פעולה ב-Dataform, פועלים לפי השלבים הבאים:

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. בחלונית Explorer, מרחיבים את הפרויקט ואת מערך הנתונים, ובוחרים טבלה שנוצרה על ידי פעולה ב-Dataform.

  3. לוחצים על הכרטיסייה Lineage.

  4. כדי לראות את הפעולה, המאגר וההרצות, בוחרים את צומת התהליך של Dataform.

  5. כדי לפתוח את המאגר ב-Dataform, לוחצים על Open in Dataform.

למידע נוסף על ניווט בתרשימי שושלת, ראו הצגת שושלת נתונים ב-Knowledge Catalog.

דיווח על שושלת נתונים מ-Dataform CLI

כדי לדווח על שושלת נתונים מהרצות מקומיות או מהרצות CI של Dataform CLI, מגדירים את lineage.enabled: true ב-workflow_settings.yaml או מריצים את הפקודה הבאה:

dataform run --emit-lineage

הדגלים --emit-lineage ו---no-emit-lineage מבטלים את ההגדרה של lineage.enabled להרצה אחת.

ממשק ה-CLI של Dataform משתמש בApplication Default Credentials ומתעד את שושלת היוחסין בפרויקט של כל טבלת פלט. בכל אחד מהפרויקטים האלה, מפעילים את Data Lineage API ונותנים את התפקיד "יוצר אירועים של שושלת נתונים" (roles/datalineage.producer) לפרטי הכניסה. ה-CLI כותב הודעות שושלת ל-stderr עם הקידומת [lineage].

למידע נוסף על דיווח על שושלת נתונים מ-CLI, ראו הפניית Dataform CLI ב-GitHub.

פתרון בעיות בשושלת נתונים

בטבלה הבאה מתוארות בעיות נפוצות בשושלת נתונים ואיך לפתור אותן:

תיאור הבעיה סיבה אפשרית תיקון
בכרטיסייה Lineage לא מוצגים צמתים של Dataform. ‫Data Lineage API מושבת. מפעילים את ה-API בפרויקט שמכיל את המאגר ובפרויקט שבו רוצים לראות את שושלת היוחסין.
מאגר לא מדווח על שושלת. לזהות שמריצה את תהליך העבודה אין את התפקיד "מפיק אירועים של שושלת יוחסין של נתונים". מקצים את התפקיד roles/datalineage.producer לחשבון השירות בהתאמה אישית או לסוכן השירות של Dataform.
הפעלות של תהליכי עבודה שפועלות עם פרטי כניסה של משתמשים לא מדווחות על שושלת נתונים. דיווח על שושלת יוחסין לא תומך בפרטי כניסה של משתמשים. מריצים את תהליך העבודה עם חשבון שירות בהתאמה אישית.
מאגר לא מדווח על שושלת נתונים למרות שהתפקיד הוקצה. ל-Dataform אין אפשרות לפעול בתור חשבון השירות בהתאמה אישית. מקצים לסוכן השירות של Dataform את התפקיד "יצירת אסימונים בחשבון שירות" (roles/iam.serviceAccountTokenCreator) בחשבון השירות בהתאמה אישית.
מאגר אחד לא מדווח על שושלת נתונים. המאגר לא נכלל. הסרת lineage.enabled: false מהחשבון workflow_settings.yaml.
חסר שושלת יוחסין בחלק מההרצות. חרגתם מהמכסה של Data Lineage API. צריך לפרוס את ההפעלות של תהליך העבודה או לבקש מכסה גדולה יותר.
הפעלות של CLI לא מדווחות על שושלת היוחסין של חלק מהטבלאות. ה-API לא מופעל או שהתפקיד לא הוקצה בפרויקט של טבלת הפלט. מפעילים את ה-API ונותנים את התפקיד בפרויקט הזה.
אם לוחצים על Open in Dataform, מופיעה שגיאת הרשאה. למשתמש אין גישה ל-Dataform. מקצים למשתמש את התפקיד "צפייה ב-Dataform"‏ (roles/dataform.viewer).

אחרי השגיאה הראשונה בהרשאה או ב-API בהפעלה של תהליך עבודה, Dataform מפסיק לדווח על שושלת היוחסין בשאר ההפעלה של תהליך העבודה. ההפעלה הבאה של תהליך העבודה תנסה לדווח שוב על שושלת היוחסין.

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

הצגת יומני שושלת היוחסין של הפעלת תהליך עבודה

ב-Cloud Logging, ‏Dataform כותב רשומות ביומן של שושלת היוחסין ביומן dataform.googleapis.com/lineage_emission. כל רשומה כוללת את השדות workflowInvocationId,‏ actionTarget ו-eventType.

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

  1. במסוף Google Cloud , פותחים את דף הפרטים של הפעלת תהליך העבודה.

  2. לוחצים על הצגת יומנים.

    הכלי Logging ייפתח עם יומנים שמסוננים לפי הפעלת תהליך העבודה על ידי jsonPayload.workflowInvocationId.

השדה outcome בכל רשומת יומן של שושלת נתונים מכיל אחד מהערכים הבאים:

  • ‫SUCCEEDED: האירוע התקבל ב-Data Lineage API. לרשומות האלה יש חומרה DEBUG, והערך של eventType הוא START,‏ COMPLETE,‏ FAIL או ABORT.

  • SKIPPED: המערכת דילגה על הדיווח על שושלת הנתונים ב-Dataform. הרשומות האלה הן ברמת החומרה INFO, והן נרשמות ביומן פעם אחת לכל סיבה בהפעלה של תהליך עבודה. השדה skipReason הוא API_DISABLED,‏ PERMISSION_DENIED,‏ EUC_UNSUPPORTED או AUTHORITY_UNAVAILABLE, והשדה errorMessage מכיל שלבים לתיקון השגיאות.

  • ‫FAILED: הדיווח על שושלת הנתונים נכשל אחרי ניסיונות חוזרים. לרשומות האלה יש חומרה ברמה WARNING והן כוללות את השדות errorCode ו-errorMessage.

כדי לסנן דיווחים על שושלת נתונים שנדלגו או נכשלו ב-Logs Explorer, מריצים את השאילתה הבאה:

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

הודעות על שושלת נתונים מ-CLI של Dataform

ה-CLI של Dataform כותב את הודעות השושלת הבאות ב-stderr:

  • ‫skip_reason=workflow_opt_out: הערך של lineage.enabled מוגדר כ-false.

  • ‫skip_reason=invocation_override: דיווח על שושלת היוחסין מושבת להרצה הזו באמצעות --no-emit-lineage או --emit-lineage=false.

  • ‫skip_reason=dry_run: הרצות בדיקה לא מדווחות על שושלת נתונים.

  • ‫skip_reason=api_disabled: ה-Data Lineage API לא מופעל. ה-CLI לא שולח בקשות נוספות לשושלת היוחסין בהרצה הזו.

  • ‫skip_reason=permission_denied: לפרטי הכניסה אין את התפקיד "מפיק אירועים של שושלת נתונים" (roles/datalineage.producer). ה-CLI לא שולח בקשות נוספות לשושלת נתונים בהרצה הזו.

  • ‫Failed to emit lineage for action ...: דיווח על שושלת נתונים נכשל בפעולה אחת. הדיווח על שושלת היוחסין של פעולות אחרות נמשך.

מגבלות

ניהול מאגרי Dataform ומעקב אחרי שושלת הנתונים ב-Knowledge Catalog כפופים למגבלות הבאות:

  • ב-Knowledge Catalog זמינות רק רשומות ברמת המאגר וברמת תהליך העבודה. נכסי קוד ברמת הקובץ ב-Dataform, כמו קובצי הגדרות SQLX, לא מקוטלגים כרשומות נפרדות.

  • ב-Dataform אפשר לדווח על שושלת יוחסין רק ברמת הטבלה. אין דיווח על שושלת יוחסין ברמת העמודה.

  • הצהרות, תיקיות Notebook ובדיקות יחידה של SQL לא מדווחות על שושלת נתונים. הצהרות מופיעות רק כקלט לפעולות אחרות. פעולות בלי hasOutput: true מדווחות על התהליך ופועלות בלבד, בלי קישורי שושלת יוחסין מטבלה לטבלה.

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

  • הדיווח על שושלת נתונים כפוף למכסות של Data Lineage API לכתיבה לכל פרויקט, זהות ואזור. ברמה הרגילה, המכסה היא כ-1,000 פעולות לדקה.

מיקומים

אתם יכולים להשתמש ב-Knowledge Catalog כדי לנהל מאגרים של Dataform מכל המיקומים של Dataform.

מכסות

ניהול מאגרי Dataform ב-Knowledge Catalog כפוף למכסות ולמגבלות של Knowledge Catalog.

תמחור

ניהול מאגרים של Dataform ב-Knowledge Catalog כפוף לתמחור של Knowledge Catalog.

החיוב על הטמעת שושלת נתונים מתבצע במסגרת המק"ט Knowledge Catalog Premium Processing, ורק אירועים שכותבים קישורים של שושלת נתונים מטבלה לטבלה מחויבים. האחסון של שושלת הנתונים מחויב במסגרת המק"ט של אחסון המטא-נתונים. כדי לשלוט בעלויות של שושלת הנתונים, בטלו את ההצטרפות של תהליכי העבודה ב-workflow_settings.yaml או השביתו את Data Lineage API.

המאמרים הבאים