הגדרה של Cloud Logging ל-Java

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

לא צריך להתקין את סוכן Cloud Logging כדי להשתמש בספריית Cloud Logging ל-Java.

לפני שמתחילים

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

‫Logback appender for Cloud Logging

באמצעות Logback appender, אפשר להשתמש ב-Cloud Logging עם חזית הרישום SLF4J.

התקנת התלות

אם משתמשים ב-Maven, צריך להוסיף את הקוד הבא לקובץ pom.xml. במאמר העוסק בספריות BOM ל-Google Cloud Platform תוכלו לקרוא מידע נוסף על עצי מוצרים (BOM).

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.131.11-alpha</version>
</dependency>

אם משתמשים ב-Gradle, צריך להוסיף את הקוד הבא ליחסי התלות:

implementation 'com.google.cloud:google-cloud-logging-logback:0.131.11-alpha'

אם משתמשים ב-sbt, צריך להוסיף את הקוד הבא ליחסי התלות:

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.11-alpha"

הגדרת Logback

אפשר להגדיר את Logback באופן פרוגרמטי או באמצעות סקריפט בפורמט XML או Groovy.

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

<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 -->
  </appender>

  <root level="info">
    <appender-ref ref="CLOUD" />
  </root>
</configuration>

דוגמה

אחרי שמגדירים את Logback לשימוש ב-Cloud Logging Logback appender, אפשר להפנות יומנים באמצעות SLF4J logging API. צריך לספק Google Cloud הגדרה אם מתכננים להריץ את הדוגמה באופן מקומי או מחוץ ל- Google Cloud. בקטע הקוד הבא אפשר לראות איך מתבצעת כניסה ליומן באמצעות SLF4J facade באפליקציה:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Quickstart {
  private static final Logger logger = LoggerFactory.getLogger(Quickstart.class);

  public static void main(String[] args) {
    logger.info("Logging INFO with Logback");
    logger.error("Logging ERROR with Logback");
  }
}

‫handler של java.util.logging

אפשר גם להשתמש ב-Cloud Logging API באמצעות handler של Java Logging API שמוגדר כברירת מחדל.

התקנת התלות

אם משתמשים ב-Maven עם BOM, צריך להוסיף את הקוד הבא לקובץ pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.55.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-logging</artifactId>
  </dependency>

  <!-- ...
</dependencies>

אם משתמשים ב-Maven בלי BOM, צריך להוסיף אותו ליחסי התלות:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>3.21.3</version>
</dependency>

אם משתמשים ב-Gradle, צריך להוסיף את הקוד הבא ליחסי התלות:

implementation platform('com.google.cloud:libraries-bom:26.74.0')

implementation 'com.google.cloud:google-cloud-logging'

אם משתמשים ב-sbt, צריך להוסיף את הקוד הבא ליחסי התלות:

libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "3.24.0"

אם משתמשים ב-Visual Studio Code או ב-IntelliJ, אפשר להוסיף את ספריות הלקוח לפרויקט באמצעות יישומי הפלאגין הבאים של IDE:

• ‏Cloud Code ל-VS Code
• ‏Cloud Code ל-IntelliJ

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

הערה: כרגע לא ניתן להשתמש בספריות לקוח של Cloud Java ב-Android.

הגדרה של java.util.logging

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

  -Djava.util.logging.config.file=/path/to/logging.properties

דוגמה לקובץ תצורה:

# To use this configuration, add to system properties : -Djava.util.logging.config.file="/path/to/file"
#
.level = INFO

# it is recommended that io.grpc and sun.net logging level is kept at INFO level,
# as both these packages are used by Cloud internals and can result in verbose / initialization problems.
io.grpc.netty.level=INFO
sun.net.level=INFO

com.example.logging.jul.Quickstart.handlers=com.google.cloud.logging.LoggingHandler
# default : java.log
com.google.cloud.logging.LoggingHandler.log=custom_log

# default : INFO
com.google.cloud.logging.LoggingHandler.level=FINE

# default : ERROR
com.google.cloud.logging.LoggingHandler.flushLevel=ERROR

# default : auto-detected, fallback "global"
com.google.cloud.logging.LoggingHandler.resourceType=container

