הגדרת סוכן Logging

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

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

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

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

איך סוכן Logging עובד.

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

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

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

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

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

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

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

  • תיאור: הקובץ הזה כולל אפשרויות הגדרה שקובעות את אופן הפעולה של הפלאגין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. כש-gRPC מופעל, השימוש ב-CPU בדרך כלל נמוך יותר.
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, המערכת משנה את הפורמט של המעקב אם הערך של שדה המטען הייעודי (payload) המובנה logging.googleapis.com/trace תואם לפורמט traceId של ResourceTrace. פרטים על העיצוב האוטומטי מופיעים בקטע שדות מיוחדים במטענים ייעודיים מובְנים שבדף הזה.

הגדרת המעקב

בקטע הזה מוסבר על ההגדרות של 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 עם התווית response_code: מספר רשומות ביומן שנכתבו על ידי סוכן 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>

עיבוד המטען הייעודי (payload)

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

החריג היחיד הוא הפלאגין של הקלט 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).

שדות מיוחדים במטענים מובְנים

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

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

הערה: השדה message נשמר בתור textPayload אם הוא השדה היחיד שנותר אחרי שסוכן הרישום העביר את השדות האחרים למטרות מיוחדות, וגם detect_json לא הופעל. אחרת, השדה message נשאר ב-jsonPayload. השדה detect_json לא רלוונטי לסביבות מנוהלות של רישום ביומן, כמו Google Kubernetes Engine. אם רשומת היומן מכילה דוח קריסות של חריגה, צריך להגדיר את דוח הקריסות של החריגה בשדה היומן message בפורמט JSON, כדי שיהיה אפשר לנתח את דוח הקריסות של החריגה ולשמור אותו ב-Error Reporting.
log (רק ב-Google Kubernetes Engine מדור קודם) 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, הערך של השדה 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, מעבר להגדרות ברירת המחדל, המשיכו לקרוא את הדף הזה.

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

שם ההגדרה סוג ברירת מחדל תיאור
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_full_action. כברירת מחדל, הוא זורק חריגות. האפשרות הזו, בשילוב עם buffer_chunk_limit, קובעת את המקום המקסימלי בכונן ש-fluentd משתמש בו לטעינה מראש.
buffer_queue_full_action מחרוזת exception ההגדרה הזו קובעת את ההתנהגות של מאגר הנתונים הזמני כשהתור במאגר הנתונים הזמני מלא. ‫ערכים אפשריים:
1. ‫exception: הפעלת 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 אם מציינים את השם, הוא מבטל את שם ה-VM.

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

שם ההגדרה סוג ברירת מחדל תיאור
‫detect_json1 bool false האם לנסות לזהות אם רשומת היומן היא רשומת יומן טקסט עם תוכן JSON שצריך לנתח. אם האפשרות הזו היא true, ורשומת יומן לא מובנית (טקסט) מזוהה כפורמט JSON, היא מנותחת ונשלחת כמטען ייעודי (payload) מובנה (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.

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

התאמה אישית של סוכן הרישום מאפשרת להוסיף קובצי תצורה משלכם ל-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 בנושא תחביר של קובצי תצורה.