Node.js 用 Cloud デバッガの設定

概要

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

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

Cloud Debugger は、次のコンピューティング環境上の Node.js 6 以降で使用できます。

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 デバッガ API が有効になっていることを確認します。Cloud デバッガは、ほとんどのプロジェクトでデフォルトで有効になっています。
Cloud デバッガ API を有効にする

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

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

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

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

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

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

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

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

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

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

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

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

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

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

App Engine

  1. npm を使用してパッケージをインストールします。

    npm install --save @google-cloud/debug-agent
    
  2. アプリのメイン スクリプトまたはエントリ ポイントの先頭でエージェントを有効にします(@google/cloud-trace を使用している場合は、その後)。

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
    

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

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

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 エージェントを追加します。

    RUN  npm install --save @google-cloud/debug-agent
    
  3. アプリのメイン スクリプトまたはエントリ ポイントの先頭でエージェントを有効にします(@google/cloud-trace を使用している場合は、その後)。

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    ここで

    • SERVICE はアプリの名前です。例: MyAppBackendFrontend
    • VERSION はバージョンです。例: v1.0build_147v20170714

    これらの値を環境変数から設定することをおすすめします。この方法では、デプロイごとにソースコードを変更する必要はありません。

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

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

コンソール

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

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

    ノードプールのオプション

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

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

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

  3. 以下の行を Dockerfile に追加して、デバッグ エージェントを追加します。

        RUN  npm install --save @google-cloud/debug-agent
    
  4. アプリのメイン スクリプトまたはエントリ ポイントの先頭でエージェントを有効にします(@google/cloud-trace を使用している場合は、その後)。

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    ここで

    • SERVICE はアプリの名前です。例: MyAppBackendFrontend
    • VERSION はバージョンです。例: v1.0build_147v20170714

    これらの値を環境変数から設定することをおすすめします。この方法では、デプロイごとにソースコードを変更する必要はありません。

Compute Engine

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

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  2. npm を使用してパッケージをインストールします。

    npm install --save @google-cloud/debug-agent
    
  3. アプリのメイン スクリプトまたはエントリ ポイントの先頭でエージェントを有効にします(@google/cloud-trace を使用している場合は、その後)。

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    ここで

    • SERVICE はアプリの名前です。例: MyAppBackendFrontend
    • VERSION はバージョンです。例: v1.0build_147v20170714

    これらの値を環境変数から設定することをおすすめします。この方法では、デプロイごとにソースコードを変更する必要はありません。

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

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

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

  1. npm を使用してパッケージをインストールします。

    npm install --save @google-cloud/debug-agent
    
  2. アプリのメイン スクリプトまたはエントリ ポイントの先頭でエージェントを有効にします(@google/cloud-trace を使用している場合は、その後)。

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

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

    enableCanary: false
    

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

ローカルと他の場所

  1. npm を使用してパッケージをインストールします。

    npm install --save @google-cloud/debug-agent
    
  2. サービス アカウントの認証情報をダウンロードします。

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

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

  3. ダウンロードした認証情報でエージェントを構成し、有効にします。

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

    require('@google-cloud/debug-agent').start({
      projectId: 'your-project-id',
      keyFilename: '/path/to/key.json',
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

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

    enableCanary: false
    

    ここで

    • SERVICE はアプリの名前です。例: MyAppBackendFrontend
    • VERSION はバージョンです。例: v1.0build_147v20170714

    これらの値を環境変数から設定することをおすすめします。この方法では、デプロイごとにソースコードを変更する必要はありません。

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

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