Menyiapkan Cloud Logging untuk Java

Anda dapat menulis log ke Cloud Logging dari aplikasi Java dengan menggunakan appender Logback atau java.util.logging handler, atau dengan menggunakan library Cloud Logging untuk Java secara langsung.

Agen Cloud Logging tidak perlu diinstal untuk menggunakan library Cloud Logging untuk Java.

Sebelum memulai

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Logging API.

   Enable the API

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud Logging API.

   Enable the API

Appender Logback untuk Cloud Logging

Dengan menggunakan appender Logback, Anda dapat menggunakan Cloud Logging dengan fasad logging SLF4J.

Menginstal dependensi

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

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

If you are using Gradle, add the following to your dependencies:

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

If you are using sbt, add the following to your dependencies:

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

Konfigurasi Logback

Logback dapat dikonfigurasi secara terprogram atau menggunakan skrip yang dinyatakan dalam XML atau Groovy.

Anda dapat menyesuaikan nilai minimum tingkat keparahan, nama log, atau memberikan pengoptimal tambahan. Ini adalah contoh konfigurasi Logback dalam format 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>

Contoh

Setelah mengonfigurasi Logback untuk menggunakan Logback appender Cloud Logging, Anda kini dapat mengalihkan log menggunakan API logging SLF4J. Berikan konfigurasi Google Cloud jika Anda berencana menjalankan contoh secara lokal atau di luar Google Cloud. Cuplikan ini menunjukkan cara mencatat ke dalam log menggunakan fasad SLF4J dalam aplikasi Anda:

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");
  }
}

Pemroses java.util.logging

Anda juga dapat menggunakan Cloud Logging API menggunakan handler Java Logging API default.

Menginstal dependensi

If you are using Maven with a BOM, add the following to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.43.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>

If you are using Maven without a BOM, add this to your dependencies:

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

If you are using Gradle, add the following to your dependencies:

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

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

If you are using sbt, add the following to your dependencies:

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

If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

• Cloud Code for VS Code
• Cloud Code for IntelliJ
• Cloud Tools for Eclipse

The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

Note: Cloud Java client libraries do not currently support Android.

Konfigurasi java.util.logging

Pengendali logging dapat ditambahkan secara terprogram atau menggunakan file konfigurasi. Jalur ke file konfigurasi harus diberikan ke aplikasi Anda sebagai properti sistem: -Djava.util.logging.config.file=/path/to/logging.properties

Berikut adalah contoh file konfigurasi:

# 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

Contoh

Berikan konfigurasi Google Cloud jika Anda berencana menjalankan contoh secara lokal atau di luar Google Cloud. Cuplikan ini menunjukkan cara mencatat log menggunakan 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");
  }
}

Konfigurasi Umum

Bagian berikut membahas konfigurasi yang umum untuk pengendali java.util.logging dan appender Logback untuk Cloud Logging.

Default

Pengendali java.util.logging dan appender Logback menggunakan default berikut untuk membuat instance klien Cloud Logging:

• Nama log : java.log

• Batas minimum untuk dicatat ke dalam log : INFO

• Tingkat pembersihan : ERROR

Library Cloud Logging untuk Java mengelompokkan pesan berdasarkan ukuran dan waktu sejak penulisan terakhir. Batch dengan permintaan logging pada atau di atas tingkat keparahan penghapusan langsung ditulis.

Catatan: Jika menggunakan library Cloud Logging untuk Java API secara langsung, tidak ada nama log default atau nilai minimum.

Deteksi resource yang dimonitor

Semua log yang dikirim melalui library Cloud Logging memerlukan jenis resource yang dimonitor untuk mengidentifikasi aplikasi Anda.

Appender Logback dan pengendali java.util.logging memberikan deteksi jenis resource otomatis untuk aplikasi App Engine, Compute Engine, dan Google Kubernetes Engine Anda.

Resource yang dipantau global digunakan sebagai default di lingkungan lain.

Anda dapat mengganti jenis resource yang dimonitor ke jenis yang valid di Konfigurasi Logback appender atau Konfigurasi Pengendali java.util.logging.

Catatan: Jika menggunakan Cloud Logging API secara langsung, Anda harus memberikan jenis resource yang dimonitor yang valid saat mencatat log menggunakan API.

Kolom dan label tambahan

Dengan menggunakan Logback appender dan pengendali java.util.logging, Anda dapat menambahkan atau memperbarui kolom pada objek LogEntry menggunakan instance LoggingEnhancer.

Pengoptimal harus dikonfigurasi seperti yang ditunjukkan dalam konfigurasi Logback appender atau konfigurasi pengendali 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");
  }
}

Penggunaan label khusus mungkin tidak didukung untuk konfigurasi Anda. Misalnya, log Dataflow tidak menyertakan label ini.

Untuk informasi selengkapnya tentang penginstalan, lihat dokumentasi untuk library Cloud Logging untuk Java. Anda juga dapat melaporkan masalah menggunakan issue tracker.

Menulis log dengan library klien Cloud Logging

Untuk informasi tentang cara menggunakan library klien Cloud Logging untuk Java secara langsung, lihat Library Klien Cloud Logging.

Menjalankan di Google Cloud

Agar aplikasi dapat menulis log menggunakan library Cloud Logging untuk Java, akun layanan untuk resource pokok harus memiliki peran IAM Logs Writer (roles/logging.logWriter). Sebagian besar lingkungan Google Cloud secara otomatis mengonfigurasi akun layanan default agar memiliki peran ini.

App Engine

