רישום ביומן וצפייה ביומנים ב-Cloud Run

בדף הזה מוסבר על היומנים שזמינים כשמשתמשים ב-Cloud Run, ואיך צופים ביומנים וכותבים אותם.

ב-Cloud Run יש כמה סוגים של יומנים, והם נשלחים אוטומטית אל Cloud Logging:

  • יומני בקשות (שירותים בלבד): יומנים של בקשות שנשלחו לשירותי Cloud Run. היומנים האלה נוצרים באופן אוטומטי.
  • יומני קונטיינרים (שירותים, משימות ומאגרי עובדים): יומנים שנוצרים מהמופעים, בדרך כלל מהקוד שלכם, ונכתבים במיקומים נתמכים כמו שמתואר במאמר כתיבת יומני קונטיינרים.
  • יומני מערכת (שירותים, משימות ומאגרי עובדים): יומנים שנוצרו על ידי הפלטפורמה ומכילים מידע על עומסי העבודה שלכם. היומנים האלה נכתבים ב-varlog/system.

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

יש כמה דרכים להצגת היומנים של השירות, העבודה או מאגר העובדים:

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

צפייה ביומנים ב-Cloud Run

אפשר לצפות ביומנים בדף Cloud Run עבור המשאבים הבאים:

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

  1. נכנסים לדף Services של Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. לוחצים על השירות ברשימה שמוצגת.

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

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

כדי לראות את יומני העבודות בדף Cloud Run:

  1. נכנסים לדף Jobs ב-Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. מאתרים את המשרה ברשימת המשרות ולוחצים עליה.

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

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

צפייה ביומנים של מאגר עובדים

כדי לראות את היומנים של מאגר העובדים בדף Cloud Run:

  1. במסוף Google Cloud , נכנסים לדף Worker pools של Cloud Run:

    כניסה ל-Cloud Run

  2. לוחצים על מאגר העובדים ברשימה שמוצגת.

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

צפייה ביומני שירות באמצעות Google Cloud CLI

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

כדי להציג את סוף הקובץ של יומנים, צריך להתקין את הרכיב log-streaming ב-Google Cloud CLI. אם הרכיב לא מותקן, תתבקשו להתקין אותו כשיהיה צורך.

צפייה ביומנים בשורת הפקודה

בשביל שירות Cloud Run, אפשר לעקוב אחרי יומנים בזמן אמת משירות Cloud Run ישירות בשורת הפקודה:

gcloud beta run services logs tail SERVICE --project PROJECT-ID

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: השם של שירות Cloud Run.
  • ‫PROJECT-ID: מזהה הפרויקט ב- Google Cloud . כדי לראות את מזהה הפרויקט, מריצים את הפקודה gcloud config get-value project.

קריאת יומנים בשורת הפקודה

בשביל שירות של Cloud Run, אפשר לקרוא יומנים קיימים באחת משתי דרכים:

  • בפורמט שעבר אופטימיזציה לקונסולה: 
    gcloud run services logs read SERVICE --limit=10 --project PROJECT-ID
  • ישירות מ-Cloud Logging: 
    gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project PROJECT-ID --limit 10

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: השם של שירות Cloud Run.
  • ‫PROJECT-ID: מזהה הפרויקט ב- Google Cloud . כדי לראות את מזהה הפרויקט, מריצים את הפקודה gcloud config get-value project.

צפייה ביומנים ב-Cloud Logging

כדי לראות את היומנים של Cloud Run ב-Logs Explorer ב-Cloud Logging:

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

    כניסה לדף Logs Explorer

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

  3. בתפריטים הנפתחים, בוחרים את המשאב:

    • גרסת Cloud Run של שירות
    • משימה ב-Cloud Run למשימה
    • מאגר עובדים ב-Cloud Run בשביל מאגר עובדים

מידע נוסף זמין במאמר שימוש ב-Logs Explorer.

הצגת יומני שירות ב-Cloud Code

כדי לראות את היומנים ב-Cloud Code, אפשר לקרוא את המדריכים ל-IntelliJ ול-Visual Studio Code.

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

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

פורמט ופרטים של יומני שינוי גודל המופע

כשמופעלים מופעים חדשים בשירות Cloud Run, ‏ Cloud Logging כולל רשומות יומן בשם היומן varlog/system שמסבירות למה כל מופע נוצר. הרשומה ביומן מופיעה בפורמט הבא:

