רישום מובנה ביומן

במאמר הזה נסביר את המושג 'רישום מובנה ביומן' ואת השיטות להוספת מבנה לשדות של מטען ייעודי (payload) ברשומות ביומן. כשמטען ייעודי של יומן מעוצב כאובייקט JSON והאובייקט הזה מאוחסן בשדה jsonPayload, רשומת היומן נקראת יומן מובנה. ביומנים האלה אפשר ליצור שאילתות שמחפשות נתיבי JSON ספציפיים, ולבצע אינדוקס של שדות ספציפיים במטען הייעודי (payload) של היומן. לעומת זאת, אם מטען הייעודי (payload) של היומן מעוצב כמחרוזת ומאוחסן בשדה textPayload, רשומת היומן היא לא מובנית. אפשר לחפש בשדה הטקסט, אבל אי אפשר ליצור אינדקס של התוכן שלו.

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

  • קוראים לשיטת ה-API‏ entries.write ומספקים LogEntry בפורמט מלא.
  • משתמשים בפקודה gcloud logging write.
  • משתמשים בספריית לקוח של Cloud Logging שכותבת יומנים מובנים.
  • משתמשים בשירות BindPlane.

  • שימוש בסוכן לכתיבת יומנים:

    • חלק מה Google Cloud שירותים מכילים סוכן רישום ביומן משולב ששולח את הנתונים שנכתבו ב-stdout או ב-stderr כיומנים ל-Cloud Logging. אפשר להשתמש בגישה הזו Google Cloud בשירותים כמו Google Kubernetes Engine,‏ הסביבה הגמישה של App Engine ופונקציות Cloud Run.

    • במכונות וירטואליות (VM) של Compute Engine, אפשר להתקין ולהגדיר את סוכן תפעול או את סוכן ה-Logging מדור קודם, ואז להשתמש בסוכן שהותקן כדי לשלוח יומנים ל-Cloud Logging.

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

כתיבת יומנים באמצעות ספריות לקוח או ה-API

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

מידע נוסף זמין במאמר בנושא entries.write.

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

כתיבת יומנים באמצעות ה-CLI של gcloud

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

מדריך למתחילים: כתיבה של רשומות ביומן ושאילתות לגביהן באמצעות Google Cloud CLI

דוגמאות קוד מופיעות במאמר בנושא gcloud logging write.

כתיבת יומנים באמצעות BindPlane

אפשר להשתמש בשירות BindPlane כדי לשלוח יומנים אל Logging. במקרה של יומנים כאלה, המטען הייעודי (payload) הוא בפורמט JSON ומובנה בהתאם למערכת המקור. למידע על איתור וצפייה ביומנים שנקלטים באמצעות BindPlane, אפשר לעיין במדריך למתחילים של BindPlane.

כתיבת יומנים באמצעות סוכן

כדי לקבל יומנים מהמכונות של Compute Engine, אפשר להשתמש ב-סוכן תפעול או בסוכן Cloud Logging מדור קודם. שני הסוכנים יכולים לאסוף מדדים מאפליקציות של צד שלישי, ושניהם תומכים ברישום ביומן במבנה:

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

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

  • סוכן Logging מדור קודם של Cloud Logging אוסף יומנים. הסוכן הזה לא אוסף סוגים אחרים של טלמטריה.

החלק הנותר של הקטע הזה מתייחס ספציפית לסוכן Logging מדור קודם.

סוכן Logging: שדות JSON מיוחדים

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

  • severity
  • spanId
  • labels בהגדרת משתמש
  • httpRequest

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

כדי ליצור רשומות יומן מובנות לאפליקציות באמצעות הפורמט הפשוט, אפשר לעיין בטבלה הבאה שבה מפורטים השדות והערכים שלהם ב-JSON:

שדה ביומן JSON LogEntry שדה פונקציית הסוכן של Cloud Logging ערך לדוגמה
severity severity הסוכן של Logging מנסה להתאים מגוון של מחרוזות נפוצות של חומרת הבעיה, כולל הרשימה של מחרוזות LogSeverity שמזוהות על ידי Logging API. "severity":"ERROR"
message textPayload (או חלק מ- jsonPayload) ההודעה שמופיעה בשורת רשומת היומן בכלי Logs Explorer. "message":"There was an error in the application."