Cloud Logging otomatis diaktifkan untuk App Engine, dan akun layanan default aplikasi Anda memiliki izin IAM secara default untuk menulis entri log.

Lingkungan standar App Engine, secara default, menggunakan java.util.logging.Logger API; API ini menulis ke Cloud Logging secara langsung dan mudah dikonfigurasi.

Untuk mengetahui detail selengkapnya, lihat dokumentasi App Engine tentang Membaca dan Menulis Log Aplikasi.

Lingkungan fleksibel App Engine

Di lingkungan fleksibel App Engine, java.util.logging menggunakan ConsoleHandler secara default, dan mengirim log ke stdout dan stderr.

Runtime Jetty dipaketkan dengan library Cloud Logging untuk Java.

Pemroses java.util.logging dapat digunakan untuk mencatat log langsung ke Cloud Logging dengan memberikan logging.properties di app.yaml Anda seperti yang ditunjukkan di sini:

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

Logging ID pelacakan tersedia di runtime Jetty jika Anda menggunakan pengendali java.util.logging atau appender Logback.

Saat berjalan di lingkungan fleksibel App Engine, instance TraceLoggingEnhancer akan menambahkan ID rekaman aktivitas yang aman untuk thread ke setiap entri log menggunakan label trace_id.

Google Kubernetes Engine (GKE)

GKE secara otomatis memberikan peran IAM Logs Writer (roles/logging.logWriter) ke akun layanan default. Jika Anda menggunakan Workload Identity Federation untuk GKE dengan akun layanan default ini untuk mengizinkan workload mengakses Google Cloud API tertentu, konfigurasi tambahan tidak diperlukan. Namun, jika Anda menggunakan Workload Identity Federation untuk GKE dengan akun layanan IAM kustom, pastikan akun layanan kustom tersebut memiliki peran Logs Writer (roles/logging.logWriter).

Jika diperlukan, Anda juga dapat menggunakan perintah berikut untuk menambahkan cakupan akses logging.write saat membuat cluster:

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

Compute Engine

Catatan: Untuk menggunakan library Cloud Logging untuk Java di instance VM Compute Engine, Anda tidak perlu menginstal agen Cloud Logging.

Saat menggunakan instance VM Compute Engine, tambahkan cakupan akses cloud-platform ke setiap instance. Saat membuat instance baru melalui konsol Google Cloud, Anda dapat melakukannya di bagian Akses identitas dan API pada panel Buat Instance. Gunakan akun layanan default Compute Engine atau akun layanan lain pilihan Anda, lalu pilih Allow full access to all Cloud APIs di bagian Identity and API access. Akun layanan mana pun yang Anda pilih, pastikan akun tersebut telah diberi peran Logs Writer di bagian IAM & Admin di konsol Google Cloud.

Menjalankan secara lokal dan di tempat lain

Untuk menggunakan library Cloud Logging untuk Java di luar Google Cloud, termasuk menjalankan library di workstation Anda sendiri, di komputer pusat data, atau di instance VM dari penyedia cloud lain, Anda harus menyediakan ID project Google Cloud dan kredensial akun layanan yang sesuai langsung ke library Cloud Logging untuk Java.

Untuk akun layanan yang ada, lakukan langkah berikut:

1. Berikan peran IAM Logs Writer (roles/logging.logWriter) kepada akun layanan. Untuk informasi selengkapnya tentang peran IAM, lihat Kontrol akses.

2. Siapkan Kredensial Default Aplikasi.

Jika Anda tidak memiliki akun layanan, buat akun layanan. Untuk mengetahui informasi tentang proses ini, lihat Membuat akun layanan.

Untuk informasi umum tentang metode yang dapat Anda gunakan untuk melakukan autentikasi, lihat Istilah: akun layanan.

Melihat log

Di konsol Google Cloud, buka halaman Logs Explorer:

Buka Logs Explorer

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

Di Logs Explorer, Anda harus menentukan satu atau beberapa resource, tetapi pemilihan resource mungkin tidak jelas. Berikut beberapa tips untuk membantu Anda memulai:

• Jika Anda men-deploy aplikasi ke App Engine atau menggunakan library khusus App Engine, tetapkan resource Anda ke Aplikasi GAE.

• Jika Anda men-deploy aplikasi di Compute Engine, tetapkan resource ke Instance VM GCE.

• Jika Anda men-deploy aplikasi di Google Kubernetes Engine, konfigurasi logging cluster akan menentukan jenis resource entri log. Untuk diskusi mendetail tentang solusi Google Cloud Observability Lama dan Google Cloud Observability Kubernetes Monitoring, serta pengaruh opsi tersebut terhadap jenis resource, lihat Bermigrasi ke Google Cloud Observability Kubernetes Monitoring.

• Jika aplikasi Anda menggunakan Cloud Logging API secara langsung, resource akan bergantung pada API dan konfigurasi Anda. Misalnya, dalam aplikasi, Anda dapat menentukan resource atau menggunakan resource default.

• Jika Anda tidak melihat log apa pun di Logs Explorer, untuk melihat semua entri log, beralihlah ke mode kueri lanjutan dan gunakan kueri kosong.

  1. Untuk beralih ke mode kueri lanjutan, klik menu (▾) di bagian atas Logs Explorer, lalu pilih Konversikan ke filter lanjutan.
  2. Hapus konten yang muncul di kotak filter.
  3. Klik Kirim Filter.

  Anda dapat memeriksa setiap entri untuk mengidentifikasi resource Anda.

Untuk informasi tambahan, lihat Menggunakan Logs Explorer.