מעבר ל-Cloud Logging

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

במדריך הזה מוסבר איך לעדכן את האפליקציה כדי להשתמש ב-Cloud Logging וליהנות כמעט מאותן תכונות של סינון ושל קורלציה של יומנים שהיו זמינות בשילוב של רישום ביומן ב-App Engine.

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

ההבדלים העיקריים

בטבלה הבאה מפורטים ההבדלים ברישום ביומן בין סביבות זמן ריצה מהדור הראשון לבין סביבות זמן ריצה מהדור השני:

	סביבות זמן ריצה מהדור הראשון	זמני ריצה מהדור השני
יומני בקשות ואפליקציות	‫App Engine מטמיע את כל יומני האפליקציה ביומן הבקשות. בזמני הריצה של הדור הראשון, היומנים של האפליקציה מוטמעים בשדה protoPayload.line.logMessage של יומן הבקשות.	יומני האפליקציה לא מוטמעים ביומן הבקשות המשויך ב-App Engine. ‫App Engine משמיט את המאפיין protoPayload.line ביומן הבקשות. יומני האפליקציות מנותבים על סמך שיטת הרישום שלכם: ‫stdout וגם stderr: יומני מסלולים כמו print() עד logs/stdout או logs/stderr. מודול הרישום ביומן של Python אחרי הגדרת הלקוח של Cloud Logging: מעביר את כל היומנים שנכתבו על ידי מודול הרישום ביומן של Python, כמו logging.info() ו-logging.error() אל logs/python. אם ספריית הלקוח של Cloud Logging ל-Python לא מוגדרת לקורלציה, מודול הרישום הבסיסי של Python מנותב אל logs/stderr כברירת מחדל.
צפייה ביומנים בכלי Logs Explorer	סביבות זמן ריצה מהדור הראשון מכילות רק סוג אחד של יומן, appengine.googleapis.com/request_log. כשמרחיבים יומן בקשות, אפשר לראות את יומני האפליקציה שמוצגים מתחתיו.	זמני ריצה מהדור השני כוללים יומנים מכמה סוגים, כמו: יומני בקשות ב-appengine.googleapis.com/request_log,‏ stdout, stderr,‏ logs/python ועוד הרבה, בהתאם לאופן שבו האפליקציה יוצרת יומנים. יומנים פנימיים של Google זמינים גם ב-/var/log/google_init.log. מכיוון שיומני האפליקציות לא משויכים אוטומטית ליומני הבקשות, צריך לבצע שלבים נוספים כדי להציג את התצוגה המקוננת של הבקשות ושל יומני האפליקציות ב-Logs Explorer. מידע נוסף זמין במאמרים הצלבת יומני בקשות עם יומני אפליקציות והצגת יומנים מוצלבים ב-Logs Explorer.
שילוב של Cloud Trace	משולב אוטומטית עם Cloud Trace לאיסוף נתונים של זמן אחזור.	כדי לאסוף נתונים של זמן האחזור מ-App Engine, צריך לשלב את האפליקציה עם Cloud Trace באופן ידני. למידע נוסף, ראו לבצע אינסטרומנטציה עבור Cloud Trace.
מתאם רמת השגיאה	השגיאה שנזרקה מתועדת ביומני הבקשות של App Engine ברמת חומרה של ERROR. Error Reporting מבצע באופן אוטומטי קורלציה בין הפרטים האלה בלוח הבקרה של Error Reporting.	כברירת מחדל, App Engine לא משלב את Error Reporting בסביבות זמן הריצה מהדור השני. כדי להגדיר שילוב של רישום ביומן עם Error Reporting, אפשר לעיין במאמר לבצע אינסטרומנטציה באפליקציות באמצעות ספריות לקוח .
רמת החומרה	כלי Logs Explorer מקצה רמת חומרה ליומני בקשות, ורמת החומרה משקפת את רמת החומרה הגבוהה ביותר של כל רשומה ביומן האפליקציה שקשורה לרשומה ביומן הבקשות. לדוגמה, אם בקשה גורמת לאפליקציה שלכם לפלוט רשומה ביומן אזהרות, בכלי Logs Explorer יוצג סמל אזהרה לצד רשומת היומן של הבקשה. כשמרחיבים את רשומת הבקשה, רואים את רשומת יומן האזהרות שמוטמעת בתוך רשומת הבקשה.	כברירת מחדל, לכל יומני הבקשות יש רמת חומרה של DEFAULT או INFO. גם אם יומני הבקשות קשורים ליומני האפליקציה, ו-Logs Explorer מוגדר להצגת יומנים קשורים, יומני הבקשות לא משקפים את חומרת הבעיות שמופיעות ביומני האפליקציה.
Logservice API	‫Logservice API הוא חלק מ-SDK של שירותים בחבילה.	ה-API של Logservice הוסר מה-SDK של Bundled Services. מידע נוסף זמין ברשימת ממשקי ה-API הזמינים.

לפני שמתחילים בהעברה

