本頁面由 Cloud Translation API 翻譯而成。

設定 Java 適用的 Cloud Logging

您可以使用 Logback 附加程式或 java.util.logging handler，或直接使用 Java 適用的 Cloud Logging 程式庫，將記錄從 Java 應用程式寫入至 Cloud Logging。

您不必安裝 Cloud Logging 代理程式，即可使用 Java 適用的 Cloud Logging 程式庫。

事前準備

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.

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

Go to project selector

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

Enable the Cloud Logging API.

Enable the API

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

Go to project selector

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

Enable the Cloud Logging API.

Enable the API

Cloud Logging 的 Logback 附加元件

使用 Logback 附加程式時，您可以搭配 SLF4J 記錄中繼介面使用 Cloud Logging。

安裝依附元件

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"

Logback 設定

Logback 能夠以程式化的方式，或使用以 XML 或 Groovy 表示的指令碼設定。

您可以自訂最小嚴重程度門檻、記錄名稱，或提供其他增強器。以下是 XML 格式的範例 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 -->
  </appender>

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

範例

在您將 Logback 設定為使用 Cloud Logging Logback 附加程式之後，現在可以使用 SLF4J 記錄 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");
  }
}

java.util.logging 處理常式

處理常式

安裝依附元件

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.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>

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.21.3</version>
</dependency>

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

implementation platform('com.google.cloud:libraries-bom:26.61.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.22.5"

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

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

java.util.logging 設定

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 處理程序和 Cloud Logging 的 Logback 附加元件常見的設定。

預設值

Logback 附加程式和 java.util.logging 處理程序會使用下列預設值，將 Cloud Logging 用戶端例項化：

記錄檔名稱：java.log
要記錄的最低門檻：INFO
清除嚴重性：ERROR

Java 版 Cloud Logging 程式庫會依大小和上次寫入後的時間批次處理訊息。若記錄要求的清除嚴重性為清除嚴重性或更高，系統會立即寫入。

受控資源偵測

透過 Cloud Logging 程式庫傳送的所有記錄都需要監控的資源類型來識別您的應用程式。

Logback 附加元件和 java.util.logging 處理程序可自動偵測 App Engine、Compute Engine 和 Google Kubernetes Engine 應用程式的資源類型。

在其他環境中，系統會使用 global 監控的資源做為預設。

您可以在 Logback 附加程式設定或 java.util.logging 處理常式設定中，將監控的資源類型覆寫為有效類型。

其他欄位與標籤

使用 Logback 附加程式和 java.util.logging 處理常式時，您可以使用 LoggingEnhancer 的例項，在 LogEntry 物件上新增或更新欄位。

強化工具必須依照 Logback 附加程式設定或 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");
  }
}

您的設定可能不支援使用自訂標籤。舉例來說，資料流記錄不包含這些標籤。

如要進一步瞭解安裝方式，請參閱 Java 適用的 Cloud Logging 程式庫說明文件。您也可以使用問題追蹤工具回報問題。

使用 Cloud Logging 用戶端程式庫寫入記錄

如要瞭解如何直接使用 Cloud Logging 用戶端程式庫 (適用於 Java)，請參閱「Cloud Logging 用戶端程式庫」一文。

在 Google Cloud上執行

應用程式如要使用適用於 Java 的 Cloud Logging 程式庫記錄記錄，底層資源的服務帳戶必須具備 Logs Writer (roles/logging.logWriter) IAM 角色。大多數環境都會自動將這個角色指派給預設服務帳戶。 Google Cloud

App Engine

Cloud Logging 會自動為 App Engine 啟用，而且您的應用程式預設服務帳戶預設會具備寫入記錄項目的 IAM 權限。

在預設情況下，App Engine 標準環境會使用 java.util.logging.Logger API；這樣會直接寫入到 Cloud Logging，而且很容易設定。

如需進一步詳細資訊，請參閱 App Engine 說明文件中的讀取及寫入應用程式記錄一文。

App Engine 彈性環境

在 App Engine 彈性環境中，java.util.logging 預設會使用 ConsoleHandler，並將記錄傳送至 stdout 和 stderr。

Jetty Runtime 隨附於 Java 適用的 Cloud Logging 程式庫。

