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

בדף הזה מתוארים היומנים שזמינים לאפליקציות 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.

אפשר לשלב את Logback appender או את java.util.logging עם Cloud Logging. באמצעות Logback appender, אפשר להשתמש ב-Cloud Logging עם SLF4J logging facade.

למידע נוסף על שימוש ב-Cloud Logging מאפליקציות Java עם Logback appender או עם java.util.logging handler, או על שילוב ישיר של ספריית Cloud Logging עבור Java, אפשר לעיין במאמר הגדרת Cloud Logging עבור Java.

כתיבת יומנים מובְנים אל 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.

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

כדי להפעיל רישום בפורמט JSON באמצעות Logback ו-SLF4J, צריך להפעיל את Logstash JSON Encoder בהגדרות של logback.xml.

// Build structured log messages as an object.
Object globalLogFields = null;

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// TODO(developer): delete this code if you're creating a Cloud
//                  Function and it is *NOT* triggered by HTTP.
String traceHeader = req.headers("x-cloud-trace-context");
if (traceHeader != null && project != null) {
  String trace = traceHeader.split("/")[0];
  globalLogFields =
      kv(
          "logging.googleapis.com/trace",
          String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using key value pairs.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

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

<configuration>
  <appender name="jsonConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
      <!-- Ignore default logging fields -->
      <fieldNames>
        <timestamp>[ignore]</timestamp>
        <version>[ignore]</version>
        <logger>[ignore]</logger>
        <thread>[ignore]</thread>
        <level>[ignore]</level>
        <levelValue>[ignore]</levelValue>
      </fieldNames>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="jsonConsoleAppender"/>
  </root>
</configuration>

בסביבה הרגילה של 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 ולא מוגבל.

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