בדף הזה מוסבר על הגדרות ברירת המחדל וההגדרות המותאמות אישית של סוכן Cloud Logging.
רוב המשתמשים לא צריכים לקרוא את הדף הזה. כדאי לקרוא את הדף הזה אם:
אתם רוצים ללמוד פרטים טכניים מעמיקים על ההגדרה של סוכן Cloud Logging.
אתם רוצים לשנות את ההגדרה של סוכן Cloud Logging.
הגדרות ברירת מחדל
הסוכן Logging google-fluentd הוא גרסה שעברה שינוי של כלי איסוף נתוני היומן fluentd.
סוכן Logging מגיע עם הגדרות ברירת מחדל, וברוב המקרים הנפוצים לא נדרשות הגדרות נוספות.
בהגדרת ברירת המחדל שלו, סוכן Logging מעביר יומנים באופן שוטף, כפי שמופיע ברשימת יומני ברירת המחדל, אל Cloud Logging. אפשר להגדיר את הסוכן כך שיזרים יומנים נוספים. פרטים נוספים מופיעים בקטע התאמה אישית של ההגדרות של סוכן Logging בדף הזה.
הסוכן של Logging משתמש בתוספים של קלט fluentd כדי לאחזר ולמשוך יומני אירועים ממקורות חיצוניים, כמו קבצים בדיסק, או כדי לנתח רשומות יומן נכנסות. יישומי פלאגין של קלט מצורפים לסוכן או שאפשר להתקין אותם בנפרד כ-Ruby gems. אפשר לעיין ברשימה של יישומי פלאגין מצורפים.
הסוכן קורא רשומות ביומן שמאוחסנות בקובצי יומן במכונה הווירטואלית באמצעות התוסף המובנה in_tail של fluentd. כל רשומה ביומן מומרת למבנה של רשומה ביומן ב-Cloud Logging. התוכן של כל רשומה ביומן מתועד בעיקר במטען הייעודי של הרשומות ביומן, אבל הרשומות ביומן מכילות גם רכיבים סטנדרטיים כמו חותמת זמן וחומרה. סוכן הרישום ביומן מחייב שכל רשומה ביומן תתויג בתג בפורמט מחרוזת. כל שאילתות הפלאגין ופלאגין הפלט תואמים לקבוצה ספציפית של תגים. שם היומן בדרך כלל בפורמט projects/[PROJECT_ID]/logs/[TAG]. לדוגמה, שם היומן הזה כולל את התג structured-log:
projects/my-sample-project-12345/logs/structured-log
תוסף הפלט משנה כל הודעה מובנית שהועברה ל-Cloud Logging לרשומה ביומן. המטען הייעודי (payload) הופך לטקסט או למטען ייעודי (payload) של JSON.
בקטעים הבאים בדף הזה מוסבר בפירוט על הגדרת ברירת המחדל.
הגדרות ברירת המחדל
בקטעים הבאים מוסבר על הגדרות ברירת המחדל של syslog, על פלאגין הקלט forward, על הגדרות קלט ליומנים של אפליקציות של צד שלישי, כמו אלה שמופיעים ברשימת יומני ברירת המחדל, ועל פלאגין הפלט Google Cloud
fluentd.
מיקום קובץ התצורה של שורש
Linux:
/etc/google-fluentd/google-fluentd.confקובץ התצורה הזה ברמה הבסיסית מייבא גם את כל קובצי התצורה מהתיקייה
/etc/google-fluentd/config.d.ב-Windows:
C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.confאם אתם מפעילים סוכן Logging לפני גרסה 1.5, המיקום הוא:
C:\GoogleStackdriverLoggingAgent\fluent.conf
הגדרת Syslog
מיקומי קובצי התצורה:
/etc/google-fluentd/config.d/syslog.confתיאור: הקובץ הזה כולל את ההגדרה לציון syslog כקלט של יומן.
בודקים את מאגר ההגדרות.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
format |
מחרוזת | /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ |
הפורמט של syslog. |
path |
מחרוזת | /var/log/syslog |
הנתיב של קובץ ה-syslog. |
pos_file |
מחרוזת | /var/lib/google-fluentd/pos/syslog.pos |
הנתיב של קובץ המיקום עבור קלט היומן הזה. fluentd מתעד את המיקום האחרון שנקרא בקובץ הזה. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
read_from_head |
bool | true |
האם להתחיל לקרוא את היומנים מהחלק העליון של הקובץ במקום מהחלק התחתון. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
tag |
מחרוזת | syslog |
תג היומן של קלט היומן הזה. |
הגדרה של פלאגין קלט in_forward
מיקומי קובצי התצורה:
/etc/google-fluentd/config.d/forward.confתיאור: הקובץ הזה כולל את ההגדרה של פלאגין הקלט
in_forwardfluentd. פלאגין הקלטin_forwardמאפשר להעביר יומנים באמצעות שקע TCP.אפשר לעיין ב
fluentdמסמכי התיעוד המפורטים של הפלאגין הזה ובמאגר התצורה.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
port |
int | 24224 |
היציאה שצריך לנטר. |
bind |
מחרוזת | 127.0.0.1 |
כתובת ה-IP שצריך לעקוב אחריה. כברירת מחדל, המערכת מקבלת רק חיבורים מ-localhost. כדי לפתוח את האפשרות הזו, צריך לשנות את ההגדרה ל-0.0.0.0. |
הגדרת קלט של יומן רישום של אפליקציות צד שלישי
מיקומי קובצי התצורה:
/etc/google-fluentd/config.d/[APPLICATION_NAME].confתיאור: הספרייה הזו כוללת קובצי הגדרה שמשמשים לציון קובצי יומן של אפליקציות צד שלישי כקלט ליומן. כל קובץ, למעט
syslog.confו-forward.conf, מייצג אפליקציה אחת (לדוגמה,apache.confלאפליקציית Apache).בודקים את מאגר ההגדרות.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
format1 |
מחרוזת | משתנה לפי אפליקציה | הפורמט של היומן. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
path |
מחרוזת | משתנה לפי אפליקציה | הנתיב של קובצי היומן. אפשר לציין כמה נתיבים, מופרדים באמצעות ','. אפשר לכלול את התו הכללי * ואת פורמטים של strftime כדי להוסיף או להסיר קבצים למעקב באופן דינמי. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
pos_file |
מחרוזת | משתנה לפי אפליקציה | הנתיב של קובץ המיקום עבור קלט היומן הזה. fluentd מתעד את המיקום האחרון שנקרא בקובץ הזה. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
read_from_head |
bool | true |
האם להתחיל לקרוא את היומנים מהחלק העליון של הקובץ במקום מהחלק התחתון. אפשר לעיין fluentdבמסמכי התיעוד המפורטים. |
tag |
מחרוזת | משתנה; שם האפליקציה. | תג היומן של קלט היומן הזה. |
1 אם משתמשים ב-stanza <parse>, צריך לציין את פורמט היומן באמצעות @type.
הגדרת פלאגין הפלטGoogle Cloud fluentd
מיקומי קובצי תצורה:
- Linux:
/etc/google-fluentd/google-fluentd.conf ב-Windows:
C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.confאם אתם מפעילים סוכן Logging לפני גרסה 1.5, המיקום הוא:
C:\GoogleStackdriverLoggingAgent\fluent.conf
- Linux:
Description: הקובץ הזה כולל אפשרויות הגדרה לשליטה בהתנהגות של תוסף הפלטGoogle Cloud
fluentd.עוברים אל מאגר התצורה.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
buffer_chunk_limit |
מחרוזת | 512KB |
כשמתקבלות רשומות ביומן, רשומות שלא ניתן לכתוב לרכיבים במורד הזרם מספיק מהר מועברות לתור של נתחים. בהגדרה הזו מציינים את הגודל המקסימלי של כל נתח. כברירת מחדל, מגבלת הגודל של המקטעים מוגדרת באופן שמרני כדי למנוע חריגה מגודל המקטע המומלץ של 5MB לכל בקשת כתיבה ב-Logging API. רשומות ביומן בבקשת ה-API יכולות להיות גדולות פי 5 עד 8 מגודל היומן המקורי עם כל המטא-נתונים הנוספים שמצורפים אליהן. נתוני באפר נמחקים אם מתקיים אחד משני התנאים הבאים: 1. הגעתם למספר flush_interval. 2. גודל המאגר מגיע ל- buffer_chunk_limit. |
flush_interval |
מחרוזת | 5s |
כשמתקבלות רשומות ביומן, רשומות שלא ניתן לכתוב לרכיבים במורד הזרם מספיק מהר מועברות לתור של נתחים. ההגדרה קובעת כמה זמן יעבור לפני שחלק מאגר ירוקן. נתוני באפר נמחקים אם מתקיים אחד משני התנאים הבאים: 1. הגעתם למספר flush_interval. 2. גודל המאגר מגיע ל- buffer_chunk_limit. |
disable_retry_limit |
bool | false |
הגבלת מספר הניסיונות החוזרים של שטיפת נתונים שנכשלה מתוך חלקי מאגר. אפשר לעיין במפרטים מפורטים ב-retry_limit, ב-retry_wait וב-max_retry_wait. |
retry_limit |
int | 3 |
כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. ההגדרה הזו קובעת כמה ניסיונות חוזרים יתבצעו לפני שחלק בעייתי במאגר יוסר. |
retry_wait |
int | 10s |
כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. ההגדרה הזו קובעת את משך ההמתנה בשניות לפני הניסיון הראשון. מרווח ההמתנה מוכפל בכל ניסיון חוזר (20 שניות, 40 שניות וכו') עד שמגיעים ל-retry_limit או ל-max_retry_wait. |
max_retry_wait |
int | 300 |
כשחלק מהמאגר לא מצליח להתרוקן, fluentd מנסה שוב מאוחר יותר כברירת מחדל. מרווח ההמתנה מוכפל בכל ניסיון חוזר (20 שניות, 40 שניות וכו'). בהגדרה הזו מציינים את מרווח ההמתנה המקסימלי בשניות. אם מגיעים למגבלה הזו של פרק הזמן להמתנה, ההכפלה נפסקת. |
num_threads |
int | 8 |
מספר הפעמים שניתן להריץ בו-זמנית את הפעולה 'ניקוי יומן' באמצעות תוסף הפלט. |
use_grpc |
bool | true |
האם להשתמש ב-gRPC במקום ב-REST/JSON כדי לתקשר עם Logging API. בדרך כלל, השימוש ב-CPU נמוך יותר כש-gRPC מופעל. |
grpc_compression_algorithm |
enum | none |
אם משתמשים ב-gRPC, מגדירים את סכימת הדחיסה שבה רוצים להשתמש. יכול להיות none או gzip. |
partial_success |
bool | true |
האם לתמוך בהצלחה חלקית של הטמעת יומנים. אם true, רשומות יומן לא תקינות בסט מלא נמחקות, ורשומות יומן תקינות מוזנות בהצלחה ל-Logging API. אם false, כל קבוצת הרשומות תימחק אם היא תכיל רשומות לא תקינות. |
enable_monitoring |
bool | true |
כשמגדירים את האפשרות true, סוכן Logging מייצא טלמטריה פנימית. פרטים נוספים זמינים במאמר בנושא טלמטריה של תוסף פלט. |
monitoring_type |
מחרוזת | opencensus |
סוג המעקב. האפשרויות הנתמכות הן opencensus ו-prometheus. פרטים נוספים זמינים במאמר בנושא טלמטריה של תוסף פלט. |
autoformat_stackdriver_trace |
bool | true |
אם הערך הוא true, העקבות יעבור עיצוב מחדש אם הערך של שדה המטען הייעודי המובנה logging.googleapis.com/trace תואם לפורמט ResourceTrace traceId. פרטים על העיצוב האוטומטי מופיעים בקטע שדות מיוחדים במטענים מובְנים בדף הזה. |
הגדרת המעקב
בקטע הזה מתוארת ההגדרה של Cloud Monitoring.
טלמטריה של תוסף הפלט
האפשרות enable_monitoring קובעת אם תוסף הפלט Google Cloud fluentd
יאסוף את נתוני הטלמטריה הפנימיים שלו. אם ההגדרה היא true, סוכן Logging עוקב אחרי מספר רשומות היומן שנדרש לשלוח ל-Cloud Logging, ואחרי המספר בפועל של רשומות היומן שנקלטו ב-Cloud Logging. אם הערך הוא false, פלאגין הפלט לא אוסף מדדים.
האפשרות monitoring_type קובעת איך נתוני הטלמטריה האלה נחשפים על ידי הסוכן. רשימת המדדים מופיעה בהמשך.
אם מגדירים את הערך prometheus, סוכן Logging חושף מדדים בפורמט Prometheus בנקודת הקצה של Prometheus (localhost:24231/metrics כברירת מחדל; לפרטים על התאמה אישית של ההגדרה הזו, אפשר לעיין במאמר הגדרת הפלאגינים prometheus ו-prometheus_monitor). כדי שהמדדים האלה ייכתבו ל-Monitoring API במכונות וירטואליות ב-Compute Engine, צריך להתקין ולהפעיל גם את סוכן Monitoring.
כשההגדרה היא opencensus (ברירת המחדל מגרסה v1.6.25), סוכן ה-Logging כותב ישירות את מדדי הבריאות שלו ל-Monitoring API. לשם כך, צריך להעניק את התפקיד roles/monitoring.metricWriter לחשבון השירות שמשמש כברירת מחדל של Compute Engine, גם אם סוכן Monitoring לא מותקן.
המדדים הבאים נכתבים ל-Monitoring API על ידי סוכן Monitoring וסוכן Logging במצב opencensus:
-
agent.googleapis.com/agent/uptimeעם התוויתversion: זמן הפעולה של סוכן ה-Logging. -
agent.googleapis.com/agent/log_entry_countעם התוויתresponse_code: מספר רשומות ביומן שנכתבו על ידי סוכן Logging. -
agent.googleapis.com/agent/log_entry_retry_countwith aresponse_codelabel: מספר רשומות ביומן שנכתבו על ידי סוכן Logging. -
agent.googleapis.com/agent/request_countעם התוויתresponse_code: מספר בקשות ה-API מסוכן Logging.
תיאורים מפורטים יותר של המדדים האלה מופיעים בדף מדדים של נציגים.
בנוסף, הפלאגין של הפלט חושף את מדדי Prometheus הבאים במצב prometheus:
-
uptimeעם התוויתversion: זמן הפעולה של סוכן ה-Logging. -
stackdriver_successful_requests_countעם התוויותgrpcו-code: מספר הבקשות שהצליחו ל-Logging API. -
stackdriver_failed_requests_countעם התוויותgrpcו-code: מספר הבקשות שנכשלו ב-Logging API, עם פירוט לפי קוד השגיאה. -
stackdriver_ingested_entries_countעם התוויותgrpcו-code: מספר רשומות היומן שנקלטו על ידי Logging API. stackdriver_dropped_entries_countעם תוויותgrpcו-code: מספר רשומות היומן שנדחו על ידי Logging API.-
stackdriver_retried_entries_countעם התוויותgrpcו-code: מספר רשומות היומן שלא נקלטו על ידי Google Cloud תוסף הפלטfluentdבגלל שגיאה זמנית, והיה ניסיון חוזר לקלוט אותן.
הגדרת הפלאגינים prometheus ו-prometheus_monitor
מיקומי קובצי התצורה:
/etc/google-fluentd/google-fluentd.confתיאור: הקובץ הזה כולל אפשרויות הגדרה לשליטה בהתנהגות של התוספים
prometheusו-prometheus_monitor. תוסףprometheus_monitorעוקב אחרי התשתית המרכזית של Fluentd. התוסףprometheusחושף את המדדים, כולל אלה מהתוסףprometheus_monitorואלה מהתוסףgoogle_cloud, באמצעות יציאה מקומית בפורמט Prometheus. מידע נוסף זמין במאמר בנושא מעקב באמצעות Prometheus.עוברים אל מאגר התצורה.
לצורך מעקב אחרי Fluentd, שרת מדדי ה-HTTP המובנה של Prometheus מופעל כברירת מחדל. כדי למנוע הפעלה של נקודת הקצה הזו, אפשר להסיר את הקטע הבא מההגדרה:
# Prometheus monitoring.
<source>
@type prometheus
port 24231
</source>
<source>
@type prometheus_monitor
</source>
עיבוד מטענים ייעודיים (payloads)
רוב היומנים הנתמכים בהגדרת ברירת המחדל של סוכן Logging מגיעים מקובצי יומן, והם מוטמעים כנתוני מטען ייעודי (payload) לא מובנים (טקסט) ברשומות ביומן.
החריג היחיד הוא תוסף הקלט in_forward, שמופעל גם הוא כברירת מחדל. התוסף הזה מקבל רק יומנים מובנים ומעביר אותם כמטענים ייעודיים (payloads) מובנים (JSON) ברשומות היומן. פרטים נוספים מופיעים בקטע הזרמת רשומות יומן מובְנות (JSON) באמצעות הפלאגין in_forward בדף הזה.
אם שורת היומן היא אובייקט JSON שעבר סריאליזציה והאפשרות detect_json מופעלת, תוסף הפלט הופך את רשומת היומן למטען ייעודי (payload) מובנה (JSON). האפשרות הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה גמישה ב-App Engine. האפשרות הזו לא מופעלת כברירת מחדל במופעי מכונה וירטואלית שפועלים בסביבה הרגילה של App Engine. כל קובץ JSON שמנותח כשהאפשרות detect_json מופעלת תמיד ייקלט כ-jsonPayload.
אפשר להתאים אישית את ההגדרות של הסוכן כדי לתמוך בהוספה של יומנים מובנים ממקורות נוספים. פרטים נוספים זמינים במאמר בנושא הזרמת רשומות יומן מובְנות (JSON) אל Cloud Logging.
המטען הייעודי (payload) של רשומות יומן שמוזרמות על ידי סוכן Logging שהוגדר בהתאמה אישית יכול להיות הודעת טקסט לא מובנית יחידה (textPayload) או הודעת JSON מובנית (jsonPayload).
שדות מיוחדים במטען ייעודי (payload) מובנה
כשסוכן Logging מקבל רשומה מובנית ביומן, הוא מעביר כל מפתח שתואם לטבלה הבאה לשדה המתאים באובייקט LogEntry. אחרת, המפתח הופך לחלק מהשדה LogEntry.jsonPayload. ההתנהגות הזו מאפשרת להגדיר שדות ספציפיים באובייקט LogEntry, שזה מה שנכתב ב-Logging API.
לדוגמה, אם רשומת היומן המובנית מכילה מפתח של severity, סוכן Logging מאכלס את השדה LogEntry.severity.
| שדה יומן JSON |
LogEntry
שדה
|
פונקציית הסוכן של Cloud Logging | ערך לדוגמה |
|---|---|---|---|
severity
|
severity
|
הסוכן של Logging מנסה להתאים מגוון של מחרוזות נפוצות של רמת חומרה, כולל הרשימה של מחרוזות LogSeverity שמזוהות על ידי Logging API. | "severity":"ERROR"
|
message
|
textPayload
(או חלק מ-
jsonPayload)
|
ההודעה שמופיעה בשורה של רשומה ביומן בכלי Logs Explorer. | "message":"There was an error in the application." הערה: הערך message נשמר כ-textPayload אם זה השדה היחיד שנשאר אחרי שהסוכן של Logging מעביר את שאר השדות המיוחדים ו
detect_json לא הופעל. אחרת, הערך message נשאר ב-jsonPayload. detect_json לא רלוונטי לסביבות ניהול רישום ביומן כמו Google Kubernetes Engine. אם רשומת היומן מכילה מעקב אחר מחסנית חריגים, צריך להגדיר את המעקב אחר מחסנית החריגים בשדה היומן message בפורמט JSON, כדי שאפשר יהיה לנתח את המעקב אחר מחסנית החריגים ולשמור אותו בדוח שגיאות. |
log
(legacy
Google Kubernetes Engine
only) |
textPayload
|
ההגדרה הזו רלוונטית רק לגרסה הקודמת של Google Kubernetes Engine: אם אחרי העברת שדות מיוחדים נשאר רק שדה log, השדה הזה יישמר בתור textPayload. |
|
httpRequest
|
httpRequest
|
רשומה מובנית בפורמט של השדה LogEntry
HttpRequest. |
"httpRequest":{"requestMethod":"GET"}
|
| שדות שקשורים לזמן | timestamp
|
מידע נוסף זמין במאמר בנושא שדות שקשורים לזמן. | "time":"2025-10-12T07:20:50.52Z"
|
logging.googleapis.com/insertId
|
insertId
|
מידע נוסף זמין במאמר insertId בדף LogEntry. |
"logging.googleapis.com/insertId":"42"
|
logging.googleapis.com/labels
|
labels
|
הערך של השדה הזה
חייב להיות רשומה מובנית.
מידע נוסף זמין במאמר labels בדף LogEntry. |
"logging.googleapis.com/labels":
{"user_label_1":"value_1","user_label_2":"value_2"}
|
logging.googleapis.com/operation
|
operation
|
הערך של השדה הזה משמש גם את הכלי Logs Explorer לקיבוץ של רשומות יומן שקשורות זו לזו.
מידע נוסף זמין במאמר operation בדף LogEntry. |
"logging.googleapis.com/operation":
{"id":"get_data","producer":"github.com/MyProject/MyApplication",
"first":"true"}
|
logging.googleapis.com/sourceLocation
|
sourceLocation
|
מידע על מיקום קוד המקור שמשויך לרשומה ביומן, אם יש כזה.
מידע נוסף זמין במאמר LogEntrySourceLocation בדף LogEntry. |
"logging.googleapis.com/sourceLocation":
{"file":"get_data.py","line":"142","function":"getData"}
|
logging.googleapis.com/spanId
|
spanId
|
מזהה הטווח בתוך
המעקב שמשויך
לרשומה ביומן.
מידע נוסף זמין במאמר spanId בדף LogEntry. |
"logging.googleapis.com/spanId":"000000000000004a"
|
logging.googleapis.com/trace
|
trace
|
שם המשאב של ה-trace שמשויך לרשומה ביומן, אם יש כזה.
מידע נוסף זמין במאמר trace בדף LogEntry.
|
"logging.googleapis.com/trace":"[TRACE_ID]""logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]" הערה: אם לא כותבים אל stdout או אל stderr, צריך להגדיר את הפורמט של השדה הזה כ-[TRACE_ID] או להשתמש בפורמט מדור קודם projects/[PROJECT_ID]/traces/[TRACE_ID]. שני הפורמטים מאפשרים ל-Logs Explorer ול-Trace Explorer לבצע קורלציה בין נתוני יומן לבין נתוני מעקב.
אם הערך של autoformat_stackdriver_trace הוא true והערך של [V] תואם לפורמט של השדה traceId באובייקט ResourceTrace, הערך של השדה trace ב-LogEntry הוא projects/[PROJECT_ID]/traces/[V]. |
logging.googleapis.com/trace_sampled
|
traceSampled
|
הערך בשדה הזה חייב להיות true או false.
מידע נוסף זמין במאמר traceSampled בדף LogEntry. |
"logging.googleapis.com/trace_sampled": false
|
שדות שקשורים לזמן
באופן כללי, מידע שקשור לזמן לגבי רשומה ביומן מאוחסן בשדה timestamp של אובייקט LogEntry:
{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}
כשמקור של רשומה ביומן הוא נתונים מובנים, סוכן Logging משתמש בכללים הבאים כדי לחפש בשדות של הרשומה jsonPayload מידע שקשור לזמן:
מחפשים שדה
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, מעבר להגדרת ברירת המחדל שלו, צריך להמשיך לקרוא את הדף הזה.
אפשרויות הגדרה שקשורות למאגר
אפשרויות ההגדרה הבאות מאפשרות לשנות את מנגנון החיץ הפנימי של סוכן Logging.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
buffer_type |
מחרוזת | buf_memory |
רשומות שלא ניתן לכתוב ל-Logging API מספיק מהר נדחפות למאגר זמני. המאגר יכול להיות בזיכרון או בקבצים. הערך המומלץ: buf_file. ברירת המחדל buf_memory היא מהירה אבל לא מתמשכת. יש סיכון לאובדן יומנים. אם הערך של buffer_type הוא buf_file, צריך לציין גם את buffer_path. |
buffer_path |
מחרוזת | בהגדרת משתמש | הנתיב שבו מאוחסנים מקטעי המאגר. חובה לכלול את הפרמטר הזה אם הערך של buffer_type הוא buf_file. ההגדרה הזו צריכה להיות ייחודית כדי למנוע מרוץ תהליכים. |
buffer_queue_limit |
int | 64 |
מציין את מגבלת האורך של תור המקטעים. כשתור במאגר נתונים זמני (buffer queue) מגיע למגבלה הזו, ההתנהגות של המאגר נשלטת על ידי buffer_queue_full_action. כברירת מחדל, הוא יוצר חריגים. האפשרות הזו, בשילוב עם buffer_chunk_limit, קובעת את נפח הדיסק המקסימלי ש-fluentd יכול לתפוס לצורך אגירת נתונים. |
buffer_queue_full_action |
מחרוזת | exception |
המדיניות הזו קובעת את התנהגות המאגר כשתור במאגר נתונים זמני (buffer queue) מלא. ערכים אפשריים: 1. exception: Throw BufferQueueLimitError כשהתור מלא. האופן שבו המערכת מטפלת ב-BufferQueueLimitError תלוי בתוספי הקלט. לדוגמה, תוסף הקלט in_tail מפסיק לקרוא שורות חדשות, ותוסף הקלט in_forward מחזיר שגיאה. 2. block: במצב הזה, השרשור של תוסף הקלט נעצר עד שהתנאי של המאגר המלא נפתר. הפעולה הזו מתאימה לתרחישי שימוש שדומים להרצת אצווה. fluentd לא ממליצה להשתמש בפעולת החסימה כדי להימנע מ-BufferQueueLimitError. אם אתם נתקלים בשגיאה BufferQueueLimitError לעיתים קרובות, זה אומר שהקיבולת של היעד לא מספיקה לתעבורה שלכם. 3. drop_oldest_chunk: במצב הזה, החלקים הכי ישנים מושמטים. |
אפשרויות הגדרה שקשורות לפרויקט ולמשאבים שבמעקב
אפשרויות ההגדרה הבאות מאפשרות לציין באופן ידני פרויקט ושדות מסוימים מהאובייקט MonitoredResource. הערכים האלה נאספים באופן אוטומטי על ידי סוכן Logging. לא מומלץ לציין אותם באופן ידני.
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
project_id |
מחרוזת | nil | אם מציינים את הפרמטר הזה, הוא מבטל את הפרמטר project_id שמזהה את פרויקט Google Cloud או AWS הבסיסי שבו פועל סוכן Logging. |
zone |
מחרוזת | nil | אם מציינים ערך, הוא מבטל את האזור. |
vm_id |
מחרוזת | nil | אם מציינים ערך, הוא מבטל את מזהה המכונה הווירטואלית. |
vm_name |
מחרוזת | nil | אם מציינים שם, הוא מבטל את שם המכונה הווירטואלית. |
אפשרויות הגדרה אחרות של תוסף פלט
| שם ההגדרה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
detect_json1 |
bool | false |
האם לנסות לזהות אם רשומת היומן היא רשומה ביומן טקסט עם תוכן JSON שצריך לנתח. אם האפשרות הזו היא true, ומזוהה רשומה ביומן לא מובנה (טקסט) בפורמט JSON, היא מנותחת ונשלחת כמטען ייעודי מובנה (JSON). |
coerce_to_utf8 |
bool | true |
האם לאפשר תווים שאינם בתקן UTF-8 ביומני המשתמשים. אם הערך הוא true, כל תו שאינו UTF-8 מוחלף במחרוזת שצוינה על ידי non_utf8_replacement_string. אם הערך הוא false, כל תו שאינו UTF-8 יגרום לשגיאה בתוסף. |
require_valid_tags |
bool | false |
האם לדחות רשומות ביומן עם תגים לא תקינים. אם האפשרות הזו מוגדרת ל-false, התגים הופכים לתקינים על ידי המרה של כל תג שאינו מחרוזת למחרוזת, וניקוי של כל תו שאינו UTF-8 או תו לא תקין אחר. |
non_utf8_replacement_string |
מחרוזת | "" (מחרוזת ריקה) או " "(רווח) |
אם הערך של coerce_to_utf8 הוא true, כל תו שאינו UTF-8 מוחלף במחרוזת שמצוינת כאן. |
1התכונה הזו מופעלת כברירת מחדל במכונות וירטואליות שפועלות בסביבה הגמישה ב-App Engine.
החלת הגדרת סוכן בהתאמה אישית
התאמה אישית של סוכן Logging מאפשרת להוסיף קובצי הגדרה משלכם
fluentd:
מופע של Linux
מעתיקים את קובצי ההגדרות לתיקייה הבאה:
/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.