java.util.logging 處理程序可用於在 app.yaml 中提供 logging.properties，直接將記錄資料記錄至 Cloud Logging，如以下所示：

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

如果您使用 java.util.logging 處理常式或 Logback 附加程式，即可使用 Jetty 執行階段的追蹤項目 ID 記錄。

在 App Engine 彈性環境上執行時，TraceLoggingEnhancer 例項會使用 trace_id 標籤，將安全執行緒追蹤項目 ID 新增到每個記錄項目。

Google Kubernetes Engine (GKE)

GKE 會自動授予預設服務帳戶「Logs Writer (roles/logging.logWriter)」 IAM 角色。如果您使用 Workload Identity Federation for GKE 搭配這個預設服務帳戶，讓工作負載存取特定Google Cloud API，則不需要額外設定。不過，如果您使用 Workload Identity Federation for GKE 搭配自訂 IAM 服務帳戶，請確認自訂服務帳戶具備「記錄寫入者」(roles/logging.logWriter) 角色。

如有需要，您也可以在建立叢集時使用下列指令新增 logging.write 存取範圍：

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

Compute Engine

使用 Compute Engine VM 執行個體時，請將 cloud-platform 存取範圍新增到每個執行個體。透過Google Cloud 主控台建立新執行個體時，您可在「Create Instance」面板的「Identity and API access」部分中執行此操作。請使用 Compute Engine 預設服務帳戶或您選擇的其他服務帳戶，並選取「Identity and API access」(身分及 API 存取權) 區段的「Allow full access to all Cloud APIs」(允許所有 Cloud API 的完整存取權)。無論您選取哪個服務帳戶，請確認該帳戶已在Google Cloud 主控台的「IAM & Admin」區段中取得「Logs Writer」角色。

在本機和其他位置執行

如要在 Google Cloud以外使用 Java 專用的 Cloud Logging 程式庫，包括在您自己的工作站、資料中心的電腦或其他雲端服務供應商的 VM 執行個體上執行程式庫時，您必須在本機環境中設定應用程式預設憑證 (ADC)，才能對 Java 專用的 Cloud Logging 程式庫進行驗證。

詳情請參閱「為內部部署或其他雲端服務供應商設定 ADC」。

查看記錄

前往 Google Cloud 控制台的「Logs Explorer」頁面：

前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

在記錄檔瀏覽器中，您必須指定一或多個資源，但資源的選取可能並不明顯。下列提示可協助您著手操作：

如果您將應用程式部署至 App Engine 或使用 App Engine 特定程式庫，請將您的資源設定為 GAE 應用程式。
如果您在 Compute Engine 上部署應用程式，請將資源設定為 GCE VM 執行個體。
如果您在 Google Kubernetes Engine 上部署應用程式，叢集的記錄設定可決定記錄項目的資源類型。如需關於舊版 Google Cloud Observability 和 Google Cloud Observability Kubernetes Monitoring 解決方案的詳細討論，以及這些選項影響資源類型的方式，請參閱遷移至 Google Cloud Observability Kubernetes Monitoring 一文。
如果您的應用程式直接使用 Cloud Logging API，資源取決於 API 與您的設定。例如，在您的應用程式中，您可以指定資源或使用預設資源。
如果您在記錄檔探索工具中看不到任何記錄，請切換至進階查詢模式並使用空白查詢，以便查看所有記錄項目。
1. 如要切換至進階查詢模式，請按一下記錄探索器頂端的選單 (&blacktriangledown;)，然後選取「Convert to advanced filter」。
2. 清除顯示在篩選器方塊中的內容。
3. 按一下 [Submit Filter] (提交篩選器)。
您可以檢查個別項目，以識別您的資源。

如需更多資訊，請參閱「使用記錄檔探索工具」。

設定 Java 適用的 Cloud Logging 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

Cloud Logging 的 Logback 附加元件

安裝依附元件

Logback 設定

範例

java.util.logging 處理常式

安裝依附元件

java.util.logging 設定

範例

常用設定

預設值

受控資源偵測

其他欄位與標籤

使用 Cloud Logging 用戶端程式庫寫入記錄

在 Google Cloud上執行

App Engine

App Engine 彈性環境

Google Kubernetes Engine (GKE)

Compute Engine

在本機和其他位置執行

查看記錄

設定 Java 適用的 Cloud Logging