# custom formatter
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s

#optional enhancers (to add additional fields, labels)
com.google.cloud.logging.LoggingHandler.enhancers=com.example.logging.jul.enhancers.ExampleEnhancer

דוגמה

צריך לספק Google Cloud הגדרה אם מתכננים להריץ את הדוגמה באופן מקומי או מחוץ ל- Google Cloud. בקטע הקוד הבא אפשר לראות איך מתבצעת כניסה באמצעות java.util.logging:

import java.util.logging.Logger;

public class Quickstart {
  private static final Logger logger = Logger.getLogger(Quickstart.class.getName());

  public static void main(String[] args) {
    logger.info("Logging INFO with java.util.logging");
    logger.severe("Logging ERROR with java.util.logging");
  }
}

הגדרה משותפת

בקטעים הבאים מוסבר על הגדרות שמשותפות ל-java.util.logging handler ול-Logback appender ל-Cloud Logging.

ברירות מחדל

ה-appender של Logback וה-handler של java.util.logging משתמשים בערכי ברירת המחדל הבאים כדי ליצור מופע של לקוח Cloud Logging:

• שם היומן : java.log

• סף מינימלי לרישום ביומן : INFO

• מידת החומרה של השגיאה : ERROR

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

הערה: אם משתמשים ישירות ב-Cloud Logging library for Java API, אין שם יומן ברירת מחדל או סף מינימלי.

זיהוי משאבים במעקב

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

ה-Appender של Logback וה-handler של java.util.logging מספקים זיהוי אוטומטי של סוגי המשאבים באפליקציות שלכם ב-App Engine, ב-Compute Engine וב-Google Kubernetes Engine.

משאב מפוקח global משמש כברירת מחדל בסביבות אחרות.

אפשר לשנות את סוג המשאב במעקב לסוג תקין בהגדרות של Logback appender או בהגדרות של java.util.logging Handler.

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

שדות ותוויות נוספים

באמצעות Logback appender וה-handler‏ java.util.logging, אפשר להוסיף או לעדכן שדות באובייקט LogEntry באמצעות מופע של LoggingEnhancer.

צריך להגדיר את ה-enhancers כמו שמוצג בהגדרת ה-appender של Logback או בהגדרת ה-handler של java.util.logging:

import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.LoggingEnhancer;

// Add / update additional fields to the log entry
public class ExampleEnhancer implements LoggingEnhancer {

  @Override
  public void enhanceLogEntry(LogEntry.Builder logEntry) {
    // add additional labels
    logEntry.addLabel("test-label-1", "test-value-1");
  }
}

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

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

כתיבת יומנים באמצעות ספריית הלקוח של Cloud Logging

מידע על שימוש ישיר בספריית הלקוח של Cloud Logging ל-Java זמין במאמר ספריות הלקוח של Cloud Logging.

ריצה ב- Google Cloud

כדי שאפליקציה תוכל לכתוב יומנים באמצעות ספריית Cloud Logging ל-Java, לחשבון השירות של המשאב הבסיסי צריך להיות מוקצה תפקיד Logs Writer (roles/logging.logWriter) IAM. ברוב הסביבות, חשבון השירות שמוגדר כברירת מחדל מוגדר אוטומטית עם התפקיד הזה. Google Cloud

App Engine

‫Cloud Logging מופעל באופן אוטומטי ב-App Engine, ולחשבון השירות שמוגדר כברירת מחדל של האפליקציה יש הרשאות IAM כברירת מחדל לכתיבת רשומות ביומן.

בסביבת App Engine סטנדרטית, נעשה שימוש ב-API ‏java.util.logging.Logger כברירת מחדל. ה-API הזה כותב ישירות ל-Cloud Logging וקל להגדרה.

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

סביבה גמישה של App Engine

בסביבה גמישה של App Engine,‏ java.util.logging משתמש ב-ConsoleHandler כברירת מחדל ושולח יומנים אל stdout ו-stderr.

סביבת זמן הריצה של Jetty כלולה בספריית Cloud Logging ל-Java.

אפשר להשתמש בב-handler‏ java.util.logging כדי לרשום יומנים ישירות ב-Cloud Logging. לשם כך צריך לציין את logging.properties ב-app.yaml, כמו שמוצג כאן:

    env_variables:
      JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties

רישום ביומן של מזהה מעקב זמין בסביבות זמן ריצה של Jetty אם משתמשים ב-handler‏ java.util.logging או ב-appender של Logback.

כשמריצים בסביבה הגמישה של App Engine, מופע של TraceLoggingEnhancer מוסיף מזהה מעקב בטוח לכל רשומה ביומן באמצעות התווית trace_id.

Google Kubernetes Engine (GKE)

‫GKE מעניק באופן אוטומטי לחשבון השירות שמוגדר כברירת מחדל את תפקיד ה-IAM‏ Logs Writer (roles/logging.logWriter). אם אתם משתמשים באיחוד זהויות של עומסי עבודה ל-GKE עם חשבון השירות שמוגדר כברירת מחדל כדי לאפשר לעומסי עבודה לגשת ל-APIs ספציפיים שלGoogle Cloud , לא נדרש שום שינוי נוסף בהגדרות. עם זאת, אם משתמשים באיחוד שירותי אימות הזהות של עומסי עבודה ב-GKE עם חשבון שירות מותאם אישית של IAM, צריך לוודא שלחשבון השירות המותאם אישית יש את התפקיד Logs Writer ‏ (roles/logging.logWriter).

במקרה הצורך, אפשר להשתמש גם בפקודה הבאה כדי להוסיף את logging.write היקף הגישה כשיוצרים את האשכול:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

הערה: כדי להשתמש בספריית Cloud Logging ל-Java במכונת VM ב-Compute Engine, לא צריך להתקין את סוכן Cloud Logging.

כשמשתמשים במופעים של מכונות וירטואליות ב-Compute Engine, צריך להוסיף את היקף הגישה cloud-platform לכל מופע. כשיוצרים מכונה חדשה דרך מסוףGoogle Cloud , אפשר לעשות זאת בקטע Identity and API access (זהות וגישה ל-API) בחלונית Create Instance (יצירת מכונה). משתמשים בחשבון השירות שמוגדר כברירת המחדל ב-Compute Engine או בחשבון שירות אחר לפי בחירתכם, ובקטע Identity and API access בוחרים באפשרות Allow full access to all Cloud APIs. לא משנה איזה חשבון שירות תבחרו, חשוב לוודא שניתן לו התפקיד Logs Writer בקטע IAM & Admin במסוףGoogle Cloud .

הרצה באופן מקומי ובמקומות אחרים

כדי להשתמש בספריית Cloud Logging ל-Java מחוץ ל- Google Cloud, כולל הפעלת הספרייה בתחנת העבודה שלכם, במחשבים של מרכז הנתונים או במכונות וירטואליות של ספק שירותי ענן אחר, אתם צריכים להגדיר Application Default Credentials ‏ (ADC) בסביבה המקומית כדי לבצע אימות לספריית Cloud Logging ל-Java.

למידע נוסף אפשר לעיין במאמר הגדרת ADC לספק שירותי ענן מקומי או אחר.

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

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

כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.

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

• אם אתם פורסים את האפליקציה ב-App Engine או משתמשים בספריות ספציפיות ל-App Engine, צריך להגדיר את המשאב לערך GAE Application.

• אם אתם פורסים את האפליקציה ב-Compute Engine, צריך להגדיר את המשאב ל-GCE VM Instance.

• אם אתם פורסים את האפליקציה ב-Google Kubernetes Engine, הגדרת רישום היומנים של האשכול קובעת את סוג המשאב של רשומות היומן. במאמר מעבר לפתרון Google Cloud Observability Kubernetes Monitoring מוסבר בפירוט על הפתרונות Legacy Google Cloud Observability ו-Google Cloud Observability Kubernetes Monitoring, ועל ההשפעה של האפשרויות האלה על סוג המשאב.

• אם האפליקציה שלכם משתמשת ישירות ב-Cloud Logging API, המשאב תלוי ב-API ובהגדרה שלכם. לדוגמה, באפליקציה שלכם תוכלו לציין משאב או להשתמש במשאב שמוגדר כברירת מחדל.

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

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

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

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