כתיבת רשומות ביומן והרצת שאילתות באמצעות סקריפט Python

כתיבת רשומות ביומן והרצת שאילתות באמצעות סקריפט Python

במדריך למתחילים הזה נציג כמה מהיכולות של Cloud Logging ונסביר איך:

• כתיבת רשומות ביומן באמצעות סקריפט Python.
• הצגת רשומות ביומן באמצעות סקריפט Python.
• מחיקת רשומות ביומן באמצעות סקריפט Python.
• העברת יומנים לקטגוריה של Cloud Storage.

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

• קטגוריות של Cloud Storage
• מערכי נתונים ב-BigQuery
• Pub/Sub
• קטגוריות ביומן
• Google Cloud פרויקטים

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

כדי להשלים את המדריך הזה, צריך שיהיה לכם פרויקט עם חיוב מופעל. Google Cloud אם אין לכם Google Cloud פרויקט, או אם החיוב לא מופעל ב Google Cloud פרויקט שלכם, צריך לבצע את הפעולות הבאות:

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

במדריך למתחילים הזה נעשה שימוש ב-Cloud Logging וב-Cloud Storage. השימוש במשאבים האלה כרוך בעלויות. כדי להימנע מחיובים נוספים אחרי שסיימתם את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם. פרטים נוספים זמינים בקטע הסרת המשאבים שבדף הזה.

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

כדי לקבל את ההרשאות שדרושות ליצירה, להצגה ולמחיקה של רשומות ביומן וקטגוריות של Cloud Storage, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

• ליצור, להציג ולמחוק רשומות ביומן: אדמין של רישום ביומן (roles/logging.admin)
• יצירה, הצגה ומחיקה של קטגוריות של Cloud Storage: אדמין אחסון (roles/storage.admin)

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

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

התפקידים 'כתיבה ביומנים' (roles/logging.logWriter) ו'צפייה ביומנים' (roles/logging.viewer) כוללים את ההרשאות ליצירה ולרשימה של רשומות ביומן. כדי למחוק רשומות ביומן, צריך להקצות את התפקיד 'אדמין של Logging' (roles/logging.admin), שכולל את ההרשאות ליצור, לרשום ולמחוק רשומות ביומן. שימו לב שהתפקיד Logging Admin ‏(roles/logging.admin) מעניק גם הרשאות לביצוע כל הפעולות ב-Logging.

תחילת העבודה

כדי להשלים את המדריך למתחילים הזה, אפשר להשתמש בסביבת Cloud Shell או בסביבת Linux כללית. ‫Python מותקן מראש ב-Cloud Shell.

Cloud Shell

1. פותחים את Cloud Shell ומאמתים את הגדרות הפרויקט: Google Cloud

   1. במסוף Google Cloud , לוחצים על Activate Cloud Shell.

      ‫Cloud Shell נפתח בחלון ומוצגת הודעת פתיחה.

   2. הודעת הפתיחה משקפת את מזהה הפרויקט שהוגדר Google Cloud . אם זה לא פרויקט Google Cloud שבו רוצים להשתמש, מריצים את הפקודה הבאה אחרי שמחליפים את PROJECT_ID במזהה הפרויקט:

      gcloud config set project PROJECT_ID
      

Linux

1. מוודאים ש-Python מותקן ומוגדר. מידע על הכנת המחשב לפיתוח ב-Python מופיע במאמר בנושא הגדרת סביבת פיתוח ב-Python.

2. מתקינים את ספריית הלקוח של Cloud Logging:

   pip install --upgrade google-cloud-logging
   

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

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

      לדף Service Accounts

      אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שמופיע בה הכותרת המשנית IAM & Admin.

   2. בוחרים את הפרויקט של המדריך המהיר Google Cloud ולוחצים על Create Service Account (יצירת חשבון שירות):

      • מזינים שם לחשבון.
      • מזינים תיאור לחשבון.
      • לוחצים על Create and continue.

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

   4. לוחצים על Done כדי לסיים ליצור את חשבון השירות.

   5. יוצרים קובץ מפתח ומורידים אותו לתחנת העבודה:

      • בחשבון השירות, לוחצים על אפשרויות נוספות ובוחרים באפשרות ניהול מפתחות.
      • בחלונית Keys, לוחצים על Add key.
      • לוחצים על Create new key.

      • בקטע Key type, בוחרים באפשרות JSON ולוחצים על Create. אחרי רגע, בחלון תוצג הודעה דומה לזו שבהמשך:

        

