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 on Google Cloud その他の場所で実行されている VM とコンテナ Cloud Functions

Cloud デバッガの設定

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

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

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

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

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

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

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

Java 用 デバッガ エージェントは、スナップショットまたはログポイントを設定するたびにカナリア スナップショットとログポイントを使用できます。

デバッガ エージェントは、スナップショットとログポイントをカナリア処理し、デバッガ エージェントのあらゆる潜在的なバグから大規模なジョブを保護します。潜在的なバグが存在すると、スナップショットまたはログポイントが適用されたときにジョブ全体が停止してしまう可能性があります。

これを緩和するために、デバッガはスナップショットとログポイントが設定されるたびに、実行中のインスタンスのサブセットでカナリア処理を繰り返します。デバッガは、スナップショットまたはログポイントが実行中のインスタンスに悪影響がないことを確認した後で、すべてのインスタンスにスナップショットまたはログポイントを適用します。

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

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

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

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

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

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

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

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

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

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

App Engine 標準環境

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

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

App Engine フレキシブル環境

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

Google 提供の Java 用ベースイメージを使用するカスタム ランタイムの場合、デフォルトでデバッガが含まれています。デフォルトのエントリ ポイントを使用している場合、構成は不要です。Cloud Console の [デバッグ] ページには、アプリのビルドに使用された 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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

    • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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

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

コンソール

コンソールを使用して Debugger を有効にする方法は次のとおりです。

  1. クラスタタイプを選択したら、[ノードプール] ペインで [その他の設定項目] をクリックします。

    [その他の設定項目] ボタンの上の赤い長方形を示すノードプールのフィールド。

  2. [セキュリティ] ペインから次のいずれかを選択します。

    • [すべての Cloud API に完全アクセス権を許可]

    • [各 API にアクセス権を設定]。次に、Cloud Debugger の [有効] を選択します。

  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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

    • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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

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

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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

    • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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

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

ウェブサーバー

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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

  • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

  • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

  • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

Cloud Run および Cloud Run for Anthos on Google Cloud

  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

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

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

ローカルと他の場所

  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 デバッガ サービスの認証を行う必要があります。

    Cloud Console の [サービス アカウント] ページを使用して、既存のサービス アカウントの認証情報ファイルを作成するか、新しいサービス アカウントを作成します。サービス アカウントには少なくとも、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 はアプリの名前です。Cloud Console では、この名前とバージョンでアプリを識別します。例: MyAppBackendFrontend

    • VERSION はアプリのバージョン(例: ビルド ID)です。Cloud Console は、実行中のアプリを MODULE - VERSION のように表示します。例: v1.0build_147v20160520

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

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

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