1. מפעילים את Cloud Logging API בפרויקט שמכיל את האפליקציה.

   הפעלה של ה-API

2. מוודאים שיש לאפליקציה הרשאה לכתוב יומנים.

   כברירת מחדל, לחשבון השירות שמוגדר כברירת מחדל של האפליקציה יש הרשאה לכתוב יומנים.

   אם האפליקציה שלכם משתמשת בחשבון שירות אחר, או אם שיניתם את ההרשאות של חשבון השירות שמוגדר כברירת מחדל, ודאו שלחשבון שבו אתם משתמשים יש הרשאה logging.logEntries.create לכתוב יומנים.

3. כדאי להכיר את הסוגים השונים של יומנים ב-App Engine.

סקירה כללית של תהליך המיגרציה

כדי להעביר את האפליקציה לשימוש ב-Cloud Logging:

1. התקנת ספריות הלקוח של Cloud לשימוש ב-Cloud Logging
2. כתיבת יומנים באמצעות Cloud Logging
3. הצלבת יומני בקשות עם יומני אפליקציות
4. הצגת היומנים
5. בדיקת האפליקציה

התקנת ספריות הלקוח של Cloud לשימוש ב-Cloud Logging

כדי להתקין ולעדכן את קובצי ההגדרות, מוסיפים את ספריות הלקוח של Cloud ל-Cloud Logging לרשימת התלויות בקובץ requirements.txt, כמו בדוגמה הבאה:

google-cloud-logging

כתיבת יומנים באמצעות מודול הרישום ביומן של Python

בכל קובץ שכותב רשומות ביומן:

1. מייבאים את ספריית הלקוח של Cloud Logging.
2. יוצרים מופע של לקוח Cloud Logging.
3. מריצים את ה-method‏ setup_logging() של לקוח Cloud Logging, שמצרף את מאזין ברירת המחדל שלו כגורם handler של רישום ביומן עבור רשומת השורש ביומן של Python.

לדוגמה:

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

אחרי שמצרפים את ה-handler, כל היומנים ברמה INFO ומעלה שמופקים באפליקציה יישלחו ל-Logging כברירת מחדל:

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

ביצוע קורלציה בין יומני בקשות לבין יומני אפליקציות

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

אפליקציות שמשתמשות בסביבות זמן ריצה מהדור השני יכולות להשיג התנהגות דומה של רישום ביומן (logging) כמו בסביבות זמן ריצה מהדור הראשון, באחת מהדרכים הבאות:

• הגדרת לקוח Cloud Logging באפליקציה והתאמת יומנים.
• שימוש במזהה trace עם stdout ו-stderr.

התנהגות הרישום ביומנים בסביבות זמן ריצה מהדור הראשון ומהדור השני שונה בדרכים הבאות:

• בסביבות זמן ריצה מהדור הראשון, App Engine מטמיע את כל יומני האפליקציות שנוצרו במהלך הטיפול בבקשה בשדה protoPayload.line.logMessage של יומן הבקשות. היומנים האלה מוצגים ב-Logs Explorer דרך appengine.googleapis.com/request_log.

  בתמונה הבאה מוצגים יומני בקשות ויומני אפליקציות עם קורלציה בסביבות זמן הריצה מהדור הראשון:

  

• בסביבות ריצה מהדור השני, App Engine משמיט את המאפיין protoPayload.line ביומן הבקשות. התוכן של יומני האפליקציות לא מופיע ביומני הבקשות בפורמט JSON ב-Logs Explorer. כל יומן אפליקציה יופיע בנפרד לפי שם היומן ב-Logs Explorer.

  בתמונה הבאה מוצגים יומני בקשות ויומני אפליקציות נפרדים בסביבות זמן הריצה מהדור השני:

  

בקטעים הבאים מוסבר איך להשתמש בלקוח Cloud Logging או ביומנים מובנים עם stdout ו-stderr כדי ליצור קורלציה בין יומנים.

שימוש במודול הרישום ביומן של Python

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

כשמריצים את ה-method‏ client.setup_logging() בהפעלת האפליקציה, ה-method הזה מוסיף את השדה trace ואת פרטי בקשת ה-HTTP ליומני האפליקציה שנכתבים על ידי מודול Python‏ logging, כמו logging.info() ו-logging.error(). היומנים האלה מנותבים אל logs/python.

‫App Engine גם מוסיף את השדה trace הזה ליומן הבקשות המשויך, וכך אפשר לראות את רשומות היומן שקשורות זו לזו ב-Log Explorer.

שימוש ב-stdout וב-stderr

אם משתמשים בפונקציות stdout ו-stderr כדי לכתוב רשומות ביומן, הרשומות האלה מופיעות בכלי Logs Explorer. עם זאת, כדי להפעיל סינון ומתאם עם יומני בקשות, צריך לעצב את הרשומות כאובייקט JSON ולספק מטא-נתונים ספציפיים. מידע נוסף על הגישה הזו זמין במאמר כתיבת יומנים מובְנים ל-stdout ול-stderr. הגישה הזו מוסיפה את מזהה המעקב של הבקשה ביומני האפליקציה באופן הבא:

