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

ספריית הלקוח של Cloud Logging ל-Python מאפשרת לכם לכתוב, לשלוח שאילתות ולנהל רשומות ביומן באופן פרוגרמטי, כדי שתוכלו לעקוב אחרי האפליקציות שלכם ולפתור בהן בעיות. במדריך למתחילים הזה תשתמשו בסקריפט של Python כדי לכתוב, להציג ולמחוק רשומות ביומן, ותגדירו כיור לניתוב היומנים לקטגוריה של Cloud Storage. בנוסף לקטגוריות של Cloud Storage, אפשר להשתמש ב-Logging כדי לנתב רשומות ביומן למערכי נתונים ב-BigQuery, ל-Pub/Sub, לקטגוריות של Logging ולפרויקטים אחרים ב- Google Cloud .

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

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

  2. 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.

    Go to project selector

  3. 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.

  4. Verify that billing is enabled for your Google Cloud project.

  5. 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.

    Go to project selector

  6. 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.

  7. Verify that billing is enabled for your Google Cloud project.

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

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

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

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

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

התפקידים "כתיבה ביומנים" (roles/logging.logWriter) ו"צפייה ביומנים" (roles/logging.viewer) כוללים את ההרשאות ליצור רשומות ביומן ולהציג אותן. כדי למחוק רשומות ביומן, צריך להקצות את התפקיד "אדמין ב-Logging" (roles/logging.admin), שכולל את ההרשאות ליצור, להציג ולמחוק רשומות ביומן. שימו לב שהתפקיד "אדמין של Logging" (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. לוחצים על השדה Select a role ובוחרים באפשרות Logging Admin.

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

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

      • בחשבון השירות, לוחצים על More options ובוחרים באפשרות Manage keys.
      • בחלונית 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. משכפלים את הפרויקט python-logging ב-GitHub:

    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'}

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

אתם יכולים גם להציג את רשומות היומן שכתבתם באמצעות 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.

יצירת כיור

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

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

מידע נוסף על אובייקטי sink מופיע במאמר מידע על אובייקטי sink ביומן.

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

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

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. כדי לתת הרשאות כתיבה ל-sink, צריך לשנות את הגדרות ההרשאות של הקטגוריה של Cloud Storage. למידע נוסף על חשבונות שירות, היקפי גישה ותפקידים של ניהול זהויות והרשאות גישה, קראו את המאמר חשבונות שירות.

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

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

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

      נכנסים לדף Log Router.

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

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

    2. מאתרים את הכיור בטבלה, לוחצים על Menu ובוחרים באפשרות View sink details.

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

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

    נכנסים לדף Buckets.

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

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

  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. כדי לפתוח את התצוגה המפורטת, לוחצים על שם הקטגוריה. בתצוגה המפורטת מופיעות התיקיות שמכילות נתונים. אם אין נתונים בקטגוריה, תוצג ההודעה הבאה:

      There are no live objects in this bucket.

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

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

      תצוגה מפורטת של תוכן הקטגוריה.

    3. הנתונים בכל תיקייה מאורגנים בסדרה של תיקיות עם תוויות, כשהתיקייה ברמה העליונה מורכבת משם היומן, ואחריו השנה, החודש והיום. כדי לראות את הנתונים שיוצאו על ידי ה-sink, לוחצים על שם התיקייה 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.

פתרון בעיות

יכולות להיות כמה סיבות לכך שקטגוריה של 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. מסמנים את התיבה לצד שם הקטגוריה ולוחצים על Delete.

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