הגדרת סוכן Logging

בדף הזה מוסבר על הגדרות ברירת המחדל וההגדרות המותאמות אישית של סוכן Cloud Logging.

רוב המשתמשים לא צריכים לקרוא את הדף הזה. כדאי לקרוא את הדף הזה אם:

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

  • אתם רוצים לשנות את ההגדרה של סוכן Cloud Logging.

הגדרות ברירת מחדל

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

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

איך סוכן הרישום ביומן עובד.

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

הסוכן קורא רשומות ביומן שמאוחסנות בקובצי יומן במכונה הווירטואלית באמצעות התוסף המובנה in_tail של fluentd. כל רשומה ביומן מומרת למבנה של רשומה ביומן ב-Cloud Logging. התוכן של כל רשומה ביומן מתועד בעיקר במטען הייעודי של הרשומות ביומן, אבל הרשומות ביומן מכילות גם רכיבים סטנדרטיים כמו חותמת זמן וחומרה. סוכן הרישום ביומן מחייב שכל רשומה ביומן תתויג בתג בפורמט מחרוזת. כל שאילתות הפלאגין ופלאגין הפלט תואמים לקבוצה ספציפית של תגים. שם היומן בדרך כלל בפורמט projects/[PROJECT_ID]/logs/[TAG]. לדוגמה, שם היומן הזה כולל את התג structured-log:

projects/my-sample-project-12345/logs/structured-log

תוסף הפלט משנה כל הודעה מובנית שהועברה ל-Cloud Logging לרשומה ביומן. המטען הייעודי (payload) הופך לטקסט או למטען ייעודי (payload) של JSON.

בקטעים הבאים בדף הזה מוסבר בפירוט על הגדרת ברירת המחדל.

הגדרות ברירת המחדל

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

מיקום קובץ התצורה של שורש

  • ‫Linux: ‏ /etc/google-fluentd/google-fluentd.conf

    קובץ התצורה הזה ברמה הבסיסית מייבא גם את כל קובצי התצורה מהתיקייה /etc/google-fluentd/config.d.

  • ב-Windows:‏ C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf‎

    אם אתם מפעילים סוכן Logging לפני גרסה 1.5, המיקום הוא: C:\GoogleStackdriverLoggingAgent\fluent.conf

הגדרת Syslog

  • מיקומי קובצי התצורה: /etc/google-fluentd/config.d/syslog.conf

  • תיאור: הקובץ הזה כולל את ההגדרה לציון syslog כקלט של יומן.

  • בודקים את מאגר ההגדרות.

שם ההגדרה סוג ברירת מחדל תיאור
format מחרוזת /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ הפורמט של syslog.
path מחרוזת /var/log/syslog הנתיב של קובץ ה-syslog.
pos_file מחרוזת /var/lib/google-fluentd/pos/syslog.pos הנתיב של קובץ המיקום עבור קלט היומן הזה. ‫fluentd מתעד את המיקום האחרון שנקרא בקובץ הזה. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
read_from_head bool true האם להתחיל לקרוא את היומנים מהחלק העליון של הקובץ במקום מהחלק התחתון. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
tag מחרוזת syslog תג היומן של קלט היומן הזה.

הגדרה של פלאגין קלט in_forward

  • מיקומי קובצי התצורה: /etc/google-fluentd/config.d/forward.conf

  • תיאור: הקובץ הזה כולל את ההגדרה של פלאגין הקלט in_forward fluentd. פלאגין הקלט in_forward מאפשר להעביר יומנים באמצעות שקע TCP.

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

שם ההגדרה סוג ברירת מחדל תיאור
port int 24224 היציאה שצריך לנטר.
bind מחרוזת 127.0.0.1 כתובת ה-IP שצריך לעקוב אחריה. כברירת מחדל, המערכת מקבלת רק חיבורים מ-localhost. כדי לפתוח את האפשרות הזו, צריך לשנות את ההגדרה ל-0.0.0.0.