4. בתחנת העבודה שלכם ב-Linux, מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ המפתח כדי לספק את פרטי הכניסה לאימות לאפליקציה. לדוגמה:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"
   

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

מקור השכפול

כדי להגדיר את Cloud Shell בשביל המדריך למתחילים הזה, מבצעים את הפעולות הבאות:

1. משכפלים את הפרויקט ב-GitHub‏ python-logging:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

   הספרייה samples/snippets מכילה את שני הסקריפטים שמשמשים במדריך למתחילים הזה:

   • ‫snippets.py מאפשר לכם לנהל רשומות ביומן.
   • export.py מאפשר לכם לנהל את ייצוא היומנים.

2. עוברים לספרייה snippets:

   cd logging/samples/snippets
   

כתיבת רשומות ביומן

הסקריפט snippets.py משתמש בספריות הלקוח של Python כדי לכתוב רשומות ביומן ל-Logging. כשמציינים את האפשרות write בשורת הפקודה, הסקריפט כותב את רשומות היומן הבאות:

• רשומה עם נתונים לא מובנים ללא רמת חומרה מוגדרת.
• רשומה עם נתונים לא מובְנים ורמת חומרה של ERROR.
• רשומה עם נתונים מובְנים ב-JSON ללא ציון רמת חומרה.

כדי לכתוב רשומות חדשות ביומן my-log, מריצים את הסקריפט snippets.py עם האפשרות write:

python snippets.py my-log write

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

כדי להציג את הרשומות ביומן ב-Cloud Shell, מריצים את הסקריפט snippets.py עם האפשרות list:

python snippets.py my-log list

הפקודה מסתיימת עם התוצאה:

Listing entries for logger my-log:
* 2025-11-13T16:05:35.548471+00:00: Hello, world!
* 2025-11-13T16:05:35.647190+00:00: Goodbye, world!
* 2025-11-13T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

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

אפשר גם להשתמש ב-Logs Explorer כדי לראות את רשומות היומן שכתבתם. פרטים נוספים זמינים במאמר הצגת יומנים באמצעות Logs Explorer.

מחיקת רשומות ביומן

כדי למחוק את כל הרשומות ביומן my-log, מריצים את הסקריפט snippets.py עם האפשרות delete:

python snippets.py my-log delete

הפקודה מסתיימת עם התוצאה:

Deleted all logging entries for my-log.

יומני ניתוב

בקטע הזה תבצעו את הפעולות הבאות:

• יוצרים קטגוריה של Cloud Storage כיעד לנתונים.
• יוצרים מאגר נתונים שמעתיק רשומות חדשות ביומן ליעד.
• מעדכנים את ההרשאות של הקטגוריה ב-Cloud Storage.
• כתיבת רשומות ביומן ל-Logging.
• אפשר גם לאמת את התוכן של הקטגוריה שלכם ב-Cloud Storage.

יצירת יעד

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

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

   כניסה לדף Buckets

   אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Cloud Storage.

2. לוחצים על Create bucket.
3. מזינים שם לקטגוריה. במדריך למתחילים הזה השתמשנו בשם myloggingproject-1.
4. בשדה Location type, בוחרים באפשרות Region כדי לבחור מיקום לקטגוריה עם זמן האחזור הנמוך ביותר.
5. בשדה Set a default class, בוחרים באפשרות Standard.
6. בשדה בקרת גישה, בוחרים באפשרות Fine-grained.
7. בקטע Protection tools (אמצעי הגנה), בוחרים באפשרות None (ללא) ולוחצים על Create (יצירה).

יצירת יעד

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

• שם
• יעד
• מסנן

מידע נוסף על יעד לניתוב יומנים זמין במאמר מידע על יעד לניתוב יומנים.

אם רשומה חדשה ביומן עומדת בתנאי השאילתה, היא מנותבת ליעד.

סקריפט export.py משתמש בספריות לקוח Python כדי ליצור, להציג ברשימה, לשנות ולמחוק יעדים. כדי ליצור את ה-sink mysink שמייצא את כל רשומות היומן עם רמת חומרה של לפחות INFO לקטגוריה של Cloud Storage myloggingproject-1, מריצים את הפקודה הבאה:

python export.py create mysink myloggingproject-1 "severity>=INFO"

הסקריפט מחזיר את הערכים הבאים:

Created sink mysink

כדי לראות את היעדים, מריצים את הסקריפט export.py עם האפשרות list:

python export.py list

הסקריפט מחזיר את הערכים הבאים:

mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

עדכון הרשאות היעד

