כתיבת רשומות ביומן והרצת שאילתות באמצעות ה-CLI של gcloud

כתיבת רשומות ביומן והרצת שאילתות באמצעות ה-CLI של gcloud

באמצעות Google Cloud CLI, אתם יכולים לכתוב רשומות ביומן ולשלוח שאילתות לגביהן ב-Cloud Logging משורת הפקודה, כדי לבדוק את הטמעת היומנים ולבחון את נתוני היומנים בלי לכתוב קוד אפליקציה. במדריך למתחילים הזה תלמדו איך לכתוב ולהציג רשומות מובְנות ולא מובְנות ביומן באמצעות ה-CLI של gcloud, להציג רשומות ביומן באמצעות Cloud Logging API, ולצפות ביומנים ולשלוח שאילתות באמצעות Logs Explorer.

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

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

1. התקינו את ה-CLI של Google Cloud.

   הערה: אם התקנתם את ה-CLI של gcloud, השתמשו בפקודה gcloud components update כדי לבדוק אם הגרסה העדכנית מותקנת.

2. הגדירו שה-CLI של gcloud ישתמש בזהות המאוחדת שלכם.

   איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?

3. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

   gcloud init

4. יוצרים או בוחרים פרויקט ב- Google Cloud .

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

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

   • יוצרים פרויקט ב- Google Cloud :

     gcloud projects create PROJECT_ID

     מחליפים את PROJECT_ID בשם של הפרויקט ב- Google Cloud שאתם יוצרים.

   • בוחרים את הפרויקט שיצרתם ב- Google Cloud :

     gcloud config set project PROJECT_ID

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

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

6. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud .

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

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

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

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

כתיבת רשומות ביומן באמצעות ה-CLI של gcloud

ב-Logging אפשר להשתמש ברשומות ביומן עם נתונים מובְנים ולא מובְנים. נתונים מובְנים מורכבים ממבנה נתונים של JSON, לדוגמה: {"weather": "partly cloudy"}. נתונים לא מובְנים הם מחרוזת של תווים, לדוגמה "A simple entry".

בשלבים הבאים תשתמשו ב-CLI של gcloud כדי לכתוב רשומת יומן עם נתונים לא מובְנים ורשומת יומן עם נתונים מובְנים. ה-CLI של gcloud מספק גישה ל-Cloud Logging API באמצעות ממשק שורת הפקודה (CLI).

1. כדי לכתוב רשומה ביומן עם נתונים לא מובנים ביומן my-test-log, מריצים את הפקודה gcloud logging write:

   gcloud logging write my-test-log "A simple entry."
   

   אחרי שהפקודה מסתיימת, מופיעה ההודעה: Created log entry.

2. כתיבת רשומה ביומן עם נתונים מובְנים ביומן my-test-log:

   gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
   

   כשכותבים רשומת יומן עם נתונים מובְנים, צריך לכלול את --payload-type=json. אם משמיטים את השדה הזה, המערכת מפרשת את המטען הייעודי כנתונים לא מובְנים.

אם היומן my-test-log לא קיים, הוא נוצר על ידי Logging כשמתקבלת הרשומה ביומן.

הצגת רשומות ביומן באמצעות ה-CLI של gcloud

אתם יכולים לאחזר רשומות ביומן מ-Logging ולהציג אותן באמצעות ה-CLI של gcloud. לדוגמה, כדי לאחזר ולהציג את רשומות היומן עם סוג המשאב global, מריצים את הפקודה הבאה:

gcloud logging read "resource.type=global"

הפקודה מחזירה תוצאה שדומה לזו:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

למידע על קריאת יומנים, עיינו במאמרי העזרה של gcloud logging read.

הצגת רשומות יומן ב-Logs Explorer

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

כדי לראות את הרשומות ביומן שכתבתם באמצעות Logs Explorer:

1. נכנסים לדף Logs Explorer ב-segment במסוף Google Cloud :

   נכנסים לדף Logs Explorer.

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

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