1. שליפת מזהה המעקב מכותרת הבקשה X-Cloud-Trace-Context.
2. כתיבת המזהה לשדה בשם logging.googleapis.com/trace ברשומה המובנית ביומן. מידע נוסף על הכותרת X-Cloud-Trace-Context זמין במאמר הפעלת מעקב אחרי בקשה.

צפייה ביומנים

יש כמה דרכים לצפות ביומני האפליקציות וביומני הבקשות:

• שימוש ב-Logs Explorer מ-Cloud Logging במסוף Google Cloud .
• משתמשים ב-Google Cloud CLI כדי להציג יומנים באמצעות gcloud.
• קריאת יומנים באופן פרוגרמטי באמצעות שיטות שונות.

שימוש ב-Logs Explorer

אתם יכולים לראות את היומנים של האפליקציה והבקשות באמצעות Logs Explorer:

1. נכנסים אל Logs Explorer במסוף Google Cloud :

   כניסה לדף Logs Explorer

2. בוחרים פרויקט קיים Google Cloud בחלק העליון של הדף.

3. בקטע Resource Type, בוחרים באפשרות GAE Application.

אפשר לסנן את Logs Explorer לפי שירות App Engine, גרסה וקריטריונים אחרים. אפשר גם לחפש ביומנים רשומות ספציפיות. פרטים נוספים מופיעים במאמר בנושא שימוש ב-Logs Explorer.

אם שולחים רשומות טקסט פשוטות לפלט רגיל, אי אפשר להשתמש בכלי Logs Viewer כדי לסנן רשומות של אפליקציות לפי חומרה, וגם אי אפשר לראות אילו יומנים של אפליקציות תואמים לבקשות ספציפיות. עדיין אפשר להשתמש בסוגים אחרים של סינון בכלי Logs Explorer, כמו סינון לפי טקסט וחותמת זמן.

צפייה ברשומות יומן שקשורות זו לזו ב-Logs Explorer

כדי להציג ב-Logs Explorer את רשומות היומן של הצאצא שקשורות לרשומת יומן של ההורה, מרחיבים את רשומת היומן.

לדוגמה, כדי להציג את הרשומה ביומן הבקשות של App Engine ואת הרשומות ביומן האפליקציה:

1. בחלונית הניווט של מסוף Google Cloud , בוחרים באפשרות Logging ואז באפשרות Logs Explorer:

   כניסה לדף Logs Explorer

2. בקטע Resource Type, בוחרים באפשרות GAE Application.

3. כדי להציג יומני בקשות ולבצע ביניהם קורלציה, בוחרים באפשרות request_log בשם היומן. לחלופין, כדי לבצע קורלציה לפי יומני בקשות, לוחצים על Correlate by (קורלציה לפי) ובוחרים באפשרות request_log (יומן בקשות).

   

4. בחלונית Query results, כדי להרחיב רשומה ביומן, לוחצים על Expand. כשמרחיבים את יומן הבקשות, מוצגים יומני האפליקציות שמשויכים אליו.

אחרי שיוצרים מסנן ליומנים, כל יומן בקשות מציג יומני אפליקציות תואמים כיומני צאצא. כדי לעשות את זה, Logs Explorer מבצע קורלציה בין השדה trace ביומני האפליקציה לבין יומן בקשות נתון, בהנחה שהאפליקציה משתמשת בספרייה google-cloud-logging.

בתמונה הבאה מוצגים יומני אפליקציות שמקובצים לפי השדה trace:

שימוש ב-Google Cloud CLI

כדי לראות את היומנים של App Engine משורת הפקודה, משתמשים בפקודה הבאה:

gcloud app logs tail

מידע נוסף זמין במאמר בנושא gcloud app logs tail.

קריאת יומנים באופן פרוגרמטי

אם רוצים לקרוא את היומנים באופן פרוגרמטי, אפשר להשתמש באחת מהשיטות הבאות:

• משתמשים בsink ביומן ב-Pub/Sub ובסקריפט כדי לשלוף נתונים מ-Pub/Sub.
• מפעילים את Cloud Logging API באמצעות ספריית הלקוח של שפת התכנות שלכם.
• קריאה ישירה לנקודות הקצה של Cloud Logging API REST.

בדיקת האפליקציה

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

1. עוברים אל Logs Explorer ומרחיבים רשומה ביומן בקשות.

   כניסה לדף Logs Explorer

2. מוודאים שיומני האפליקציה שנוצרו על ידי האפליקציה במהלך עיבוד בקשה מוטמעים ביומן הבקשות.

3. אם כל נקודות הקצה של האפליקציה פועלות כמצופה, משתמשים בפיצול תנועה כדי להגביר בהדרגה את התנועה לאפליקציה המעודכנת. חשוב לעקוב מקרוב אחרי האפליקציה כדי לזהות בעיות לפני שמפנים אליה עוד תנועה.