Starting new instance. Reason: REASON - DESCRIPTION

בטבלה הבאה מפורטים תיאורי המופעים:

סיבה תיאור
MANUAL_OR_CUSTOMER_MIN_INSTANCE המופע הופעל בגלל מופעים מינימליים או שינוי גודל ידני שהוגדרו על ידי הלקוח.
AUTOSCALING המופע הופעל בגלל גורמי קנה מידה שהוגדרו (כמו ניצול CPU, נפח בקשות וכו') או בגלל שלא היה מספיק קיבולת קיימת לתעבורה הנוכחית.
DEPLOYMENT_ROLLOUT המופע הופעל בגלל העברת תנועה בין עדכונים בעקבות פריסה, התאמה של פיצול התנועה או בדיקת תקינות של הפריסה.

כתיבת יומני קונטיינרים

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

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

יומני הקונטיינר שנכתבים במיקומים הנתמכים האלה משויכים אוטומטית לשירות, לגרסה ולמיקום של Cloud Run, למאגר העובדים, לגרסה ולמיקום של Cloud Run, או לעבודת Cloud Run. חריגים שמופיעים ביומנים האלה נרשמים ומדווחים בError Reporting.

הרישום המשולב מאזן בין מהימנות לשימוש במשאבים, והוא אמור לפעול ברוב האפליקציות. כתיבת רשומות ביומן באמצעות רישום משולב לא צורכת מכסה של מספר הבקשות entries.write לדקה של Cloud Logging API.

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

שימוש בטקסט פשוט לעומת JSON מובנה ביומנים

כשכותבים יומנים, אפשר לשלוח מחרוזת טקסט פשוטה או לשלוח שורה אחת של JSON מסודר, שנקרא גם נתונים 'מובנים'. הנתונים האלה נאספים ומנותחים על ידי Cloud Logging ומוצבים ב-jsonPayload. לעומת זאת, הודעת הטקסט הפשוטה ממוקמת ב-textPayload.

כתיבת יומנים מובנים

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

Node.js 


// Uncomment and populate this variable in your code:
// const project = 'The project ID of your function or Cloud Run service';

// Build structured log messages as an object.
const globalLogFields = {};

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// (This only works for HTTP-based invocations where `req` is defined.)
if (typeof req !== 'undefined') {
  const traceHeader = req.header('X-Cloud-Trace-Context');
  if (traceHeader && project) {
    const [trace] = traceHeader.split('/');
    globalLogFields['logging.googleapis.com/trace'] =
      `projects/${project}/traces/${trace}`;
  }
}

// Complete a structured log entry.
const entry = Object.assign(
  {
    severity: 'NOTICE',
    message: 'This is the default display field.',
    // Log viewer accesses 'component' as 'jsonPayload.component'.
    component: 'arbitrary-property',
  },
  globalLogFields
);

// Serialize to a JSON string and output.
console.log(JSON.stringify(entry));

Python 

# 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))

המשך

המבנה של כל רשומה ביומן מסופק על ידי סוג Entry: 


// Entry defines a log entry.
type Entry struct {
	Message  string `json:"message"`
	Severity string `json:"severity,omitempty"`
	Trace    string `json:"logging.googleapis.com/trace,omitempty"`

	// Logs Explorer allows filtering and display of this as `jsonPayload.component`.
	Component string `json:"component,omitempty"`
}

// String renders an entry structure to the JSON format expected by Cloud Logging.
func (e Entry) String() string {
	if e.Severity == "" {
		e.Severity = "INFO"
	}
	out, err := json.Marshal(e)
	if err != nil {
		log.Printf("json.Marshal: %v", err)
	}
	return string(out)
}

כשמבצעים רישום ביומן של מבנה Entry, מתבצעת קריאה לשיטה String כדי להמיר אותו לפורמט JSON שצפוי ב-Cloud Logging: 


func init() {
	// Disable log prefixes such as the default timestamp.
	// Prefix text prevents the message from being parsed as JSON.
	// A timestamp is added when shipping logs to Cloud Logging.
	log.SetFlags(0)
}

func indexHandler(w http.ResponseWriter, r *http.Request) {
	// Uncomment and populate this variable in your code:
	// projectID = "The project ID of your Cloud Run service"

	// Derive the traceID associated with the current request.
	var trace string
	if projectID != "" {
		traceHeader := r.Header.Get("X-Cloud-Trace-Context")
		traceParts := strings.Split(traceHeader, "/")
		if len(traceParts) > 0 && len(traceParts[0]) > 0 {
			trace = fmt.Sprintf("projects/%s/traces/%s", projectID, traceParts[0])
		}
	}

	log.Println(Entry{
		Severity:  "NOTICE",
		Message:   "This is the default display field.",
		Component: "arbitrary-property",
		Trace:     trace,
	})

	fmt.Fprintln(w, "Hello Logger!")
}

Java

כדי להפעיל רישום ביומן בפורמט JSON באמצעות Logback ו-SLF4J, צריך להגדיר את התוסף Logging Logback בהגדרות של logback.xml: 

// 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];
  MDC.put(
      "logging.googleapis.com/trace",
      String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using MDC (Mapped Diagnostic Context) keys.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
MDC.put("component", "arbitrary-property");

logger.info("This is the default display field.");

// Clear MDC at the end of the request to avoid resource leaks
MDC.clear();

מגדירים את LoggingAppender להפניית יומנים לפלט רגיל (stdout) בפורמט JSON מובנה, כדי ש-Cloud Run יתעד אותם. פרטים נוספים מופיעים במאמר בנושא הגדרת Logback. 

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
    <!-- Redirect logs to stdout in JSON format for Cloud Run to capture -->
    <redirectToStdout>true</redirectToStdout>
  </appender>
  <root level="INFO">
    <appender-ref ref="CLOUD"/>
  </root>
</configuration>

כך נראה מבנה יומן הפלט: 

{"severity":"INFO","time":"YYYY-MM-DDTHH:MM:SS.SSSZ","logging.googleapis.com/labels":{"component":"arbitrary-property","levelName":"INFO","loggerName":"com.example.cloudrun.App","levelValue":"20000"},"logging.googleapis.com/trace_sampled":false,"message":"This is the default display field."}

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

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

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

הצלבת יומני הקונטיינר עם יומן בקשות (שירותים בלבד)

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

יומני קונטיינרים לא משויכים אוטומטית ליומני בקשות, אלא אם משתמשים בספריית לקוח של Cloud Logging. כדי לבצע קורלציה בין יומני קונטיינרים לבין יומני בקשות בלי להשתמש בספריית לקוח, אפשר להשתמש בשורת יומן JSON מובנית שמכילה שדה logging.googleapis.com/trace עם מזהה המעקב שחולץ מהכותרת X-Cloud-Trace-Context, כמו בדוגמה שלמעלה לרישום מובנה ביומן.

שליטה בשימוש במשאבים ביומן הבקשות (שירותים בלבד)

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

הערה לגבי רישום נציגים ביומן

אם השתמשתם ב-Cloud Logging עם מוצרים מסוימים, כמו Compute Engine, יכול להיות שהשתמשתם בסוכני רישום ב-Cloud Logging. Google Cloud ב-Cloud Run לא משתמשים בסוכני רישום ביומן כי יש תמיכה מובנית באיסוף יומנים.

שמות משאבים ב-Logging

שמות המשאבים של Cloud Run ב-Cloud Logging הם:

משאבי Logging

כשלוחצים על רשומה ביומן בכלי Logs Explorer, נפתחת רשומה ביומן בפורמט JSON, כך שאפשר להגיע לפרטים הרצויים.

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

‫Cloud Run מוסיף מטא-נתונים נוספים, כך שאפשר לזהות את המקור של יומן. זה כולל את (התוויות שהגדרתם בשירות Cloud Run) ואת תוויות המשאבים שספציפיות ל-Cloud Run.

שדות של רשומת יומן לשירות

הרשימה הבאה כוללת שדות שאפשר למצוא ברשומת היומן של שירות Cloud Run:

שדה ערכים והערות
LogEntry.labels.instanceId המופע שטיפל בבקשה.
LogEntry.labels.run.googleapis.com/base_image_versions גרסת תמונת הבסיס שבה השירות משתמש. האפשרות הזו מופיעה רק בשירותים שנפרסו ממקור, ורק אם האפשרות עדכוני אבטחה אוטומטיים מופעלת.
LogEntry.labels.run.googleapis.com/cloud_event_id מזהה CloudEvent. האפשרות הזו מופיעה רק בשירותים שמקבלים אירועים מ-Eventarc.
LogEntry.labels.run.googleapis.com/cloud_event_source המקור של CloudEvent. האפשרות הזו מופיעה רק בשירותים שמקבלים אירועים מ-Eventarc.
LogEntry.labels.mylabel,
LogEntry.labels.mysecondlabel		 התוויות שהגדרתם בשירות.
LogEntry.logName מזהה את היומן, לדוגמה, יומן בקשות, שגיאה רגילה, פלט רגיל וכו'.
LogEntry.resource.labels.location מזהה את המיקום של השירות ב-Google Cloud.
LogEntry.resource.labels.project_id הפרויקט שבו השירות נפרס.
LogEntry.resource.labels.revision_name הגרסה ששימשה להצגת הבקשה.
LogEntry.resource.labels.service_name השירות שטיפל בבקשה.
LogEntry.resource.type ‫cloud_run_revision. סוג המשאב ב-Cloud Run.

הנה דוגמה לרשומה ביומן הבקשות של שירות Cloud Run:

{
 httpRequest: {…}
 insertId:  "5c82b3d1000ece0000000000"
 labels: {
  instanceId:  "00bf4bf00000fb59c906a00000c9e29c2c4e06dce91500000000056008d2b6460f163c0057b97b2345f2725fb2423ee5f0bafd36df887fdb1122371563cf1ff453717282afe000001"
  mylabel: "mylabelvalue"
  mysecondlabel: "mysecondlabelvalue"
 }
 logName:  "projects/my-project/logs/run.googleapis.com%2Frequests"
 receiveTimestamp:  "2019-03-08T18:26:25.981686167Z"
 resource: {
  labels: {
   configuration_name:  "myservice"
   location:  "europe-west1"
   project_id:  "my-project"
   revision_name:  "myservice-00002"
   service_name:  "myservice"
  }
  type:  "cloud_run_revision"
 }
 severity:  "INFO"
 timestamp:  "2019-03-08T18:26:25.970397Z"
}

שדות של רשומות ביומן לגבי משרות

זו רשימה של השדות שמופיעים ברשומה ביומן של משימת Cloud Run:

שדה ערכים והערות
LogEntry.labels.instanceId המופע.
LogEntry.labels.mylabel,

LogEntry.labels.mysecondlabel

התוויות שהגדרתם למשרה.
LogEntry.logName מזהה את היומן, למשל, שגיאה רגילה, פלט רגיל וכו'.
LogEntry.resource.labels.location מזהה את Google Cloud מיקום העבודה.
LogEntry.resource.labels.project_id הפרויקט שבו העבודה נפרסת.
LogEntry.resource.labels.job_name שם המשרה.
LogEntry.labels.execution_name השם של הפעלת העבודה.
LogEntry.labels.task_index האינדקס של המשימה.
LogEntry.labels.task_attempt כמה פעמים נעשה ניסיון לבצע את המשימה הזו.
LogEntry.resource.type ‫cloud_run_job. סוג המשאב ב-Cloud Run.

שדות של רשומות ביומן למאגרי כוח עבודה

זו רשימה של שדות שאפשר למצוא ברשומה ביומן של מאגר עובדים ב-Cloud Run:

שדה ערכים והערות
LogEntry.labels.instanceId המופע.
LogEntry.labels.mylabel,

LogEntry.labels.mysecondlabel

התוויות שהגדרתם במאגר העובדים.
LogEntry.logName מזהה את היומן, למשל, שגיאה רגילה, פלט רגיל וכו'.
LogEntry.resource.labels.location Google Cloud המיקום של מאגר העובדים.
LogEntry.resource.labels.project_id הפרויקט שבו נפרס מאגר העובדים.
LogEntry.resource.labels.workerpool_name השם של מאגר העובדים.
LogEntry.resource.type ‫cloud_run_workerpool. סוג המשאב ב-Cloud Run.

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

  • אתם יכולים להשתמש ב-Gemini Cloud Assist Investigations כדי לאבחן בעיות, לקבל תובנות פרקטיות ולפתור בעיות. מידע נוסף על דרכים שונות להתחלת חקירה באמצעות Logs Explorer מופיע במאמר פתרון בעיות באמצעות Gemini Cloud Assist Investigations במסמכי Gemini.