הערה: הערך message נשמר כ-textPayload אם זה השדה היחיד שנשאר אחרי שהסוכן Logging מעביר את שאר השדות המיוחדים ו detect_json לא הופעל. אחרת, הערך message נשאר ב-jsonPayload. ‫detect_json לא רלוונטי לסביבות ניהול רישום ביומן כמו Google Kubernetes Engine. אם רשומת היומן מכילה מעקב אחר מחסנית חריגים, צריך להגדיר את המעקב אחר מחסנית החריגים בשדה היומן message בפורמט JSON, כדי שאפשר יהיה לנתח את המעקב אחר מחסנית החריגים ולשמור אותו בדוח שגיאות.
log (legacy Google Kubernetes Engine only) textPayload ההגדרה הזו רלוונטית רק לגרסה הקודמת של Google Kubernetes Engine: אם אחרי העברת שדות מיוחדים נשאר רק שדה log, השדה הזה יישמר בתור textPayload.
httpRequest httpRequest רשומה מובנית בפורמט של השדה LogEntry HttpRequest. "httpRequest":{"requestMethod":"GET"}
שדות שקשורים לזמן timestamp מידע נוסף זמין במאמר בנושא שדות שקשורים לזמן. "time":"2025-10-12T07:20:50.52Z"
logging.googleapis.com/insertId insertId מידע נוסף זמין במאמר insertId בדף LogEntry. "logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels labels הערך בשדה הזה חייב להיות רשומה מובנית. מידע נוסף זמין במאמר labels בדף LogEntry. "logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation operation הערך של השדה הזה משמש גם את הכלי Logs Explorer לקיבוץ רשומות יומן שקשורות זו לזו. מידע נוסף זמין במאמר בנושא operation בדף LogEntry. "logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation sourceLocation מידע על מיקום קוד המקור שמשויך לרשומה ביומן, אם יש כזה. מידע נוסף זמין במאמר LogEntrySourceLocation בדף LogEntry. "logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId spanId מזהה הטווח בתוך המעקב שמשויך לרשומה ביומן. מידע נוסף זמין במאמר spanId בדף LogEntry. "logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace trace שם המשאב של המעקב שמשויך לרשומה ביומן, אם יש כזה. מידע נוסף זמין במאמר trace בדף LogEntry. "logging.googleapis.com/trace":"[TRACE_ID]"
"logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]"

הערה: אם לא כותבים אל stdout או אל stderr, צריך להגדיר את הפורמט של השדה הזה כ-[TRACE_ID] או להשתמש בפורמט מדור קודם projects/[PROJECT_ID]/traces/[TRACE_ID]. שני הפורמטים מאפשרים ל-Logs Explorer ול-Trace Explorer לבצע קורלציה בין נתוני יומן לבין נתוני מעקב. אם הערך של autoformat_stackdriver_trace הוא true והערך של [V] תואם לפורמט של השדה traceId באובייקט ResourceTrace, הערך של השדה LogEntry trace הוא projects/[PROJECT_ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled הערך בשדה הזה חייב להיות true או false. מידע נוסף זמין במאמר traceSampled בדף LogEntry. "logging.googleapis.com/trace_sampled": false

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

הדוגמה הבאה היא של רשומה פשוטה ביומן בפורמט JSON:

{
  "severity":"ERROR",
  "message":"There was an error in the application.",
  "httpRequest":{
    "requestMethod":"GET"
  },
  "time":"2020-10-12T07:20:50.52Z",
  "logging.googleapis.com/insertId":"42",
  "logging.googleapis.com/labels":{
    "user_label_1":"value_1",
    "user_label_2":"value_2"
  },
  "logging.googleapis.com/operation":{
    "id":"get_data",
    "producer":"github.com/MyProject/MyApplication",
    "first":"true"
  },
  "logging.googleapis.com/sourceLocation":{
    "file":"get_data.py",
    "line":"142",
    "function":"getData"
  },
  "logging.googleapis.com/spanId":"000000000000004a",
  "logging.googleapis.com/trace":"projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "logging.googleapis.com/trace_sampled":false
}

דוגמה לרשומה ביומן שמתקבלת:

{
  "insertId": "42",
  "jsonPayload": {
    "message": "There was an error in the application",
    "time": "2020-10-12T07:20:50.52Z"
  },
  "httpRequest": {
    "requestMethod": "GET"
  },
  "resource": {
    "type": "k8s_container",
    "labels": {
      "container_name": "hello-app",
      "pod_name": "helloworld-gke-6cfd6f4599-9wff8",
      "project_id": "stackdriver-sandbox-92334288",
      "namespace_name": "default",
      "location": "us-west4",
      "cluster_name": "helloworld-gke"
    }
  },
  "timestamp": "2020-10-12T07:20:50.52Z",
  "severity": "ERROR",
  "labels": {
    "user_label_2": "value_2",
    "user_label_1": "value_1"
  },
  "logName": "projects/stackdriver-sandbox-92334288/logs/stdout",
  "operation": {
    "id": "get_data",
    "producer": "github.com/MyProject/MyApplication",
    "first": true
  },
  "trace": "projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "sourceLocation": {
    "file": "get_data.py",
    "line": "142",
    "function": "getData"
  },
  "receiveTimestamp": "2020-10-12T07:20:57.52Z",
  "spanId": "000000000000004a"
}

סוכן Logging: הגדרה

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

ב-Fluentd יש רשימה של מנתחי נתונים נתמכים שמחלצים יומנים וממירים אותם למטענים ייעודיים (payloads) מובנים (JSON).

