Java 用 Cloud Logging の設定

Java アプリケーションから Cloud Logging にログを書き込むには、Logback アペンダーまたは java.util.logging ハンドラを使用するか、Java 用 Cloud Logging ライブラリを直接使用します。

Java 用 Cloud Logging ライブラリを使用するために、Cloud Logging エージェントをインストールする必要はありません。

始める前に

Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Cloud Logging API を有効にします。

API を有効にする

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Cloud Logging API を有効にします。

API を有効にする

Cloud Logging 用 Logback アペンダー

Logback アペンダーを使用すると、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.4-alpha</version>
</dependency>

Gradle を使用している場合は、以下を依存関係に追加します。

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

sbt を使用している場合は、以下を依存関係に追加します。

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.4-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>

例

Cloud Logging の Logback アペンダーを使用するように Logback を構成すると、SLF4J のロギング API を使用してログをリダイレクトできるようになります。サンプルをローカルまたは Google Cloud の外部で実行する場合は、Google Cloud の構成を指定します。次のスニペットは、アプリケーション内で SLF4J ファサードを使用してロギングを行う方法を示しています。


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 ハンドラから Cloud Logging API を使用することもできます。

依存関係のインストール

Maven を BOM ありで使用している場合は、以下を pom.xml ファイルに追加します。

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

Gradle を使用している場合は、以下を依存関係に追加します。

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

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

sbt を使用している場合は、以下を依存関係に追加します。

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

Visual Studio Code、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 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 handler では、次のデフォルトを使用して 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 ハンドラでは、LoggingEnhancerr のインスタンスを使用して、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");
  }
}

構成に際して、カスタムラベルの使用がサポートされていない場合があります。たとえば、Dataflow ログにはこれらのラベルが含まれません。

インストールの詳細については、Java 用 Cloud Logging ライブラリのドキュメントをご覧ください。公開バグトラッカーを使用して問題を報告することもできます。

Cloud Logging クライアントライブラリを使用してログを書き込む

Java 用 Cloud Logging クライアントライブラリを直接使用する方法については、Cloud Logging クライアントライブラリをご覧ください。

Google Cloud での実行

Java 用 Cloud Logging ライブラリを使用してログを書き込むアプリでは、基盤となるリソースのサービスアカウントにログ書き込み（roles/logging.logWriter） IAMのロールが必要です。ほとんどの Google Cloud 環境では、このロールを持つようにデフォルトのサービスアカウントが自動的に構成されます。

App Engine

App Engine では Cloud Logging が自動的に有効になり、アプリのデフォルトのサービスアカウントにログエントリを書き込む IAM 権限がデフォルトで付与されます。

App Engine スタンダード環境では、デフォルトで java.util.logging.Logger API を使用します。これは Cloud Logging に直接書き込みを行うため、簡単に構成できます。

詳しくは、App Engine のドキュメントでアプリケーションログの読み込みと書き込みに関する説明をご覧ください。

App Engine フレキシブル環境

App Engine フレキシブル環境では、java.util.logging は、デフォルトで ConsoleHandler を使用し、stdout と stderr にログを送信します。

Jetty ランタイムは、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 ランタイムで Trace ID ロギングが使用できます。

App Engine フレキシブル環境で実行すると、TraceLoggingEnhancer インスタンスがラベル trace_id を使用してスレッドセーフのトレース ID を各ログエントリに追加します。

Google Kubernetes Engine（GKE）

GKE は、デフォルトのサービスアカウントにログ書き込み（roles/logging.logWriter） IAM ロールを自動的に付与します。このデフォルトのサービスアカウントで Workload Identity を使用して、ワークロードが特定の Google Cloud API にアクセスできるようにする場合、追加の構成は必要ありません。ただし、カスタム IAM サービスアカウントで Workload Identity を使用する場合は、カスタムサービスアカウントにログ書き込みロール（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 Console から新しいインスタンスを作成する場合は、[インスタンスの作成] パネルの [ID と API へのアクセス] のセクションで作成します。Compute Engine のデフォルトサービスアカウントまたは別のサービスアカウントを使用し、[ID と API へのアクセス] セクションの [すべての Cloud API に完全アクセス権を許可] を選択します。どのサービスアカウントを選択する場合でも、Google Cloud コンソールの [IAM と管理] でログ書き込みロールが付与されていることを確認してください。

ローカルやその他の場所で実行する

自分のワークステーション、データセンターのコンピュータ、別のクラウドプロバイダの VM インスタンスでライブラリを実行するなど、Google Cloud の外部で Java 用 Cloud Logging ライブラリを使用するには、Google Cloud プロジェクト ID と適切なサービスアカウント認証情報を Java 用 Cloud Logging ライブラリに直接提供する必要があります。

既存のサービスアカウントの場合は、次の操作を行います。

サービスアカウントに IAM のログ書き込み（roles/logging.logWriter） IAM。ロールを付与します。IAM ロールの詳細については、アクセス制御をご覧ください。
アプリケーションのデフォルト認証情報を設定します。

サービスアカウントをお持ちでない場合は、サービスアカウントを作成します。このプロセスについては、サービスアカウントの作成をご覧ください。

認証に使用できる方法に関する一般的な情報については、用語: サービスアカウントをご覧ください。

ログを閲覧する

Google Cloud コンソールのナビゲーションパネルで、[ロギング] を選択してから、[ログエクスプローラ] を選択します。

[ログエクスプローラ] に移動

ログエクスプローラでは 1 つ以上のリソースを指定する必要がありますが、リソースの選択が明確でない場合があります。その場合は、次のヒントを参考にしてください。

アプリケーションを 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;）をクリックし、[高度なフィルタに変換] を選択します。
2. フィルタボックスに表示されているコンテンツをクリアします。
3. [フィルタを送信] をクリックします。
個々のエントリを調べてリソースを特定します。

詳細については、ログエクスプローラの使用をご覧ください。

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

ローカルやその他の場所で実行する

ログを閲覧する

Cloud Logging クライアントライブラリを使用してログを書き込む