הגדרת קלט של יומן רישום של אפליקציות צד שלישי

  • מיקומי קובצי התצורה: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

  • תיאור: הספרייה הזו כוללת קובצי הגדרה שמשמשים לציון קובצי יומן של אפליקציות צד שלישי כקלט ליומן. כל קובץ, למעט syslog.conf ו-forward.conf, מייצג אפליקציה אחת (לדוגמה, apache.conf לאפליקציית Apache).

  • בודקים את מאגר ההגדרות.

שם ההגדרה סוג ברירת מחדל תיאור
‫format1 מחרוזת משתנה לפי אפליקציה הפורמט של היומן. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
path מחרוזת משתנה לפי אפליקציה הנתיב של קובצי היומן. אפשר לציין כמה נתיבים, מופרדים באמצעות ','. אפשר לכלול את התו הכללי * ואת פורמטים של strftime כדי להוסיף או להסיר קבצים למעקב באופן דינמי. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
pos_file מחרוזת משתנה לפי אפליקציה הנתיב של קובץ המיקום עבור קלט היומן הזה. ‫fluentd מתעד את המיקום האחרון שנקרא בקובץ הזה. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
read_from_head bool true האם להתחיל לקרוא את היומנים מהחלק העליון של הקובץ במקום מהחלק התחתון. אפשר לעיין fluentdבמסמכי התיעוד המפורטים.
tag מחרוזת משתנה; שם האפליקציה. תג היומן של קלט היומן הזה.

‫1 אם משתמשים ב-stanza‏ <parse>, צריך לציין את פורמט היומן באמצעות @type.

הגדרת פלאגין הפלטGoogle Cloud fluentd

  • מיקומי קובצי תצורה:

    • ‫Linux: ‏ /etc/google-fluentd/google-fluentd.conf
    • ב-Windows:‏ C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf‎

      אם אתם מפעילים סוכן Logging לפני גרסה 1.5, המיקום הוא: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • ‫Description: הקובץ הזה כולל אפשרויות הגדרה לשליטה בהתנהגות של תוסף הפלטGoogle Cloud fluentd.

  • עוברים אל מאגר התצורה.