אם מגדירים מקור יומן עם format [PARSER_NAME], אפשר להשתמש במנתחים המובנים ש-Fluentd מספקת. מידע על הגדרת סוכן Logging מדור קודם זמין במאמר הגדרת סוכן Logging.

בדוגמאות הקוד הבאות מוצגת ההגדרה של Fluentd, רשומת יומן הקלט ומטען הייעודי המובנה של הפלט, שהוא חלק מרשומה ביומן של Cloud Logging:

  • הגדרת Fluentd:

      <source>
    @type tail

    format syslog # This uses a predefined log format regex named
                  # `syslog`. See details at https://docs.fluentd.org/parser/syslog.

    path /var/log/syslog
    pos_file /var/lib/google-fluentd/pos/syslog.pos
    read_from_head true
    tag syslog
  </source>

  • רשומה ביומן (קלט):

      <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test

  • מטען ייעודי (פלט) מובנה:

      jsonPayload: {
      "pri": "6",
      "host": "192.168.0.1",
      "ident": "fluentd",
      "pid": "11111",
      "message": "[error] Syslog test"
  }

מידע נוסף על אופן הפעולה של מנתח ה-syslog זמין במסמכי התיעוד המפורטים של Fluentd.

סוכן Logging: מנתחי נתונים רגילים מופעלים כברירת מחדל

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

שם מנתח קובץ תצורה
syslog /etc/google-fluentd/config.d/syslog.conf
nginx /etc/google-fluentd/config.d/nginx.conf
apache2 /etc/google-fluentd/config.d/apache.conf
apache_error /etc/google-fluentd/config.d/apache.conf

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

סוכן Logging: התקנה

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

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

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

אפשר למצוא את קובצי התצורה של סוכן Logging מדור קודם במיקום /etc/google-fluentd/config.d/, שצריך לכלול עכשיו את מנתחים רגילים שמופעלים כברירת מחדל.

סוכן Logging: הגדרת פורמט של יומן גישה של Apache

כברירת מחדל, סוכן Logging מדור קודם שומר נתוני יומן גישה של Apache בשדה jsonPayload. לדוגמה:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

אפשר גם להגדיר את סוכן Logging מדור קודם כדי לחלץ שדות מסוימים לשדה httpRequest. לדוגמה:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

הגדרת השדה httpRequest, כמו בדוגמה הקודמת, עוזרת במעקב: במסוף Google Cloud מוצגים כל היומנים של בקשת HTTP נתונה בהיררכיה של הורה-צאצא.

כדי להגדיר את החילוץ הזה, מוסיפים את הקוד הבא לסוף התג /etc/google-fluentd/config.d/apache.conf:

<filter apache-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
    "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, host, referer
</filter>

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

סוכן Logging: הגדרת פורמט של יומן גישה ל-nginx

כברירת מחדל, סוכן Logging מדור קודם שומר את נתוני יומן הגישה של nginx בשדה jsonPayload. לדוגמה:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "remote":"127.0.0.1",
    "host":"192.168.0.1",
    "user":"some-user",
    "method":"GET",
    "path":"/some-path",
    "code":"200",
    "size":"777",
    "referrer":"some-referrer",
    "agent":"Opera/12.0",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

אפשר גם להגדיר את סוכן Logging מדור קודם כדי לחלץ שדות מסוימים לשדה httpRequest. לדוגמה:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "remoteIp": "127.0.0.1",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

הגדרת השדה httpRequest, כמו בדוגמה הקודמת, עוזרת במעקב: במסוף Google Cloud מוצגים כל היומנים של בקשת HTTP נתונה בהיררכיה של הורה-צאצא.

כדי להגדיר את החילוץ הזה, מוסיפים את הקוד הבא לסוף התג /etc/google-fluentd/config.d/nginx.conf:

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

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

כתיבת מנתח משלכם

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

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

  • שורה ביומן ברשומה ביומן:

    REPAIR CAR $500

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

    $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
$ cat /etc/google-fluentd/config.d/test-structured-log.conf
<source>
  @type tail

  # Format indicates the log should be translated from text to
  # structured (JSON) with three fields, "action", "thing" and "cost",
  # using the following regex:
  format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
  # The path of the log file.
  path /tmp/test-structured-log.log
  # The path of the position file that records where in the log file
  # we have processed already. This is useful when the agent
  # restarts.
  pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
  read_from_head true
  # The log tag for this log input.
  tag structured-log
</source>

  • הרשומה שמתקבלת ביומן:

    {
insertId:  "eps2n7g1hq99qp"
jsonPayload: {
  "action": "REPAIR"
  "thing": "CAR"
  "cost": "500"
}
labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
}
logName:  "projects/my-sample-project-12345/logs/structured-log"
receiveTimestamp:  "2023-03-21T01:47:11.475065313Z"
resource: {
  labels: {
    instance_id:  "3914079432219560274"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
}
timestamp:  "2023-03-21T01:47:05.051902169Z"
}

פתרון בעיות

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

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