2. בתפריט Resource בוחרים באפשרות Global.

   אם האפשרות Global לא מופיעה בתפריט או שרשומות היומן לא מופיעות, המתינו כמה דקות ורעננו את הדף. יכול להיות שיעברו כמה דקות עד שרשומות היומן יתקבלו ב-Logging.

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

   הנתונים של רשומת היומן הראשונה מאוחסנים ב-textPayload. רשומת היומן השנייה מכילה נתונים מובְנים שמאוחסנים ב-jsonPayload. המטען הייעודי המובנה מכיל את המפתחות message ו-weather.

   הערה: כש-message הוא מפתח לרשומה ביומן מובנה, מערכת Logging משתמשת בו כסיכום של הרשומה ביומן כשהרשומה לא מורחבת.

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

שליחת שאילתות על רשומות ביומן ב-Logs Explorer

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

1. נכנסים לדף Logs Explorer ב-segment במסוף Google Cloud :

   נכנסים לדף Logs Explorer.

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

2. בתפריט Resource בוחרים באפשרות Global.

3. בעורך השאילתות, מזינים את המחרוזת simple במירכאות. בתצוגת היומנים מופיעה רק רשומת היומן A simple entry.

4. אחרי שצפיתם ביומן, הסירו את מחרוזת השאילתה שהוספתם ולחצו על Run query. שתי הרשומות ביומן מופיעות שוב בתצוגה.

כדי להציג את כל רשומות היומן עם נתונים מובְנים שיש להם מפתח של weather, כאשר השדה value מכיל את הערך partly, מבצעים את הפעולות הבאות:

1. עורך השאילתות מכיל את השורה resource.type="global". מזינים את הפקודה הבאה:

   jsonPayload.weather:partly
   

2. לוחצים על Run query. התוצאה היא רשומת היומן היחידה My second entry.

ב-Logs Explorer יש גם שאילתות שמורות, מוצעות ואחרונות. מידע נוסף על שאילתות זמין במאמר יצירת שאילתות ב-Logs Explorer.

שאילתות לדוגמה מופיעות במאמר שאילתות לדוגמה באמצעות Logs Explorer.

פתרון בעיות

• שגיאות הקלדה ושמות לא ידועים של שדות גורמים לכך שהפקודות של ה-CLI של gcloud מסתיימות בהודעות ארגומנט לא תקין. לדוגמה, אם תשכחו את הנקודה ב-resource.type, תתקבל השגיאה:

   ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
  

• אם ל-Cloud Logging אין את הרשאות הגישה הנדרשות, הפקודות של ה-CLI של gcloud מסתיימות בהודעות permission denied. לדוגמה, אם מכונה וירטואלית של Compute Engine מוגדרת עם הגדרות ברירת המחדל של ה-API, הפקודה list מסתיימת עם שגיאה של דחיית הרשאה:

   ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
  

  כדי לתקן את המצב הזה, צריך לשנות את ההרשאות של מכונת ה-VM ב-Compute Engine ולתת ל-Cloud Logging הרשאת קריאה:

  1. נכנסים לדף VM instance details של המכונה הווירטואלית. לוחצים על הפסקה. הפעולה הזו עשויה להימשך דקה או שתיים.
  2. כדי לשנות את ההגדרות, לוחצים על עריכה.
  3. מחפשים את הכותרת Cloud API access scopes ולוחצים על Details כדי להציג את ההגדרות של כל API. משנים את הערך של Cloud Logging API ל-Full. לוחצים על Save.
  4. כדי להפעיל מחדש את המכונה הווירטואלית, לוחצים על Start. אחרי כמה רגעים, המכונה הווירטואלית מוכנה לשימוש.

הסרת המשאבים

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

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

   gcloud logging logs delete my-test-log
   

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

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

• לפרטים על ממשק שורת הפקודה של Logging, קראו את דפי העזרה של קבוצת הפקודות gcloud logging.
• למידע נוסף על Logging API, קראו את המאמר Cloud Logging API.
• לפרטים על הכלי, קראו את המאמר שימוש ב-Logs Explorer.