התאמה אישית של הגדרת סוכן Cloud Logging מאפשרת להעביר ל-Logging יומנים נוספים מקבצים ומאפליקציות של צד שלישי במכונות הווירטואליות (VM). מכיוון שסוכן Logging כולל הגדרת ברירת מחדל שאוספת יומני מערכת ואפליקציות נפוצים, צריך לשנות את ההגדרה שלו רק כשרוצים להתאים אישית את איסוף היומנים או לבדוק איך הסוכן מעבד רשומות ביומן.
הגדרות ברירת מחדל
סוכן Logging google-fluentd הוא גרסה שונה של אוסף נתוני היומן fluentd.
סוכן Logging מגיע עם הגדרת ברירת מחדל. ברוב המקרים הנפוצים, אין צורך בהגדרות נוספות.
בהגדרת ברירת המחדל, סוכן Logging מעביר את היומנים שכלולים ברשימת יומני ברירת המחדל אל Cloud 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_forwardfluentd. פלאגין הקלט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
- Linux:
תיאור: הקובץ הזה כולל אפשרויות הגדרה שקובעות את אופן הפעולה של הפלאגין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 Cloudfluentdבגלל שגיאה זמנית, ובוצע ניסיון חוזר.
הגדרת הפלאגינים 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 מידע שקשור לזמן:
מחפשים שדה
timestampשהוא אובייקט JSON שכולל את השדותsecondsו-nanos, שמייצגים, בהתאמה, מספר חתום של שניות מתקופת ה-UTC ומספר לא שלילי של שניות חלקיות:jsonPayload: { ... "timestamp": { "seconds": CURRENT_SECONDS, "nanos": CURRENT_NANOS } }אם החיפוש הקודם נכשל, מחפשים צמד של שדות
timestampSecondsו-timestampNanos:jsonPayload: { ... "timestampSeconds": CURRENT_SECONDS, "timestampNanos": CURRENT_NANOS }אם החיפוש הקודם נכשל, מחפשים שדה
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
- Linux:
Description: הקובץ הזה כולל אפשרויות הגדרה שקובעות את אופן הפעולה של הפלאגין של הפלט של
fluent-plugin-google-cloud.בודקים את מאגר ההגדרות.
יומני סטרימינג מקלט נוסף
כדי לשלוח יומנים נוספים ל-Logging, אפשר להתאים אישית את סוכן Logging על ידי הוספת הגדרות קלט.
העברת יומנים לא מובנים (טקסט) בסטרימינג באמצעות קובצי יומן
משורת הפקודה של Linux, יוצרים קובץ יומן:
touch /tmp/test-unstructured-log.logיוצרים קובץ תצורה חדש בשם
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במקום ליצור קובץ חדש, אפשר להוסיף את פרטי ההגדרות לקובץ תצורה קיים.
מפעילים מחדש את הסוכן כדי להחיל את השינויים בהגדרות:
sudo service google-fluentd restartיוצרים רשומת יומן בקובץ היומן:
echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.logבודקים ב-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:
משורת הפקודה של Linux, יוצרים קובץ יומן:
touch /tmp/test-structured-log.logיוצרים קובץ תצורה חדש בשם
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במקום ליצור קובץ חדש, אפשר להוסיף את פרטי ההגדרות לקובץ הגדרות קיים.
מפעילים מחדש את הסוכן כדי להחיל את השינויים בהגדרות:
sudo service google-fluentd restartיוצרים רשומת יומן בקובץ היומן:
echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.logבודקים ב-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, קראו את ההוראות הבאות:
מריצים את הפקודה הבאה ב-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בודקים ב-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)
אפשרויות ההגדרה הבאות מאפשרות לכם לשנות את מנגנון אגירת הנתונים הפנימי של סוכן הרישום ביומן.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
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
מעתיקים את קובצי התצורה לספרייה הבאה:
/etc/google-fluentd/config.d/סקריפט ההתקנה של סוכן Logging מאכלס את הספרייה הזו בקובצי התצורה הכוללים של ברירת המחדל. למידע נוסף, קראו את המאמר קבלת קוד המקור של סוכן Logging.
זה שינוי אופציונלי. כדי לאמת את השינוי בהגדרה, מריצים את הפקודה הבאה:
sudo service google-fluentd configtestמפעילים מחדש את הסוכן באמצעות הפקודה הבאה:
sudo service google-fluentd force-reload
מכונה של Windows
מעתיקים את קובצי התצורה לספריית המשנה
config.dשל ספריית ההתקנה של הסוכן. אם אישרתם את ספריית ברירת המחדל להתקנה, הספרייה היא:C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\מפעילים מחדש את הסוכן באמצעות הרצת הפקודות הבאות במעטפת של שורת הפקודה:
net stop StackdriverLogging net start StackdriverLogging
מידע נוסף על קובצי תצורה של fluentd זמין במסמכי התיעוד של fluentd בנושא תחביר של קובצי תצורה.