ההרשאות של היעד, במקרה הזה, קטגוריית Cloud Storage, לא משתנות כשיוצרים מאגר באמצעות הסקריפט export.py. צריך לשנות את הגדרות ההרשאות של הקטגוריה של Cloud Storage כדי לתת הרשאות כתיבה ל-sink. מידע על חשבונות שירות, היקפי גישה ותפקידים בניהול זהויות והרשאות גישה זמין במאמר חשבונות שירות.

כדי לעדכן את ההרשאות בקטגוריה של Cloud Storage:

1. מזהים את זהות הכותב של מאגר היעד:

   1. במסוף Google Cloud , עוברים לדף Log Router:

      כניסה אל Log Router

      אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.

      תוצג טבלת סיכום של מאגרי הנתונים.

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

   3. מעתיקים את זהות הכותב ללוח.

2. נכנסים לדף Buckets במסוף Google Cloud :

   כניסה לדף Buckets

   אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Cloud Storage.

3. כדי לפתוח את התצוגה המפורטת, לוחצים על שם ה-bucket.

4. לוחצים על Permissions (הרשאות) ואז על Grant Access (מתן גישה).

5. מדביקים את זהות הכותב בתיבה New principals. מסירים את הקידומת serviceAccount: מכתובת הזהות של הכותב.

6. מגדירים את התפקיד לערך Storage Admin ולוחצים על שמירה.

מידע נוסף מופיע במאמר בנושא הגדרת הרשאות ליעדים.

אימות יעד

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

1. כתיבת רשומות חדשות ביומן my-log:

   python snippets.py my-log write
   

2. כדי לראות את התוכן של קטגוריה ב-Cloud Storage:

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

      כניסה לדף Buckets

      אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Cloud Storage.

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

      There are no live objects in this bucket.

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

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

      

   3. הנתונים בכל תיקייה מאורגנים בסדרת תיקיות שמתויגות עם שם היומן בתיקייה ברמה העליונה, ולאחר מכן עם השנה, החודש והיום. כדי לראות את הנתונים שיוצאו על ידי יעד הייצוא, לוחצים על שם התיקייה my-log, ואז ממשיכים ללחוץ על תיקיות המשנה של השנה, החודש והיום עד שמגיעים לקובץ שמסתיים ב-json:

      

   4. קובץ ה-JSON מכיל את רשומות היומן שיוצאו לקטגוריה שלכם ב-Cloud Storage. לוחצים על השם של קובץ ה-JSON כדי לראות את התוכן שלו. התוכן דומה ל:

       {"insertId":"yf1cshfoivz48",
       "logName":"projects/loggingproject-222616/logs/my-log",
       "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
       "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
       "severity":"ERROR",
       "textPayload":"Goodbye, world!",
       "timestamp":"2018-11-15T23:06:14.738729911Z"}
      

      כי רמת החומרה של ERROR גבוהה מרמת החומרה של INFO, ולכן רשומת היומן שמכילה את המחרוזת '"Goodbye, world!"' מיוצאת ליעד של מאגר הנתונים. רשומות אחרות ביומן שנכתבו לא יוצאו ליעד כי רמת החומרה שלהן הוגדרה לערך ברירת המחדל, ורמת החומרה של ברירת המחדל נמוכה מ-INFO.

פתרון בעיות

יכולות להיות כמה סיבות לכך שמאגר (bucket) ב-Cloud Storage ריק:

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

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

   [ACTION REQUIRED] Logging export config error in myloggingproject.

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

   bucket_permission_denied

  כדי לתקן את המצב הספציפי הזה, אפשר לעיין בקטע עדכון הרשאות היעד בדף הזה.

• לא נכתבו רשומות ביומן אחרי יצירת היעד. היעד חל רק על רשומות חדשות ביומן. כדי לתקן את המצב הזה, צריך לכתוב רשומות חדשות ביומן:

   python snippets.py my-log write
  

הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם בדף הזה, פועלים לפי השלבים הבאים:

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

   כדי למחוק את כל רשומות היומן ביומן my-log, מריצים את הפקודה הבאה:

    python snippets.py my-log delete
   

2. מחיקה של הפרויקט ב- Google Cloud או מחיקה של המשאבים במדריך למתחילים.

   • כדי למחוק את Google Cloud הפרויקט, בחלונית Project Info במסוףGoogle Cloud לוחצים על Go to project settings ואז על Shut down.

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

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

        python export.py delete mysink
        

     2. מחיקת קטגוריה של Cloud Storage. נכנסים למסוף Google Cloud ולוחצים על Storage > Buckets. מסמנים את התיבה שליד שם הדלי ולוחצים על מחיקה.

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

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