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

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

  • כתיבת רשומות ביומן באמצעות Google Cloud CLI.
  • אפשר לרשום את רשומות היומן באמצעות ה-CLI של gcloud.
  • מציגים רשומות ביומן באמצעות Logging API.
  • הצגה של רשומות ביומן והרצת שאילתות באמצעות Logs Explorer.

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

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

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

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

  3. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

    gcloud init

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

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

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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 .

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

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

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

  9. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

    gcloud init

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

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

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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 .

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

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

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

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

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

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

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

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

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

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

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

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

הצגת רשומות ביומן באמצעות APIs Explorer

כדי להריץ methods של Logging API בלי לכתוב קוד, אפשר לעיין במאמר בנושא שימוש ב-APIs Explorer. כדי לקרוא רשימה של רשומות ביומן מ-Logging:

  1. עוברים לדף ההפניה ל-API של ה-method entries.list API:

    לדף API entries.list

  2. מגדירים ומריצים את פקודת ה-API:

    1. מחליפים את PROJECT_ID בטקסט הבא:

      "resourceNames": [
"projects/PROJECT_ID"
],
"filter": "resource.type=global",
"orderBy": "timestamp desc"

    2. מעתיקים את הטקסט המעודכן מהשלב הקודם ומדביקים אותו בשדה Request body (גוף הבקשה) ב-APIs Explorer.

    3. לוחצים על Execute.

    התגובה שמוחזרת מהשיטה דומה לדוגמה הבאה:

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

צפייה ברשומות ביומן בכלי Logs Explorer

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

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

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

    כניסה אל Logs Explorer

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

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

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

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

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

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

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

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

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

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

    כניסה אל Logs Explorer

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

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

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

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

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

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

    jsonPayload.weather:partly

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

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

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

פתרון בעיות

  • שגיאות הקלדה ושמות שדות לא מוכרים גורמים לפקודות של ה-CLI של gcloud להסתיים עם הודעות invalid argument. לדוגמה, אם שכחתם להוסיף את הנקודה ב-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. כדי להפעיל מחדש את מופע ה-VM, לוחצים על התחלה. אחרי כמה רגעים, המכונה הווירטואלית מוכנה לשימוש.

  • אם הכלי APIs Explorer לא מצליח להשלים את הפקודה או שהוא דורש הרשאה נוספת, הוא מציג הודעה או קוד שגיאה:

    • קוד תגובה 200 ואין רשומות: אם מוצגת ההודעה nextPageToken, סימן שלא היה ל-APIs Explorer מספיק זמן להשלים את החיפוש. מוסיפים pageToken לבקשה, מגדירים את הערך שלו כך שיהיה זהה לערך שמופיע עם המפתח nextPageToken, ואז מנסים שוב להריץ את הפקודה.
    • קוד תגובה 400: הערך של השאילתה לא תקין. לדוגמה, אם תכתבו global במקום gloobal, ההודעה תהיה Unsupported resource type: gloobal.
    • קוד תגובה 404: מזהה הפרויקט לא תקין. בודקים את האיות של מזהה הפרויקט.
    • יכול להיות שתתבקשו להיכנס לפרויקטGoogle Cloud ולתת ל-APIs Explorer הרשאה לגשת לחשבון שלכם.

הסרת המשאבים

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

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

    gcloud logging logs delete my-test-log

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

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

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