Pipelines API トラブルシューティング

Google Genomics Pipelines API を使用すると、Google Compute Engine の仮想マシン(VM)でバッチ処理タスクを簡単に実行できます。このドキュメントでは、パイプラインで以下のような障害が発生した場合のトラブルシューティング情報の参照先について説明します。

パイプライン オペレーション リソース

pipelines.run() API が呼び出されると、パイプラインに関する重要な状態を維持するためにオペレーション リソースが作成されます。オペレーション名が返されるため、進行状況を追跡できます。

進行状況を追跡するためのオペレーションの主なフィールドは次のとおりです。

done

オペレーションが作成されると、done 値は false に設定されます。オペレーションが(成功または失敗)で完了すると、donetrue に設定されます。

error

オペレーションが失敗した場合は、done プロパティは true に設定され、エラーコードおよび message が返されます。次に例を示します。

オペレーションがキャンセルされた

エラーテキスト

error:
  code: 1
  message: Operation canceled at 2017-02-01T13:46:07-08:00

説明

オペレーションがキャンセルされました。ユーザーが operations.cancel API を使用したためです。

ファイルが見つからない

入力ファイル

エラーテキスト

error:
  code: 5
  message: '9: Failed to localize files: failed to copy the following files: "gs://my-bucket/my-path/input.txt
    -> /mnt/data/input.txt (cp failed: gsutil -q -m cp gs://my-bucket/my-path/input.txt
    /mnt/data/input.txt, command failed: CommandException: No URLs matched: gs://my-bucket/my-path/input.txt\nCommandException:
    1 file/object could not be transferred.\n)"'

説明

パイプラインに以下の入力パラメータが指定されていました。

localCopy: /mnt/data/input.txt
value: gs://my-bucket/my-path/input.txt

Cloud Storage のパス gs://my-bucket/my-path/input.txt にオブジェクトが見つかりませんでした。

出力ファイル

エラーテキスト

error:
  code: 5
  message: '10: Failed to delocalize files: failed to copy the following files: "/mnt/data/output.txt
    -> gs://my-bucket/my-path/
    (cp failed: gsutil -q -m cp -L /var/log/google-genomics/out.log /mnt/data/output.txt
    gs://my-bucket/my-path/,
    command failed: CommandException: No URLs matched: /mnt/data/output.txt\nCommandException:
    1 file/object could not be transferred.\n)"'

説明

パイプラインに以下の出力パラメータが指定されていました。

localCopy: /mnt/data/output.txt
value: gs://my-bucket/my-path

docker run の完了時に、オペレーションの Compute Engine VM の /mnt/data/output.txt にファイルが見つかりませんでした。

Docker イメージ

エラーテキスト

error:
  code: 5
  message: |
    8: Failed to pull image gcr.io/my-project-id/my-non-existent-image: "gcloud docker -- pull gcr.io/my-project-id/my-non-existent-image" failed: exit status 1: Using default tag: latest
    Pulling repository gcr.io/my-project-id/my-non-existent-image
    Tag latest not found in repository gcr.io/my-project-id/my-non-existent-image

説明

パイプラインで Docker イメージが gcr.io/my-project-id/my-non-existent-image として指定されていました。このイメージは存在しないため、Compute Engine VM にダウンロードできませんでした。

Docker イメージのアップロードに関するヘルプは、Container Registry への push をご覧ください。

VM のシャットダウン

エラーテキスト

error:
  code: 10
  message: '13: VM ggp-3407728597191315463 shut down unexpectedly.'

error:
  code: 10
  message: '14: VM ggp-3630732807397428672 stopped unexpectedly.'

説明

オペレーションの Compute Engine VM が予期せずシャットダウンしました。通常、これは以下の原因で発生します。

  • プリエンプティブ VM がプリエンプティブされています。VM がプリエンプティブされていたかどうかを判別するには、この手順を実施してください。
  • ユーザーが VM インスタンスを明示的に停止または削除しました。

失敗した Docker コマンド

error:
  code: 10
  message: |-
    11: Docker run failed: command failed: [STDERR]
    . See logs at gs://my-bucket/my-path/logging

説明

Docker コマンドが実行されましたが、ゼロ以外のコードで終了しました。

オペレーションの [STDERR] ブロックに必要な情報が記載されている可能性があります。

詳細については、オペレーション ログファイルをご覧ください。

metadata.events

パイプラインの実行の進行中、オペレーションの metadata.events 配列にイベントがタイムスタンプとともに送信されます。以下にパイプラインのイベントの典型的な例を示します。

