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