設定 Java 適用的 Stackdriver Logging

您可以使用 Logback 附加程式java.util.logging 處理常式,或直接使用 Java 適用的 Stackdriver Logging 程式庫,將記錄從 Java 應用程式寫入到 Stackdriver Logging。

您不必安裝 Stackdriver Logging 代理程式,就可以使用 Java 適用的 Stackdriver Logging 程式庫。

事前準備

  1. 登入您的 Google 帳戶。

    如果您沒有帳戶,請申請新帳戶

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

  4. 啟用Stackdriver Logging API。

    啟用 API

Stackdriver Logging 適用的 Logback 附加程式

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

安裝依附元件

如果您是使用 Maven,請在 pom.xml 檔案中新增以下指令:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.79.0-alpha</version>
</dependency>
如果您是使用 Gradle,請在相依元件中新增以下指令:
compile 'com.google.cloud:google-cloud-logging-logback:0.79.0-alpha'
如果您是使用 SBT,請在相依元件中新增以下指令:
libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.79.0-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 設定為使用 Stackdriver Logging Logback 附加程式之後,現在可以使用 SLF4J 記錄 API 重新導向記錄。以下程式碼片段顯示如何在您的應用程式中使用 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 處理常式

您也可以透過預設 Java Logging API 處理常式使用 Stackdriver Logging API。

安裝依附元件

如果您是使用 Maven,請在 pom.xml 檔案中新增以下指令:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>1.61.0</version>
</dependency>
如果您是使用 Gradle,請在相依元件中新增以下指令:
compile 'com.google.cloud:google-cloud-logging:1.61.0'
如果您是使用 SBT,請在相依元件中新增以下指令:
libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "1.61.0"

如果您使用 IntelliJ 或 Eclipse,可以使用以下 IDE 外掛程式將用戶端程式庫加入專案中:

外掛程式還提供其他功能,例如服務帳戶適用的金鑰管理。詳情請參閱各外掛程式的說明文件。

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

範例

下列程式碼片段說明如何使用 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 處理常式及 Stackdriver Logging 適用的 Logback 附加程式而言常見的設定。

預設值

Logback 附加程式與 java.util.logging 處理常式使用下列預設值來實例化 Stackdriver Logging 用戶端:

  • 記錄名稱:java.log

  • 要記錄的最低門檻:INFO

  • 清除嚴重性:ERROR

Java 適用的 Stackdriver Logging 程式庫會按大小及自從上次寫入之後的時間批次處理訊息。 記錄要求嚴重性達到或高於清除嚴重性的批次會被立即寫出。

受控資源偵測

所有透過 Stackdriver 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 適用的 Stackdriver Logging 程式庫的說明文件。您也可以使用問題追蹤工具報告問題。

直接使用 Cloud 用戶端程式庫

如要瞭解如何直接使用 Java 適用的 Stackdriver Logging Cloud 用戶端程式庫,請參閱 Stackdriver Logging 用戶端程式庫一文。

在 Google Cloud Platform 上執行

使用 Java 適用的 Stackdriver Logging 程式庫需要 GCP 上的 Cloud IAM 記錄寫入者角色。大部分 GCP 環境預設都提供這個角色。

App Engine

在預設情況下,App Engine 會授予記錄寫入者角色

不需要明確提供憑證,即可使用 Java 適用的 Stackdriver Logging 程式庫。

所有 App Engine 應用程式都會自動啟用 Stackdriver Logging。您不需要另外進行設定。

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

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

App Engine 彈性環境

App Engine 彈性環境java.util.logging 依預設會使用 ConsoleHandler,並將記錄傳送到 stdoutstderr

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

如下所示,在 app.yaml 提供 logging.propertiesjava.util.logging 處理常式即可用來直接記錄到 Stackdriver 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

Google Kubernetes Engine 上,您必須於建立叢集時新增 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 Platform 主控台建立新執行個體時,您可在「Create Instance」 (建立執行個體) 面板的「Identity and API access」 (身分及 API 存取權) 區段執行這項操作。請使用 Compute Engine 預設服務帳戶或您選擇的其他服務帳戶,並選取「Identity and API access」 (身分及 API 存取權) 區段的 [Allow full access to all Cloud APIs] (允許所有 Cloud API 的完整存取權)。無論您選取哪個服務帳戶,請確認這個帳戶已在 GCP 主控台的「IAM & admin」(IAM 與管理員) 區段取得記錄寫入者角色

在本機及其他位置執行

如要在 Google Cloud Platform 之外使用 Java 適用的 Stackdriver Logging 程式庫,您必須將 GCP 專案 ID 與適當的服務帳戶憑證直接提供給 Java 適用的 Stackdriver Logging 程式庫。這適用於在您自己的工作站上、在資料中心的電腦上,或在其他雲端服務供應商的 VM 執行個體上執行代理程式。詳情請參閱手動取得及提供服務帳戶憑證一節。

查看記錄

部署之後,您可在 GCP 主控台記錄檢視器中查看記錄。

前往記錄檢視器

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

  • 如果您將應用程式部署至 App Engine 或使用 App Engine 特定程式庫,請將您的資源設定為 GAE 應用程式

  • 如果您在 Compute Engine 上部署應用程式,請將資源設定為 GCE VM 執行個體

  • 如果您在 Google Kubernetes Engine 上部署應用程式,叢集的記錄設定可決定記錄項目的資源類型。如需關於舊版 Stackdriver 與 Stackdriver Kubernetes Monitoring 解決方案的詳細討論,以及這些選項影響資源類型的方式,請參閱遷移至 Stackdriver Kubernetes Monitoring 一文。

  • 如果您的應用程式直接使用 Stackdriver Logging API,資源取決於 API 與您的設定。例如,在您的應用程式中,您可以指定資源或使用預設資源。

  • 如果您在記錄檢視器中看不到任何記錄,若要查看所有記錄項目,請切換至進階篩選器模式並使用空白篩選器。

    1. 若要切換至進階篩選器模式,請按一下記錄檢視器頂端的選單 (&blacktriangledown;),然後選取 [Convert to advanced filter] (轉換為進階篩選器)
    2. 清除顯示在篩選器方塊中的內容。
    3. 按一下 [Submit Filter] (提交篩選器)

    您可以檢查個別項目,以識別您的資源。

詳情請參閱查看記錄進階記錄篩選器這兩篇文章。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