Java 用 Cloud デバッガの設定

概要

このページでは、Cloud デバッガを使用できるように、環境と Java アプリケーションを構成する方法について説明します。環境によっては、Cloud デバッガ エージェントがデータを送信できるようにするためにアクセス スコープを明示的に指定する必要があります。できるだけ幅広いアクセススコープを設定し、Identity and Access Managementを使用してアクセスを制限することをおすすめします。このおすすめの方法に沿って、オプション cloud-platform を使用して、すべての Cloud API がアクセス スコープになるように設定します。

言語バージョンとコンピューティング環境

Cloud デバッガは、以下のコンピューティング環境上の Java バージョン 7、8、9、11 で使用できます。

App Engine スタンダード環境 App Engine フレキシブル環境 Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos その他の場所で実行されている VM とコンテナ Cloud Functions

Cloud デバッガの設定

Cloud デバッガを設定するには、次のタスクを実行します。

  1. プロジェクトで Cloud デバッガ API が有効になっていることを確認します。

  2. 使用しているコンピューティング環境にデバッガをインストールして構成します。

  3. ソースコードを選択します。

Cloud デバッガ API が有効になっていることを確認する

Cloud デバッガを使用する前に、Cloud Debugger API が有効になっていることを確認します。Cloud デバッガは、ほとんどのプロジェクトでデフォルトで有効になっています。
Cloud デバッガ API を有効にする

カナリア スナップショットとログポイント

スナップショットとログポイントが実行中のすべてのインスタンスに同時に読み込まれ、デバッガエージェントの潜在的なバグが原因でジョブが停止するのを防ぐには、デバッガエージェントのカナリアモードを有効にします。カナリア モードを有効にすると、スナップショットまたはログポイントが実行中のインスタンスのサブセットに適用され、Debugger はスナップショットまたはログポイントがこれらのインスタンスに悪影響を及ぼさないことを検証します。検証が完了すると、スナップショットまたはログポイントがすべてのインスタンスに適用されます。

カナリア モードでデバッガを使用する方法については、デバッグ スナップショットとデバッグ ログポイントのページをご覧ください。

カナリア スナップショットとログポイントを有効にする

最新バージョンの カナリア エージェントをインストールするときに、カナリア処理を有効にするか無効にするかを選択します。カナリア処理はデフォルトで無効になっています。

カナリア スナップショットとログポイントを有効にするタイミング

デプロイメントと本番環境の重要なワークロードを保護するため、ワークロードのデバッグ時にはカナリア処理を有効にします。

単一インスタンスの場合でもカナリア処理を有効にしてデバッグできますが、単一インスタンスが実行される際にスナップショットやログポイントのカナリア処理は行われません。

カナリア スナップショットとログポイントを有効にすべきでない場合

Cloud Functions を使用するジョブなど、実行時間が 40 秒未満のワークロードではカナリア処理を有効にしないでください。

スナップショットがトリガーとなるサイクルを高速化する場合、カナリア処理を有効にしないでください。

デバッガ エージェントをカナリア スナップショットとログポイントをカナリア処理しないように構成するには、使用している Google Cloud プラットフォームのインストール手順をご覧ください。

App Engine 標準環境

デバッガはデフォルトで有効になっています。構成は不要です。Google Cloud コンソールの [デバッグ] ページには、アプリのビルドに使用された Java ソースファイルが表示されます。

なお、URL 取得が有効になっている場合、Google Cloud コンソールは動作しません。

詳細については、ソースコードを自動的に選択するをご覧ください。

App Engine フレキシブル環境

デフォルトでは、Java ランタイムにデバッガは有効になっています。構成は不要です。Google Cloud コンソールの [デバッグ] ページには、アプリのビルドに使用された Java ソースファイルが表示されます。

Google 提供の Java 用ベースイメージを使用するカスタム ランタイムの場合、デフォルトでデバッガが含まれています。デフォルトのエントリ ポイントを使用している場合、構成は不要です。Google Cloud コンソールの [デバッグ] ページには、アプリのビルドに使用された Java ソースファイルが表示されます。

他のベースイメージを使用して構築されたカスタム ランタイムで Cloud デバッガを使用するには、Compute Engine の設定手順に従ってください。

詳細については、ソースコードを自動的に選択するをご覧ください。

Google Kubernetes Engine

gcloud

