כתיבה של יומנים וצפייה בהם

בדף הזה מתוארים היומנים שזמינים לאפליקציות App Engine, ומוסבר איך לכתוב רשומות ביומן, לקשר ביניהן ולצפות בהן.

‫App Engine אוסף שני סוגים של יומנים:

  • יומן בקשות: יומנים של בקשות שנשלחו לאפליקציה. כברירת מחדל, App Engine פולט באופן אוטומטי רשומה ביומן לכל בקשת HTTP שאפליקציה מקבלת.

  • יומן אפליקציה: רשומות ביומן שנוצרות על ידי אפליקציית App Engine על סמך רשומות ביומן שאתם כותבים למסגרת או לקובץ נתמכים.

‫App Engine שולח אוטומטית את יומני הבקשות ואת יומני האפליקציות לסוכן של Cloud Logging.

כתיבת יומני אפליקציות

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

כשכותבים יומני אפליקציות מאפליקציית App Engine, המערכת אוספת את היומנים באופן אוטומטי באמצעות Cloud Logging, בתנאי שהיומנים נכתבים באמצעות השיטות הבאות:

שילוב עם Cloud Logging

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

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

כתיבת יומנים מובְנים אל stdout ו-stderr

כברירת מחדל, App Engine משתמש בספריית הלקוח של Cloud Logging כדי לשלוח יומנים. עם זאת, השיטה הזו לא תומכת ברישום ביומן במבנה. אפשר לכתוב יומנים מובנים רק באמצעות stdout/stderr. בנוסף, אפשר גם לשלוח מחרוזות טקסט אל stdout וstderr. כברירת מחדל, מטען הייעודי (payload) של היומן הוא מחרוזת טקסט שמאוחסנת בשדה textPayload של הרשומה ביומן. המחרוזות מופיעות כהודעות ב-Logs Explorer, בשורת הפקודה וב-Cloud Logging API, והן משויכות לשירות ולגרסה של App Engine שמהם הן נשלחו.

כדי להפיק ערך רב יותר מהיומנים, אפשר לסנן את המחרוזות האלה ב-Logs Explorer לפי רמת חומרה. כדי לסנן את המחרוזות האלה, צריך לעצב אותן כנתונים מובְנים. כדי לעשות את זה, כותבים יומנים בצורה של שורה אחת של JSON שעבר סריאליזציה. ‫App Engine מאחזר ומנתח את השורה הזו בפורמט JSON שעברה סריאליזציה, ומציב אותה בשדה jsonPayload של רשומת היומן במקום בשדה textPayload.

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

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

בסביבה הרגילה של App Engine, כתיבת יומנים מובנים אל stdout ו-stderr לא נספרת במכסת הבקשות להוספת יומנים לדקה ב-Cloud Logging API.

שדות JSON מיוחדים בהודעות

כשמספקים יומן מובנה כמילון JSON, חלק מהשדות המיוחדים מוסרים מהשדה jsonPayload ונכתבים בשדה המתאים ב-LogEntry שנוצר, כפי שמתואר במסמכי התיעוד בנושא שדות מיוחדים.

לדוגמה, אם קובץ ה-JSON כולל מאפיין severity, הוא יוסר מjsonPayload ויופיע במקום זאת כseverity של רשומת היומן. המאפיין message משמש כטקסט התצוגה הראשי של רשומת היומן, אם הוא קיים.

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

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

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

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

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

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

שימוש ב-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.

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

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

תמחור, מכסות ומדיניות שמירת נתונים של יומנים

למידע על התמחור שחל על יומני בקשות ועל יומני אפליקציות, ראו תמחור של Cloud Logging.

למידע על מדיניות שמירת הנתונים של היומנים ועל הגודל המקסימלי של רשומות היומן, אפשר לעיין במאמר בנושא מכסות ומגבלות. אם רוצים לאחסן את היומנים לתקופה ארוכה יותר, אפשר לייצא את היומנים ל-Cloud Storage. אפשר גם לייצא את היומנים ל-BigQuery ול-Pub/Sub כדי להמשיך לעבד אותם.

ניהול השימוש במשאבי יומן

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

בעיות מוכרות

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

  • לפעמים, רשומות ביומן של האפליקציה לא קשורות ליומן הבקשות. זה קורה בפעם הראשונה שהאפליקציה מקבלת בקשה ובכל פעם אחרת ש-App Engine כותב הודעות סטטוס ליומן של האפליקציה. מידע נוסף זמין בכתובת https://issuetracker.google.com/issues/138365527.

  • כשמנתבים יומנים מ-sink ביומן ל-Cloud Storage, יעד Cloud Storage מכיל רק יומני בקשות. ‫App Engine כותב יומנים של אפליקציות בתיקיות שונות.

  • הטמעת היומנים ב-BigQuery נכשלת בגלל השדה @type ביומני הבקשות. הדבר משבש את הזיהוי האוטומטי של הסכימה, כי BigQuery לא מאפשר שימוש בתווים @type בשמות של שדות. כדי לפתור את הבעיה, צריך להגדיר ידנית את הסכימה ולהסיר את השדה @type מיומני הבקשות.

  • אם משתמשים ב-REST APIs של Logging, שרשור ברקע כותב יומנים ל-Cloud Logging. אם ה-thread הראשי לא פעיל, המופע לא מקבל זמן CPU, ולכן ה-thread ברקע מפסיק לפעול. יש עיכוב בזמן העיבוד של היומן. בשלב מסוים, המופע מוסר וכל היומנים שלא נשלחו אובדים. כדי למנוע אובדן של יומנים, אפשר להשתמש באחת מהאפשרויות הבאות:

    • מגדירים את Cloud Logging SDK לשימוש ב-gRPC. ב-gRPC, היומנים נשלחים ל-Cloud Logging באופן מיידי. עם זאת, הפעולה הזו עלולה להגדיל את מגבלות המעבד הנדרשות.
    • שליחת הודעות יומן אל Cloud Logging באמצעות stdout/stderr. הצינור הזה נמצא מחוץ למופע App Engine ולא מוגבל.

המאמרים הבאים