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

הגדרת המעקב

טלמטריה של פלאגין הפלט

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

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

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

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

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

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

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

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

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

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

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

‫¹התכונה הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה הגמישה של 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 זמין במאמר fluentd's Configuration File Syntax documentation.