gcloud を使用して Debugger を有効にする方法は次のとおりです。

  1. 次のいずれかのアクセス スコープでクラスタを作成します。

    • https://www.googleapis.com/auth/cloud-platform は、すべての Google Cloud API へのアクセス権をクラスタに付与します。

    • https://www.googleapis.com/auth/cloud_debugger は、Debugger API のみへのアクセス権をクラスタに付与します。このアクセス スコープを使用して、クラスタのセキュリティを強化します。

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

  2. 以下の行を Dockerfile に追加して、Debugger エージェントをコンテナ化されたアプリに追加し、アプリのデプロイ時に初期化します。 

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
RUN mkdir /opt/cdbg && \
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    以前のバージョンのエージェントをインストールするには、URL を次の値に変更します。

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER は、使用するエージェントのバージョン（https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz など）で置き換えます。カナリア処理は、2.25 より前のバージョンでは使用できません。デバッガ エージェントのバージョンを取得するには、Java エージェントの GitHub ページに移動してください。

  3. デバッガ エージェントを実行するには、次の行を Dockerfile に追加します。

    カナリア処理を有効にしてデバッグするには:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    コマンドのプレースホルダを次のように置き換えます。

    • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

    • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

    • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

    • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

これで、コンテナ化されたアプリをデプロイするときにデバッガを使用できるようになりました。

