Python 用 Cloud デバッガの設定

概要

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

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

Cloud デバッガは、次のコンピューティング環境上の Python 3 で使用できます。

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

Cloud デバッガの設定

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

プロジェクトで Cloud デバッガ API が有効になっていることを確認します。
使用しているコンピューティング環境にデバッガをインストールして構成します。
ソースコードを選択します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

App Engine 標準環境

Python 3.7 または Python 3.8

Python 3.7 または Python 3.8 を使用している場合は、次の手順でデバッガエージェントを手動で有効にする必要があります。

app.yaml ファイルに次の行が含まれていることを確認します。
```
runtime: python37
or
runtime: python38
```
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します（バージョン 1.* のみ）。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
    breakpoint_enable_canary=True
  )
except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
 breakpoint_enable_canary=False
```
requirements.txt に google-python-cloud-debugger を追加します。
デプロイされたアプリに一致するソースコードを Cloud Console の [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

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

App Engine フレキシブル環境

App Engine Python ランタイムまたはカスタムランタイムでデバッガを使用できます。

App Engine フレキシブル VM インスタンスが実行されていることを確認します。
- 64 ビット Debian Linux イメージ
- Python 3
app.yaml ファイルに次の行が含まれていることを確認します。
```
runtime: python
env: flex
```
カスタムランタイムを使用している場合は、runtime: custom を使用します。
requirements.txt に google-python-cloud-debugger を追加します。
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します（バージョン 1.* のみ）。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
    breakpoint_enable_canary=True
  )
except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```
デプロイされたアプリに一致するソースコードを Cloud Console の [デバッグ] ページに自動的に表示するには、ソースコードを自動的に選択するをご覧ください。

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

Google Kubernetes Engine

gcloud

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

次のいずれかのアクセススコープでクラスタを作成します。
- 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
```
注: クラスタの作成後に、アクセススコープを変更することはできません。
Debugger パッケージをアプリに追加します。

requirements.txt ファイルを使用している場合は、次の行を追加します。
```
  google-python-cloud-debugger
```
Dockerfile を使用している場合は、次の行を追加します。
```
  RUN pip install google-python-cloud-debugger
```
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します。

カナリア処理を有効にしてデバッグするには:
```
  try:
    import googleclouddebugger
    googleclouddebugger.enable(
      breakpoint_enable_canary=True
    )
  except ImportError:
    pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
  breakpoint_enable_canary=False
```

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

これで Debugger が使用できるようになりました。

コンソール

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

クラスタタイプを選択したら、[ノードプール] ペインで [その他の設定項目] をクリックします。
[セキュリティ] ペインから次のいずれかを選択します。
- [すべての Cloud API に完全アクセス権を許可]。
- [各 API にアクセス権を設定]。次に、Cloud Debugger の [有効] を選択します。
Debugger パッケージをアプリに追加します。

requirements.txt ファイルを使用している場合は、次の行を追加します。
```
google-python-cloud-debugger
```
Dockerfile を使用している場合は、次の行を追加します。
```
RUN pip install google-python-cloud-debugger
```
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
    breakpoint_enable_canary=True
  )
except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```

これで Debugger が使用できるようになりました。

Compute Engine

Compute Engine VM インスタンスが実行されていることを確認します。
- 64 ビット Debian Linux イメージ
- Python 3
Compute Engine VM インスタンスが [すべての Cloud API に完全アクセス権を許可] アクセススコープオプションで作成されていることを確認するか、次のいずれかのアクセススコープを使用します。
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud_debugger
Debugger エージェントをダウンロードします。

Python 用 Debugger のインストールは、次のように [pip][pip] を使用してインストールする方法が最も簡単です。
```
pip install google-python-cloud-debugger
```
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
    module='[MODULE]',
    version='[VERSION]'
    breakpoint_enable_canary=True
  )
except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```
コードを変更できない場合は、Stackdriver Debugger エージェントをモジュールとして実行します。

カナリア処理を有効にしてデバッグするには:
```
python -m googleclouddebugger \
      --module=[MODULE] \
      --version=[VERSION] \
      --breakpoint_enable_canary=True
      -- \
      myapp.py
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```
注: デバッガをモジュールとして実行する場合、--breakpoint_enable_canary の値は文字列です。True 以外の値は False として扱われます。

コマンドのプレースホルダを次のように置き換えます。
- [MODULE] はアプリの名前です。
  これはバージョンとともに、Cloud Console の [デバッグ] ページでデバッグターゲットを識別するために使用されます。
  例: MyApp、Backend、Frontend。
- [VERSION] はアプリのバージョンです（ビルド ID など）。
  Cloud Console の [デバッグ] ページには、実行中のバージョンが [MODULE] - [VERSION] のように表示されます。
  値の例: v1.0、build_147、v20170714。

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

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

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

Python パッケージ。

requirements.txt ファイルを使用している場合は、次の行を追加します。
```
google-python-cloud-debugger
```
そうでない場合は、次の行を Dockerfile に追加します。
```
RUN pip install google-python-cloud-debugger
```
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
    breakpoint_enable_canary=True
  )

except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```

これで Debugger が使用できるようになりました。

ローカルと他の場所

ワークステーションが実行されていることを確認します。
- 64 ビット Debian Linux イメージ
- Python 3
Debugger エージェントをダウンロードします。

Python 用 Debugger のインストールは、次のように [pip][pip]{: .external} を使用してインストールする方法が最も簡単です。
```
pip install google-python-cloud-debugger
```
サービスアカウントの認証情報をダウンロードします。

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

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

サービスアカウントの JSON ファイルを Python 用 Cloud デバッガエージェントとともに配置します。
初期化コードの main 関数や manage.py（Django ウェブフレームワークを使用している場合）などに、なるべく早い段階で次の行を追加します。

カナリア処理を有効にしてデバッグするには:
```
try:
  import googleclouddebugger
  googleclouddebugger.enable(
      module='[MODULE]',
      version='[VERSION]',
      breakpoint_enable_canary=True
      service_account_json_file='/opt/cdbg/gcp-svc.json')
except ImportError:
  pass
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```
コードを変更できない場合は、Stackdriver Debugger エージェントをモジュールとして実行します。

カナリア処理を有効にしてデバッグするには:
```
python \
    -m googleclouddebugger \
    --module=[MODULE] \
    --version=[VERSION] \
    --breakpoint_enable_canary=True
    --service_account_json_file=/opt/cdbg/gcp-svc.json \
    -- \
    myapp.py
```
カナリア処理を有効にせずにデバッグするには、breakpoint_enable_canary パラメータを False に設定します。
```
breakpoint_enable_canary=False
```
注: デバッガをモジュールとして実行する場合、--breakpoint_enable_canary の値は文字列です。True 以外の値は False として扱われます。

コマンドのプレースホルダを次のように置き換えます。
- [MODULE] はアプリの名前です。
  これはバージョンとともに、Cloud Console の [デバッグ] ページでデバッグターゲットを識別するために使用されます。
  例: MyApp、Backend、Frontend。
- [VERSION] はアプリのバージョンです（ビルド ID など）。
  Cloud Console の [デバッグ] ページには、実行中のバージョンが [MODULE] - [VERSION] のように表示されます。
  値の例: v1.0、build_147、v20170714。
- service_account_json_file を指定する代わりに、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用できます。

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

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

Python 用 Cloud デバッガの設定

概要

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

Cloud デバッガの設定

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

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

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

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

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

App Engine 標準環境

Python 3.7 または Python 3.8

App Engine フレキシブル環境

Google Kubernetes Engine

gcloud

コンソール

Compute Engine

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

ローカルと他の場所

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

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

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

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