הגדרת סוכן Logging

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הגדרת Syslog

הערה: הגדרת ברירת המחדל הבאה syslog, כחלק מחבילת google-fluentd-catch-all-config, בלעדית למערכות הפעלה של Linux.

• מיקומי קובצי התצורה: /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 הגדרת פלאגין קלט

הערה: הגדרת ברירת המחדל הבאה של הפלאגין in_forward, כחלק מחבילת google-fluentd-catch-all-config, רלוונטית רק למערכות הפעלה של Linux.

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

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

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

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

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

הערה: הגדרת ברירת המחדל הבאה של יומן אפליקציות צד שלישי, כחלק מחבילת google-fluentd-catch-all-config, בלעדית למערכות הפעלה של Linux.

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

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

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

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

‫¹ אם משתמשים בפסקה <parse>, צריך לציין את הפורמט של היומן באמצעות @type.

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

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

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

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

    אם אתם מפעילים סוכן Logging לפני גרסה v1-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	כשמתקבלות רשומות ביומן, רשומות שלא ניתן לכתוב לרכיבים במורד הזרם מספיק מהר מועברות לתור של נתחים. ההגדרה קובעת כמה זמן יעבור עד שנצטרך לרוקן מידע (Flush) את מאגר הנתונים הזמני של חתיכת הנתונים. באפר נמחק אם אחד משני התנאים הבאים מתקיים: 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 מופעל
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. פרטים על העיצוב האוטומטי מופיעים בקטע שדות מיוחדים במטענים מובְנים בדף הזה.

הגדרת המעקב

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

האפשרות 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.

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

בנוסף, הפלאגין output חושף את מדדי 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

הערה: הגדרות ברירת המחדל הבאות של המעקב רלוונטיות רק למערכות הפעלה של Linux.

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

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

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

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

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

עיבוד של מטען ייעודי (payload)

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

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

אם שורת היומן היא אובייקט JSON שעבר סריאליזציה והאפשרות detect_json מופעלת, תוסף הפלט הופך את רשומת היומן למטען ייעודי (payload) מובנה (JSON). האפשרות הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה הגמישה של App Engine וב-Google Kubernetes 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":"2020-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":"projects/my-projectid/traces/0679686673a" הערה: אם לא כותבים ל-stdout או ל-stderr, הערך של השדה הזה צריך להיות בפורמט projects/[PROJECT-ID]/traces/[TRACE-ID], כדי שה-Logs Explorer ומציג העקבות יוכלו להשתמש בו כדי לקבץ רשומות ביומן ולהציג אותן בשורה עם העקבות. אם autoformat_stackdriver_trace הוא true ו-[V] תואם לפורמט של ResourceTrace traceId הערך בשדה LogEntry trace הוא 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 לפני גרסה v1-5, המיקום הוא: C:\GoogleStackdriverLoggingAgent\fluent.conf

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

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

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

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

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

הערה: בקטע הזה יש דוגמה לפקודת Linux. אם אתם משתמשים ב-Windows, תצטרכו להתאים את שלבי הפקודה לסביבה הזו. ‫C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d הוא ספריית ההגדרות של צד שלישי ב-Windows. בנוסף, צריך לוודא שמשתמשים בקו נטוי קדימה (/) בקובץ התצורה של Windows. מידע נוסף על הסיבה לכך שזה נדרש מופיע במאמר תבנית של תו כללי בנתיב לא פועלת ב-Windows.

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 where in the log file
       # we have processed already. 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) באמצעות קובצי יומן

הערה: בקטע הזה יש דוגמה לפקודת Linux. אם אתם משתמשים ב-Windows, תצטרכו להתאים את שלבי הפקודה לסביבה הזו. ‫C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d הוא ספריית ההגדרות של צד שלישי ב-Windows. בנוסף, צריך לוודא שמשתמשים בקו נטוי קדימה (/) בקובץ התצורה של Windows. מידע נוסף על הסיבה לכך שזה נדרש מופיע במאמר תבנית של תו כללי בנתיב לא פועלת ב-Windows.

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

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

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

אפשרויות הגדרה שקשורות למאגר

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

שם ההגדרה	סוג	ברירת מחדל	תיאור
buffer_type	מחרוזת	buf_memory	רשומות שלא ניתן לכתוב ל-Logging API מספיק מהר נדחפות למאגר. המאגר יכול להיות בזיכרון או בקבצים בפועל. הערך המומלץ: buf_file. ברירת המחדל buf_memory היא מהירה אבל לא קבועה. יש סיכון לאובדן יומנים. אם הערך של buffer_type הוא buf_file, צריך לציין גם את buffer_path.
buffer_path	מחרוזת	בהגדרת משתמש	הנתיב שבו מאוחסנים מקטעי המאגר. חובה לכלול את הפרמטר הזה אם הערך של buffer_type הוא 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: השלכת 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. Google Cloud
zone	מחרוזת	nil	אם מציינים את השדה הזה, הוא מבטל את האזור.
vm_id	מחרוזת	nil	אם מציינים את האפשרות הזו, היא מבטלת את מזהה המכונה הווירטואלית.
vm_name	מחרוזת	nil	אם מציינים שם, הוא מבטל את שם המכונה הווירטואלית.

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

שם ההגדרה	סוג	ברירת מחדל	תיאור
‫detect_json^1	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 יוחלף במחרוזת שצוינה כאן.

‫¹התכונה הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה הגמישה של App Engine וב-Google Kubernetes 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

הערה: אם אתם מפעילים גרסת סוכן שקודמת לגרסה v1-5, לא תוכלו להוסיף קובצי הגדרות משלכם. שדרוג לסוכן האחרון.

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

   C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
   

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

   net stop  StackdriverLogging
   net start StackdriverLogging
   

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