デプロイされたアプリに一致するソースコードを Google Cloud コンソールの [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

コンソール

Google Cloud Console を使用してデバッガを有効にするには、次の手順を実行します。

  1. [ノードプール] セクションで、[セキュリティ] を選択し、[各 API にアクセス権を設定] を選択します。

  2. デバッガを有効にします。

    クラスタで Debugger API が有効になっている。

  3. 省略可: [すべての Cloud APIs に完全アクセス権を許可] を選択します。

  4. デバッガ エージェントを実行するには、次の行を Dockerfile に追加します。

    カナリア処理を有効にしてデバッグするには:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    コマンドのプレースホルダを次のように置き換えます。

    • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

    • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

    • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

    • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

これで、コンテナ化されたアプリをデプロイするときにデバッガを使用できるようになりました。

デプロイされたアプリに一致するソースコードを Google Cloud コンソールの [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

Compute Engine

Google Compute Engine インスタンス上で実行されている Java アプリには Cloud デバッガを使用できます。アプリで実行中のすべてのインスタンスに対して Debugger を有効にすることをおすすめします。

  1. Compute Engine VM インスタンスが実行されていることを確認します。

    • 64 ビット Debian Linux イメージ
    • Java JDK バージョン 7、8 または 9

  2. Compute Engine VM インスタンスが [すべての Cloud API に完全アクセス権を許可] アクセス スコープ オプションで作成されていることを確認するか、次のいずれかのアクセス スコープを使用します。

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger

  3. ビルド済みのエージェント パッケージをダウンロードします。

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
sudo mkdir /opt/cdbg
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    以前のバージョンのエージェントをインストールするには、URL を次の値に変更します。

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER は、使用するエージェントのバージョン（https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz など）で置き換えます。カナリア処理は、2.25 より前のバージョンでは使用できません。デバッガ エージェントのバージョンを取得するには、Java エージェントの GitHub ページに移動してください。

  4. Java の呼び出しにエージェントを追加します。
    （Tomcat または Jetty を使用している場合は、ウェブサーバーのセクションをご覧ください）。

    カナリア処理を有効にしてデバッグするには:

    # Start the agent when the app is deployed.
java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    コマンドのプレースホルダを次のように置き換えます。

    • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

    • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

    • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

    • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

これで、アプリでデバッガを使用できるようになりました。

デプロイされたアプリに一致するソースコードを Google Cloud コンソールの [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

ウェブサーバー

Java のウェブサーバーは通常、ブートストラップ プロセスを通じて開始し、ウェブサーバーごとに Java オプションを独自にカスタマイズしています。

Tomcat

次の行を /etc/default/tomcat7 または /etc/default/tomcat8 に追加します。

カナリア処理を有効にしてデバッグするには:

# Start the agent when the app is deployed.
JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true"

カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

-Dcom.google.cdbg.breakpoints.enable_canary=false

コマンドのプレースホルダを次のように置き換えます。

  • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

  • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

  • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

  • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

Docker コンテナで Tomcat を実行している場合は、Dockerfile に次の行を追加します。

カナリア処理を有効にしてデバッグするには:

# Start the agent when the app is deployed.
ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true

カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

-Dcom.google.cdbg.breakpoints.enable_canary=false

コマンドのプレースホルダを次のように置き換えます。

  • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

  • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

  • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

  • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

Jetty

/var/lib/jetty/start.d に次の行を追加します。

カナリア処理を有効にしてデバッグするには:

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so \
-Dcom.google.cdbg.module=MODULE \
-Dcom.google.cdbg.version=VERSION \
-Dcom.google.cdbg.breakpoints.enable_canary=true

カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

-Dcom.google.cdbg.breakpoints.enable_canary=false

コマンドのプレースホルダを次のように置き換えます。

  • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

  • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

  • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

  • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

Cloud Run と Cloud Run for Anthos

  1. 次のコマンドを Dockerfile に追加して、Debugger エージェントをインストールするディレクトリを作成します。Debugger エージェントのアーカイブをダウンロードし、インストール ディレクトリに解凍します。

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
RUN mkdir /opt/cdbg && \
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    以前のバージョンのエージェントをインストールするには、URL を次の値に変更します。

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    VERSION_NUMBER は、使用するエージェントのバージョン（https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz など）で置き換えます。カナリア処理は、2.25 より前のバージョンでは使用できません。デバッガ エージェントのバージョンを取得するには、Java エージェントの GitHub ページに移動してください。

    Java の呼び出しを見つけ、次のフラグを追加してデバッガ エージェントを初期化します。

    カナリア処理を有効にしてデバッグするには:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    コマンドのプレースホルダを次のように置き換えます。

    • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

[デバッグ] ページで、ソースコードのロケーションを選択します。デプロイされたアプリに一致するソースコードを Google Cloud コンソールの [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

これでデバッガが使用できるようになりました。

ローカルと他の場所

  1. ビルド済みのデバッガ エージェント パッケージをダウンロードします。

    mkdir /opt/cdbg
wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz | \
    tar xvz -C /opt/cdbg

  2. サービス アカウントの認証情報をダウンロードします。
    Google Cloud でホストされていないマシンで Java 用 Cloud デバッガ エージェントを使用するには、エージェントが Google Cloud サービス アカウントの認証情報を使用して Cloud デバッガ サービスの認証を行う必要があります。

    Google Cloud コンソールの [サービス アカウント] ページを使用して、既存のサービス アカウントの認証情報ファイルを作成するか、新しいサービス アカウントを作成します。サービス アカウントには少なくとも、Cloud Debugger Agent の役割が必要です。

    サービス アカウントの JSON ファイルを Java 用 Cloud デバッガ エージェントとともに配置します。

  3. Java の呼び出しにエージェントを追加します。

    カナリア処理を有効にしてデバッグするには:

    java -agentpath:/opt/cdbg/cdbg_java_agent.so \
  -Dcom.google.cdbg.module=MODULE \
  -Dcom.google.cdbg.version=VERSION \
  -Dcom.google.cdbg.breakpoints.enable_canary=true \
  -Dcom.google.cdbg.auth.serviceaccount.enable=true \
  -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json \
  -jar PATH_TO_JAR_FILE

    カナリア処理を有効にせずにデバッグするには、enable_canary フラグを false に設定します。

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    コマンドのプレースホルダを次のように置き換えます。

    • PATH_TO_JAR_FILE は、アプリの JAR ファイルへの相対パスです。例: ~/myapp.jar

    • MODULE はアプリの名前です。 たとえば、MyApp、Backend、Frontend などです。

    • VERSION はアプリのバージョンまたはビルド ID です。たとえば、v1.0 や build_147 です。リリース プロセスに基づいてバージョン番号を決定し、その値を設定できます。

    • MODULE と VERSION は両方とも Google Cloud Console に MODULE - VERSION として表示されます。たとえば、MyApp - v1.0、Backend - build_147 などです。

    • auth.serviceaccount.jsonfile システム プロパティを追加せずに、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用できます。

これで、アプリでデバッガを使用できるようになりました。

Google Cloud コンソールの [デバッグ] ページでは、ローカル開発向けに、ローカルにあるソースファイルをアップロードせずに表示できます。ソースコードを手動で選択するをご覧ください。