metadata:
  events:
  - description: start
    startTime: '2016-06-21T22:11:19.033492348Z'
  - description: pulling-image
    startTime: '2016-06-21T22:11:19.033538217Z'
  - description: localizing-files
    startTime: '2016-06-21T22:11:41.986968591Z'
  - description: running-docker
    startTime: '2016-06-21T22:11:44.414132377Z'
  - description: delocalizing-files
    startTime: '2016-06-21T22:11:44.867186386Z'
  - description: ok
    startTime: '2016-06-21T22:11:48.363039120Z'

以下はパイプラインの Docker コマンドの実行が失敗した場合の例です。

metadata:
  events:
  - description: start
    startTime: '2016-06-22T17:26:19.774419593Z'
  - description: pulling-image
    startTime: '2016-06-22T17:26:19.774797917Z'
  - description: localizing-files
    startTime: '2016-06-22T17:27:51.700833219Z'
  - description: running-docker
    startTime: '2016-06-22T17:27:51.700872247Z'
  - description: fail
    startTime: '2016-06-22T17:27:54.305925814Z'

オペレーションがハングしているように見える場合は、VM を起動するのに十分な割り当てがないことが考えられます。オペレーションの進行中、割り当てに関する警告が events リストに追加されます。

metadata:
  events:
  - description: 'Warning: Quota ''CPUS'' exceeded. Limit: 24.0. Region: us-east1, will try again'
    startTime: '2017-02-11T07:51:45.984778139Z'
  - description: 'Warning: Creating VM and disk(s) would exceed "CPUS" in region us-east1, will try again'
    startTime: '2017-02-11T09:43:35.768859933Z'

パイプライン オペレーション ログファイル

パイプライン オペレーションには、ログが書き込まれる Cloud Storage のパスが含まれます。3 つのログファイルがパイプラインの VM から書き込まれます。VM からファイルが書き込まれるため、VM が起動されたことがない場合にはログファイルは存在しません。

書き込まれる 3 つのファイルは以下のとおりです。

  • パイプライン ログ: パイプラインのソフトウェアによって書き込まれるログ。パイプラインのソフトウェアは Docker イメージの pull、ファイルのローカライズ、Docker コマンドの実行、ファイルのローカライズ解除を行います。
  • stderr ログ: Docker コマンドからの stderr ログ
  • stdout ログ: Docker コマンドからの stdout ログ

既存のオペレーションからロギングパスを取得するには、コマンドラインで以下を実行します。

gcloud alpha genomics operations describe <operation-id> \
  --format='value(metadata.request.pipelineArgs.logging)'

Cloud Storage のパスは以下のいずれかです。

  • シンプルな Cloud Storage のパス
  • 「.log」で終わる Cloud Storage のパス

シンプルな Cloud Storage のパス

シンプルな Cloud Storage のパスが指定された場合は、ファイル システム フォルダと同様に処理されます。たとえば、gs://my-bucket/my-path/my-pipeline と指定した場合、生成されるログファイルの名前は次のようになります。

  • gs://my-bucket/my-path/my-pipeline/<operation-id>.log
  • gs://my-bucket/my-path/my-pipeline/<operation-id>-stderr.log
  • gs://my-bucket/my-path/my-pipeline/<operation-id>-stdout.log

「.log」で終わる Cloud Storage のパス

「.log」で終わる Cloud Storage のパスを指定できます。たとえば、gs://my-bucket/my-path/my-pipeline.log と指定した場合、生成されるログファイルの名前は次のようになります。

  • gs://my-bucket/my-path/my-pipeline.log
  • gs://my-bucket/my-path/my-pipeline-stderr.log
  • gs://my-bucket/my-path/my-pipeline-stdout.log

パイプライン VM

パイプラインを実行する Compute Engine VM の名前とゾーンは、オペレーションの metadata.runtimeMetadata.computeEngine 要素の下にあります。インスタンスの実行中、これを検査できます。

既存のオペレーションから zone/instanceName を取得するには、コマンドラインで以下を実行します。

gcloud alpha genomics operations describe <operation-id> \
   --format='value[separator=/]
                 (metadata.runtimeMetadata.computeEngine.zone,
                  metadata.runtimeMetadata.computeEngine.instanceName)'

VM ロギング

VM ロギングには以下が含まれます。

  • Linux システム ロギング。
  • ファイルのローカライズとローカライズ解除のロギング。
  • パイプライン Docker ロギング。