שם ההגדרה סוג ברירת מחדל תיאור
buffer_chunk_limit מחרוזת 512KB כשמתקבלות רשומות ביומן, רשומות שלא ניתן לכתוב לרכיבים במורד הזרם מספיק מהר מועברות לתור של נתחים. בהגדרה הזו מציינים את הגודל המקסימלי של כל נתח. כברירת מחדל, מגבלת הגודל של המקטעים מוגדרת באופן שמרני כדי למנוע חריגה מגודל המקטע המומלץ של 5MB לכל בקשת כתיבה ב-Logging API. רשומות ביומן בבקשת ה-API יכולות להיות גדולות פי 5 עד 8 מגודל היומן המקורי עם כל המטא-נתונים הנוספים שמצורפים אליהן. נתוני באפר נמחקים אם מתקיים אחד משני התנאים הבאים:
1. הגעתם למספר flush_interval.
‫2. גודל המאגר מגיע ל-buffer_chunk_limit.
flush_interval מחרוזת 5s כשמתקבלות רשומות ביומן, רשומות שלא ניתן לכתוב לרכיבים במורד הזרם מספיק מהר מועברות לתור של נתחים. ההגדרה קובעת כמה זמן יעבור לפני שחלק מאגר ירוקן. נתוני באפר נמחקים אם מתקיים אחד משני התנאים הבאים:
1. הגעתם למספר flush_interval.
‫2. גודל המאגר מגיע ל-buffer_chunk_limit.
disable_retry_limit bool false הגבלת מספר הניסיונות החוזרים של שטיפת נתונים שנכשלה מתוך חלקי מאגר. אפשר לעיין במפרטים מפורטים ב-retry_limit, ‏ ב-retry_wait וב-max_retry_wait.
retry_limit int 3 כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. ההגדרה הזו קובעת כמה ניסיונות חוזרים יתבצעו לפני שחלק בעייתי במאגר יוסר.
retry_wait int 10s כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. ההגדרה הזו קובעת את משך ההמתנה בשניות לפני הניסיון הראשון. מרווח ההמתנה מוכפל בכל ניסיון חוזר (20 שניות, 40 שניות וכו') עד שמגיעים ל-retry_limit או ל-max_retry_wait.
max_retry_wait int 300 כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. מרווח ההמתנה מוכפל בכל ניסיון חוזר (20 שניות, 40 שניות וכו'). בהגדרה הזו מציינים את מרווח ההמתנה המקסימלי בשניות. אם מגיעים למגבלה הזו של פרק הזמן להמתנה, ההכפלה נפסקת.
num_threads int 8 מספר הפעמים שניתן להריץ בו-זמנית את הפעולה 'ניקוי יומן' באמצעות תוסף הפלט.
use_grpc bool true האם להשתמש ב-gRPC במקום ב-REST/JSON כדי לתקשר עם Logging API. בדרך כלל, השימוש ב-CPU נמוך יותר כש-gRPC מופעל.
grpc_compression_algorithm enum none אם משתמשים ב-gRPC, מגדירים את סכימת הדחיסה שבה רוצים להשתמש. יכול להיות none או gzip.
partial_success bool true האם לתמוך בהצלחה חלקית של הטמעת יומנים. אם true, רשומות יומן לא תקינות בסט מלא נמחקות, ורשומות יומן תקינות מוזנות בהצלחה ל-Logging API. אם false, כל קבוצת הרשומות תימחק אם היא תכיל רשומות לא תקינות.
enable_monitoring bool true כשמגדירים את האפשרות true, סוכן Logging מייצא טלמטריה פנימית. פרטים נוספים זמינים במאמר בנושא טלמטריה של תוסף פלט.
monitoring_type מחרוזת opencensus סוג המעקב. האפשרויות הנתמכות הן opencensus ו-prometheus. פרטים נוספים זמינים במאמר בנושא טלמטריה של תוסף פלט.
autoformat_stackdriver_trace bool true אם הערך הוא true, העקבות יעבור עיצוב מחדש אם הערך של שדה המטען הייעודי המובנה logging.googleapis.com/trace תואם לפורמט ResourceTrace traceId. פרטים על העיצוב האוטומטי מופיעים בקטע שדות מיוחדים במטענים מובְנים בדף הזה.

הגדרת המעקב

בקטע הזה מתוארת ההגדרה של Cloud Monitoring.

טלמטריה של תוסף הפלט

האפשרות enable_monitoring קובעת אם תוסף הפלט Google Cloud fluentd יאסוף את נתוני הטלמטריה הפנימיים שלו. אם ההגדרה היא true, סוכן Logging עוקב אחרי מספר רשומות היומן שנדרש לשלוח ל-Cloud Logging, ואחרי המספר בפועל של רשומות היומן שנקלטו ב-Cloud Logging. אם הערך הוא false, פלאגין הפלט לא אוסף מדדים.

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

אם מגדירים את הערך prometheus, סוכן Logging חושף מדדים בפורמט Prometheus בנקודת הקצה של Prometheus (localhost:24231/metrics כברירת מחדל; לפרטים על התאמה אישית של ההגדרה הזו, אפשר לעיין במאמר הגדרת הפלאגינים prometheus ו-prometheus_monitor). כדי שהמדדים האלה ייכתבו ל-Monitoring API במכונות וירטואליות ב-Compute Engine, צריך להתקין ולהפעיל גם את סוכן Monitoring.

כשההגדרה היא opencensus (ברירת המחדל מגרסה v1.6.25), סוכן ה-Logging כותב ישירות את מדדי הבריאות שלו ל-Monitoring API. לשם כך, צריך להעניק את התפקיד roles/monitoring.metricWriter לחשבון השירות שמשמש כברירת מחדל של Compute Engine, גם אם סוכן Monitoring לא מותקן.

המדדים הבאים נכתבים ל-Monitoring API על ידי סוכן Monitoring וסוכן Logging במצב opencensus:

  • ‫agent.googleapis.com/agent/uptime עם התווית version: זמן הפעולה של סוכן ה-Logging.
  • ‫agent.googleapis.com/agent/log_entry_count עם התווית response_code: מספר רשומות ביומן שנכתבו על ידי סוכן Logging.
  • ‫agent.googleapis.com/agent/log_entry_retry_count with a response_code label: מספר רשומות ביומן שנכתבו על ידי סוכן Logging.
  • ‫agent.googleapis.com/agent/request_count עם התווית response_code: מספר בקשות ה-API מסוכן Logging.

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

בנוסף, הפלאגין של הפלט חושף את מדדי Prometheus הבאים במצב prometheus:

  • ‫uptime עם התווית version: זמן הפעולה של סוכן ה-Logging.
  • ‫stackdriver_successful_requests_count עם התוויות grpc ו-code: מספר הבקשות שהצליחו ל-Logging API.
  • ‫stackdriver_failed_requests_count עם התוויות grpc ו-code: מספר הבקשות שנכשלו ב-Logging API, עם פירוט לפי קוד השגיאה.
  • ‫stackdriver_ingested_entries_count עם התוויות grpc ו-code: מספר רשומות היומן שנקלטו על ידי Logging API.
  • stackdriver_dropped_entries_count עם תוויות grpc ו-code: מספר רשומות היומן שנדחו על ידי Logging API.
  • ‫stackdriver_retried_entries_count עם התוויות grpc ו-code: מספר רשומות היומן שלא נקלטו על ידי Google Cloud תוסף הפלט fluentd בגלל שגיאה זמנית, והיה ניסיון חוזר לקלוט אותן.

הגדרת הפלאגינים prometheus ו-prometheus_monitor

  • מיקומי קובצי התצורה: /etc/google-fluentd/google-fluentd.conf

  • תיאור: הקובץ הזה כולל אפשרויות הגדרה לשליטה בהתנהגות של התוספים prometheus ו-prometheus_monitor. תוסף prometheus_monitorעוקב אחרי התשתית המרכזית של Fluentd. התוסף prometheus חושף את המדדים, כולל אלה מהתוסף prometheus_monitor ואלה מהתוסף google_cloud, באמצעות יציאה מקומית בפורמט Prometheus. מידע נוסף זמין במאמר בנושא מעקב באמצעות Prometheus.

  • עוברים אל מאגר התצורה.

לצורך מעקב אחרי Fluentd, שרת מדדי ה-HTTP המובנה של Prometheus מופעל כברירת מחדל. כדי למנוע הפעלה של נקודת הקצה הזו, אפשר להסיר את הקטע הבא מההגדרה:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

עיבוד מטענים ייעודיים (payloads)

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

החריג היחיד הוא תוסף הקלט in_forward, שמופעל גם הוא כברירת מחדל. התוסף הזה מקבל רק יומנים מובנים ומעביר אותם כמטענים ייעודיים (payloads) מובנים (JSON) ברשומות היומן. פרטים נוספים מופיעים בקטע הזרמת רשומות יומן מובְנות (JSON) באמצעות הפלאגין in_forward בדף הזה.

אם שורת היומן היא אובייקט JSON שעבר סריאליזציה והאפשרות detect_json מופעלת, תוסף הפלט הופך את רשומת היומן למטען ייעודי (payload) מובנה (JSON). האפשרות הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה גמישה ב-App Engine. האפשרות הזו לא מופעלת כברירת מחדל במופעי מכונה וירטואלית שפועלים בסביבה הרגילה של App Engine. כל קובץ JSON שמנותח כשהאפשרות detect_json מופעלת תמיד ייקלט כ-jsonPayload.

אפשר להתאים אישית את ההגדרות של הסוכן כדי לתמוך בהוספה של יומנים מובנים ממקורות נוספים. פרטים נוספים זמינים במאמר בנושא הזרמת רשומות יומן מובְנות (JSON) אל Cloud Logging.

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

שדות מיוחדים במטען ייעודי (payload) מובנה

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

שדה יומן 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 שמשויך לרשומה ביומן, אם יש כזה. מידע נוסף זמין במאמר 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, הערך של השדה trace ב-LogEntry הוא projects/[PROJECT_ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled הערך בשדה הזה חייב להיות true או false. מידע נוסף זמין במאמר traceSampled בדף LogEntry. "logging.googleapis.com/trace_sampled": false

שדות שקשורים לזמן

באופן כללי, מידע שקשור לזמן לגבי רשומה ביומן מאוחסן בשדה timestamp של אובייקט LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

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

  1. מחפשים שדה timestamp שהוא אובייקט JSON שכולל את השדות seconds ו-nanos, שמייצגים, בהתאמה, מספר חתום של שניות מאז תקופת ה-UTC ומספר לא שלילי של שניות חלקיות:

    jsonPayload: {
      ...
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  2. אם החיפוש הקודם נכשל, צריך לחפש זוג שדות timestampSeconds ו-timestampNanos:

    jsonPayload: {
      ...
      "timestampSeconds": CURRENT_SECONDS,
      "timestampNanos": CURRENT_NANOS
    }
    
  3. אם החיפוש הקודם נכשל, מחפשים שדה time שהוא מחרוזת בפורמט RFC 3339:

    jsonPayload: {
      ...
      "time": CURRENT_TIME_RFC3339
    }
    

כשסוכן Logging מוצא מידע שקשור לזמן, הוא משתמש במידע הזה כדי להגדיר את הערך של LogEntry.timestamp, והוא לא מעתיק את המידע הזה מהרשומה המובנית לאובייקט LogEntry.jsonPayload.

שדות שקשורים לזמן ולא משמשים להגדרת הערך של השדה LogEntry.timestamp מועתקים מהרשומה המובנית לאובייקט LogEntry.jsonPayload. לדוגמה, אם הרשומה המובנית מכילה אובייקט JSON‏ timestamp ושדה time, הנתונים באובייקט ה-JSON‏ timestamp משמשים להגדרת השדה LogEntry.timestamp. האובייקט LogEntry.jsonPayload מכיל את השדה time כי השדה הזה לא שימש להגדרת הערך LogEntry.timestamp.

התאמה אישית של הגדרות הסוכן

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

הגדרות התצורה שמופיעות בקטעים האלה חלות רק על תוסף הפלט fluent-plugin-google-cloud, ומציינות איך היומנים עוברים טרנספורמציה ומועברים אל Cloud Logging.

  • מיקומים של קובצי תצורה ראשיים:

    • ‫Linux: ‏ /etc/google-fluentd/google-fluentd.conf
    • ב-Windows:‏ C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf‎

      אם אתם מפעילים סוכן Logging לפני גרסה 1.5, המיקום הוא: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • ‫Description: הקובץ הזה כולל אפשרויות הגדרה לשליטה בהתנהגות של תוסף הפלט fluent-plugin-google-cloud.

  • בודקים את מאגר ההגדרות.

יומני סטרימינג מקלט נוסף

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

העברת יומנים לא מובנים (טקסט) בסטרימינג באמצעות קובצי יומן

  1. בשורת הפקודה של Linux, יוצרים קובץ יומן:

    touch /tmp/test-unstructured-log.log
    
  2. יוצרים קובץ הגדרות חדש בשם test-unstructured-log.conf בספריית ההגדרות הנוספות /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
    <source>
        @type tail
        <parse>
            # 'none' indicates the log is unstructured (text).
            @type none
        </parse>
        # The path of the log file.
        path /tmp/test-unstructured-log.log
        # The path of the position file that records the position in the log
        # file that has already been processed. This is useful when the agent
        # restarts.
        pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag unstructured-log
    </source>
    EOF
    

    אפשרות נוספת במקום ליצור קובץ חדש היא להוסיף את פרטי התצורה לקובץ תצורה קיים.

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

    sudo service google-fluentd restart
    
  4. יצירת רשומה ביומן בקובץ היומן:

    echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
    
  5. בודקים ב-Logs Explorer את הרשומה ביומן שהועברה:

    {
      insertId:  "eps2n7g1hq99qp"
      labels: {
      compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/unstructured-log"
      receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
      resource: {
      labels: {
        instance_id:  "3914079432219560274"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      textPayload:  "This is a log from the log file at test-unstructured-log.log"
      timestamp:  "2018-03-21T01:47:05.051902169Z"
    }
    

הזרמת יומנים מובְנים (JSON) באמצעות קובצי יומן

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

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

כדי להגדיר את סוכן Logging כך שיקלוט תוכן בפורמט JSON:

  1. בשורת הפקודה של Linux, יוצרים קובץ יומן:

    touch /tmp/test-structured-log.log
    
  2. יוצרים קובץ הגדרות חדש בשם test-structured-log.conf בספריית ההגדרות הנוספות /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
    <source>
        @type tail
        <parse>
            # 'json' indicates the log is structured (JSON).
            @type json
        </parse>
        # The path of the log file.
        path /tmp/test-structured-log.log
        # The path of the position file that records the position in the log
        # file that has already been processed. 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>
      EOF
    

    אפשרות נוספת במקום ליצור קובץ חדש היא להוסיף את פרטי התצורה לקובץ תצורה קיים.

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

    sudo service google-fluentd restart
    
  4. יצירת רשומה ביומן בקובץ היומן:

    echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
    
  5. בודקים ב-Logs Explorer את הרשומה ביומן שהועברה:

    {
      insertId:  "1m9mtk4g3mwilhp"
      jsonPayload: {
      code:  "structured-log-code"
      message:  "This is a log from the log file at test-structured-log.log"
      }
      labels: {
      compute.googleapis.com/resource_name:  "add-structured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/structured-log"
      receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
      resource: {
      labels: {
        instance_id:  "5351724540900470204"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      timestamp:  "2018-03-21T01:53:39.071920609Z"
    }
    

    בכלי Logs Explorer, מסננים לפי סוג המשאב וlogName של structured-log.

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

הזרמת יומנים מובנים (JSON) באמצעות התוסף in_forward

בנוסף, אפשר לשלוח יומנים באמצעות התוסף fluentd in_forward. ‫fluentd-cat הוא כלי מובנה שעוזר לשלוח יומנים לתוסף in_forward. במאמרי העזרה של fluentd יש פרטים נוספים על הכלי הזה.

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

  1. מריצים את הפקודה הבאה במכונת ה-VM שבה מותקן סוכן ה-Logging:

    echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
    
  2. בודקים ב-Logs Explorer את הרשומה ביומן שהועברה:

    {
      insertId:  "1kvvmhsg1ib4689"
      jsonPayload: {
      code:  "send-log-via-fluent-cat"
      message:  "This is a log from in_forward plugin."
      }
      labels: {
      compute.googleapis.com/resource_name:  "add-structured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
      receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
      resource: {
      labels: {
        instance_id:  "5351724540900470204"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      timestamp:  "2018-03-21T02:11:22.717692494Z"
    }
    

הזרמת רשומות יומן מובנות (JSON) מקוד האפליקציה

אפשר להפעיל מחברים בשפות שונות כדי לשלוח יומנים מוּבְנִים מקוד האפליקציה. מידע נוסף זמין במסמכי fluentd. המחברים האלה מבוססים על התוסף in_forward.

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

אפשרויות ההגדרה הבאות מאפשרות לכם לשנות את התוויות של LogEntry ואת התוויות של MonitoredResource כשמייבאים יומנים ל-Cloud Logging. כל רשומות היומן משויכות למשאבים במעקב. למידע נוסף, אפשר לעיין ברשימה של סוגי המשאבים במעקב ב-Cloud Logging.

שם ההגדרה סוג ברירת מחדל תיאור
label_map hash nil ‫label_map (שמצוין כאובייקט JSON) הוא קבוצה לא מסודרת של שמות שדות fluentd שהערכים שלהם נשלחים כתוויות ולא כחלק מהמטען הייעודי המובנה. כל רשומה במפה היא זוג {field_name: label_name}. כשנתקלים ב-field_name (כפי שמנותח על ידי תוסף הקלט), מתווספת רשומה ליומן עם label_name התואם. הערך של השדה משמש כערך של התווית. המיפוי מאפשר לכם גמישות נוספת בציון שמות התוויות, כולל האפשרות להשתמש בתווים שלא יכולים להיות חלק משמות השדות fluentd. דוגמה מופיעה במאמר בנושא הגדרת תוויות ברשומות יומן מובנות.
labels hash nil ‫labels (מוגדר כאובייקט JSON) הוא קבוצה של תוויות מותאמות אישית שמוגדרות בזמן ההגדרה. התכונה הזו מאפשרת להוסיף מידע סביבתי לכל הודעה או להתאים אישית תוויות שמזוהות באופן אוטומטי. כל רשומה במפה היא זוג {label_name: label_value}.

פלאגין הפלט של סוכן ה-Logging תומך בשלוש דרכים להגדרת תוויות LogEntry:

הגדרת תוויות ברשומות יומן מובנות

נניח שכתבתם מטען ייעודי (payload) של רשומה ביומן מובנה, כמו זה:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

נניח שאתם רוצים לתרגם את שדה המטען הייעודי (payload) env לתווית מטא-נתונים environment. כדי לעשות זאת, מוסיפים את הפרטים הבאים להגדרות של תוסף הפלט בקובץ ההגדרות הראשי (/etc/google-fluentd/google-fluentd.conf ב-Linux או C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf ב-Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

ההגדרה label_map מחליפה את התווית env במטען הייעודי (payload) בתווית environment, כך שרשומת היומן שמתקבלת כוללת את התווית environment עם הערך production.

הגדרת תוויות באופן סטטי

אם המידע הזה לא מופיע במטען הייעודי (payload) ואתם רוצים להוסיף תווית סטטית של מטא נתונים בשם environment, צריך להוסיף את הקוד הבא להגדרת פלאגין הפלט בקובץ ההגדרות הראשי (/etc/google-fluentd/google-fluentd.conf ב-Linux או C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf ב-Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

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

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

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

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

התוסף הנפוץ ביותר לסינון הוא filter_record_transformer. היא מאפשרת לכם:

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

חלק מתוספי הפלט מאפשרים גם לשנות את רשומות היומן. פלאגין הפלט fluent-plugin-record-reformer מספק פונקציונליות דומה לזו של פלאגין המסנן filter_record_transformer, אבל הוא גם מאפשר לשנות תגי יומן. צפוי שימוש רב יותר במשאבים עם הפלאגין הזה: בכל פעם שתג יומן מתעדכן, נוצרת רשומה חדשה ביומן עם התג החדש. שימו לב שהשדה tag בהגדרה הוא שדה חובה. מומלץ גם לשנות את השדה הזה כדי למנוע כניסה ללולאה אינסופית.

תוסף הפלט fluent-plugin-detect-exceptions סורק זרם יומנים, לא מובנה (טקסט) או רשומות יומן בפורמט JSON, כדי למצוא עקבות של מחסנית חריגים מרובת שורות. אם רצף עוקב של רשומות ביומן יוצר דוח קריסה של חריגה, הרשומות ביומן מועברות כהודעת יומן אחת משולבת. אחרת, רשומת היומן מועברת כמו שהיא.

הגדרות מתקדמות (לא ברירת מחדל)

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

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

שם ההגדרה סוג ברירת מחדל תיאור
buffer_type מחרוזת buf_memory רשומות שלא ניתן לכתוב ל-Logging API מספיק מהר נדחפות למאגר זמני. המאגר יכול להיות בזיכרון או בקבצים. הערך המומלץ: buf_file. ברירת המחדל buf_memory היא מהירה אבל לא מתמשכת. יש סיכון לאובדן יומנים. אם הערך של buffer_type הוא buf_file, צריך לציין גם את buffer_path.
buffer_path מחרוזת בהגדרת משתמש הנתיב שבו מאוחסנים מקטעי המאגר. חובה לכלול את הפרמטר הזה אם הערך של buffer_type הוא buf_file. ההגדרה הזו צריכה להיות ייחודית כדי למנוע מרוץ תהליכים.
buffer_queue_limit int 64 מציין את מגבלת האורך של תור המקטעים. כשתור במאגר נתונים זמני (buffer queue) מגיע למגבלה הזו, ההתנהגות של המאגר נשלטת על ידי buffer_queue_full_action. כברירת מחדל, הוא יוצר חריגים. האפשרות הזו, בשילוב עם buffer_chunk_limit, קובעת את נפח הדיסק המקסימלי ש-fluentd יכול לתפוס לצורך אגירת נתונים.
buffer_queue_full_action מחרוזת exception המדיניות הזו קובעת את התנהגות המאגר כשתור במאגר נתונים זמני (buffer queue) מלא. ערכים אפשריים:
1. ‫exception: Throw BufferQueueLimitError כשהתור מלא. האופן שבו המערכת מטפלת ב-BufferQueueLimitError תלוי בתוספי הקלט. לדוגמה, תוסף הקלט in_tail מפסיק לקרוא שורות חדשות, ותוסף הקלט in_forward מחזיר שגיאה.
2. ‫block: במצב הזה, השרשור של תוסף הקלט נעצר עד שהתנאי של המאגר המלא נפתר. הפעולה הזו מתאימה לתרחישי שימוש שדומים להרצת אצווה. ‫fluentd לא ממליצה להשתמש בפעולת החסימה כדי להימנע מ-BufferQueueLimitError. אם אתם נתקלים בשגיאה BufferQueueLimitError לעיתים קרובות, זה אומר שהקיבולת של היעד לא מספיקה לתעבורה שלכם.
3. ‫drop_oldest_chunk: במצב הזה, החלקים הכי ישנים מושמטים.

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

שם ההגדרה סוג ברירת מחדל תיאור
project_id מחרוזת nil אם מציינים את הפרמטר הזה, הוא מבטל את הפרמטר project_id שמזהה את פרויקט Google Cloud או AWS הבסיסי שבו פועל סוכן Logging.
zone מחרוזת nil אם מציינים ערך, הוא מבטל את האזור.
vm_id מחרוזת nil אם מציינים ערך, הוא מבטל את מזהה המכונה הווירטואלית.
vm_name מחרוזת nil אם מציינים שם, הוא מבטל את שם המכונה הווירטואלית.

אפשרויות הגדרה אחרות של תוסף פלט

שם ההגדרה סוג ברירת מחדל תיאור
‫detect_json1 bool false האם לנסות לזהות אם רשומת היומן היא רשומה ביומן טקסט עם תוכן JSON שצריך לנתח. אם האפשרות הזו היא true, ומזוהה רשומה ביומן לא מובנה (טקסט) בפורמט JSON, היא מנותחת ונשלחת כמטען ייעודי מובנה (JSON).
coerce_to_utf8 bool true האם לאפשר תווים שאינם בתקן UTF-8 ביומני המשתמשים. אם הערך הוא true, כל תו שאינו UTF-8 מוחלף במחרוזת שצוינה על ידי non_utf8_replacement_string. אם הערך הוא false, כל תו שאינו UTF-8 יגרום לשגיאה בתוסף.
require_valid_tags bool false האם לדחות רשומות ביומן עם תגים לא תקינים. אם האפשרות הזו מוגדרת ל-false, התגים הופכים לתקינים על ידי המרה של כל תג שאינו מחרוזת למחרוזת, וניקוי של כל תו שאינו UTF-8 או תו לא תקין אחר.
non_utf8_replacement_string מחרוזת ‫"" (מחרוזת ריקה) או " "(רווח) אם הערך של coerce_to_utf8 הוא true, כל תו שאינו UTF-8 מוחלף במחרוזת שמצוינת כאן.

‫1התכונה הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה הגמישה ב-App Engine.

החלת הגדרת סוכן בהתאמה אישית

התאמה אישית של סוכן Logging מאפשרת להוסיף קובצי הגדרה משלכם fluentd:

מופע של Linux

  1. מעתיקים את קובצי ההגדרות לתיקייה הבאה:

    /etc/google-fluentd/config.d/
    

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

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

    sudo service google-fluentd configtest
    
  3. מפעילים מחדש את הסוכן באמצעות הפקודה הבאה:

    sudo service google-fluentd force-reload
    

מכונת Windows

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

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. מפעילים מחדש את הסוכן על ידי הרצת הפקודות הבאות במעטפת של שורת פקודה:

    net stop StackdriverLogging
    net start StackdriverLogging
    

מידע נוסף על קובצי ההגדרות של fluentd זמין במסמכי התיעוד של תחביר קובצי ההגדרות של fluentd.