VM ログを表示するには、いくつかの方法があります。

  • Google Cloud Console のログビューアで以下の手順を実施します。

    • 最初のプルダウン メニューで、[GCE VM インスタンス] を選択します。
    • 検索ボックスに VM の名前を入力します。
    • [すべてのログ] プルダウン メニューで、[syslog] を選択します。
  • Google Cloud Console のインスタンスの詳細ページで、[シリアルポートを表示] ボタンをクリックします。

  • gcloud compute instances get-serial-port-output zone/instanceName を実行します。

上記の方法はいずれも、VM が動作している場合に機能します。VM が終了している場合は、ログには Google Cloud Console のログビューアからしかアクセスできません。

パイプラインの VM への SSH 接続

ファイル システム(使用可能なディスク容量)を確認するためにパイプラインの VM への SSH セッションを開いたり、実行中の Docker コンテナに接続したりできます。

前述の gcloud コマンドの zone/instanceName を次のように gcloud compute ssh コマンドに直接渡すことができます。

gcloud compute ssh zone/instanceName

Docker コマンドの実行または出力ファイルのローカライズ解除が失敗した場合、VM は自動的に削除されます。VM の実行時間を延長して SSH で接続できるようにするために、keepVmAliveOnFailureDuration を使用できます。

同様に、Docker コマンドの実行に VM に SSH 接続するための時間を確保する必要がある場合は、Docker コマンドの先頭に sleep を追加できます。次に例を示します。

sleep $((5*60)); mycommand.sh

上記の例では、時間が 5 分長くなります。

ブート ボリュームの容量が不足している場合、インスタンスに SSH で接続できないことがあります。この状況ではデバッグが難しくなります。VM ログでこの問題の手がかりを見つけることができます。デバッグするために、処理の早い段階で既存のパイプライン オペレーションをキャンセルして再作成し、インスタンスに SSH で接続することが必要になる可能性があります。

ファイル システムの使用可能なディスク容量の検査

パイプラインが失敗する単純な原因として、ディスク容量の不足が考えられます。使用可能なディスク容量を調べるには、次のように入力します。

df -k -h

目的のボリュームの Mounted on 列を確認します。ブート ボリュームは / にマウントされます。

パイプライン用に追加されるディスク リソースはすべて、パイプライン定義で指定される mountPoint 値に「マウント」されます。

実行中の Docker コンテナへの接続

docker exec コマンドを使用して、実行中の Docker コンテナに接続できます。最初にコンテナの ID または名前を取得する必要があります。

docker ps コマンドを実行すると、実行中のコンテナのリストが表示されます。パイプライン VM インスタンスには 1 つのコンテナしかありません。次に例を示します。

$ sudo docker ps
CONTAINER ID        IMAGE                COMMAND                CREATED             STATUS              PORTS               NAMES
24e6a7c1e573        java:openjdk-8-jre   "/tmp/ggp-532475336"   10 minutes ago      Up 10 minutes                           clever_chandrasekhar

コンテナ ID のみを取得するには、--format フラグを使用します。

$ sudo docker ps --format '{{.ID}}'
24e6a7c1e573

実行中のコンテナに接続して bash シェルを実行するには、次のように入力します。

sudo docker exec -t -i <container-id> /bin/bash

次に例を示します。

$ sudo docker exec -t -i $(sudo docker ps --format '{{.ID}}') /bin/bash
root@24e6a7c1e573:/#

VM モニタリング

すべてのパイプライン VM には Stackdriver Monitoring エージェントがインストールされているため、Stackdriver モニタリングとアラートを設定できます。

パイプラインが実行されない、または実行が停止されない

パイプラインの実行を開始できないか、実行中のパイプラインをキャンセルできません。

Google Cloud Platform Console の IAM ページで、関連プロジェクトのサービス アカウントのメンバーリストに Genomics サービス エージェントの役割が表示されていることを確認します(@genomics-api.google.com.iam.gserviceaccount.com で終わるプロジェクトのサービス アカウントを探してください)。

Genomics サービス エージェントの役割がメンバーリストに表示されていない場合は、gcloud を使用して、genomics.serviceAgent 役割を関連プロジェクトのサービス アカウントに追加します。この役割には、プロジェクト内で Compute Engine インスタンスを停止および開始する権限が含まれています。

PROJECT_IDPROJECT_NUMBER を見つけるには、プロジェクトの識別をご覧ください。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@genomics-api.google.com.iam.gserviceaccount.com \
    --role=roles/genomics.serviceAgent
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...