Amazon Omics Workflows ZIP 圧縮したワークフロー定義ファイルのディレクトリ構成を誤った場合のエラーの出力例

大村 保貴

2023.03.04

Omics Workflows で解析処理を走らせてエラーになりました。切り分けた結果 Nestflow のワークフロー定義ファイル（.nf）の ZIP 圧縮時のディレクトリ構造を誤り原因でした。本記事では同じ原因でエラーになったとき疑うべきポイントを紹介します。

確認結果

ワークフロー定義ファイルの ZIP 圧縮時の内部ディレクトリ構成が適切でない場合、残念ながらエラーメッセージ、ログから原因を特定が困難です。切り分けする際は以下の箇所を確認してください。

  • CloudWatch Logs のログにはSTATING TASKのログが記録されない
    • 成功時はRUNNING_WORKFLOWのあとSTARTING_TASKへ遷移
    • 失敗時はRUNNING_WORKFLOW"のあとにSTOPPING_RUNへ遷移
  • マネージメントコンソールに表示されるエラーメッセージからは原因特定はできない
  • AWS CLI から確認しても原因特定に繋がるメッセージは確認できない
  • 実行から失敗（FAILED）まで約5分かかる

Omics Workflows のワークフロー定義

ワークフローの定義は WDL か Nextflow をサポートしています。ここでは Nextflow で定義したワークフローを例に紹介します。

Omics Workflows 実行時に外部からのパラメーターとしてgreetingとaddresseeの値を受け取って、受け取った値の内容を書き出したファイルを出力するといった内容のワークフローを定義しました。こちらのワークフロー定義はワークショップで紹介されている Hello World 的なサンプルです。

main.nf

nextflow.enable.dsl = 2

params.greeting = 'hello'
params.addressee = null

if (!params.addressee) exit 1, "required parameter 'addressee' missing"

process Greet {
    publishDir '/mnt/workflow/pubdir'
    input:
        val greeting
        val addressee

    output:
        path "output", emit: output_file

    script:
        """
        echo "${greeting} ${addressee}" | tee output
        """
}

workflow {
    Greet(params.greeting, params.addressee)
}

上記ワークフロー定義のファイル（main.nf）を Omics Workflows でワークフローを作成するときにアップロードします。アップロード方法は S3 経由か、マネージメントコンソールから直接ファイルのアップロードにも対応しています。

アップロード時にファイルをZIP 圧縮必須となっています。ZIP 圧縮したときの内部のディレクトリ構成がポイントです。正しい内部ディレクトリ構成と、エラーになったディレクトリ構成を説明します。

正しい内部ディレクトリ構成

main.nfをsample.nf.zipという名前で ZIP 圧縮しました。ZIP 圧縮後の階層以下の様にディレクトリ直下にmain.nfがあれば正しいです。

正しい階層

$ zipinfo -lht sample.nf.zip
Archive:  sample.nf.zip
Zip file size: 659 bytes, number of entries: 2
-rw-r--r--  3.0 unx      122 tx       78 defN 23-Jan-13 13:35 parameter.template.json
-rw-r--r--  3.0 unx      470 tx      243 defN 23-Jan-13 13:34 main.nf
2 files, 592 bytes uncompressed, 321 bytes compressed:  45.8%

悪い内部ディレクトリ構成

悪い例は以下の様にsampleディレクトリ配下にmain.nfファイルがあり、ディレクトリ直下にmain.nfないとエラーの原因になります。

悪い階層

$ zipinfo -lht sample.nf.zip
Archive:  sample.nf.zip
Zip file size: 563 bytes, number of entries: 2
drwxr-xr-x  3.0 unx        0 bx        0 stor 23-Feb-28 13:02 sample/
-rw-r--r--  3.0 unx      470 tx      243 defN 23-Feb-28 13:01 sample/main.nf
2 files, 470 bytes uncompressed, 243 bytes compressed:  48.3%

あるべき内部のディレクトリ構成はご理解いただけたでしょうか。かりに悪い内部ディレクトリ構成の ZIP ファイルをアップロードして、ワークフローを作成したときどういったエラーになるのかを次に紹介します。

悪い内部ディレクトリ構成のワークフローを利用

悪い内部ディレクトリ構成の ZIP ファイルをアップロードしワークフローを作成します。

パラメーターを定義しました。

ワークフローを実行してみます。

最低限必要な値を設定します。

パラメーターの値は JSON ファイルで定義してアップロードすると画面下に表示されます。

実行します。

タスクが実行されました。

失敗しました。CloudWatch Logs を確認してと表示されました。

CloudWatch Logs を確認しても原因がわかりません。後々手がかりになる要素とわかったのはlogMessageのステータスの変移です。

  1. CREATING_RUN
  2. STARTING_RUN
  3. RUNNING_WORKFLOW
  4. STOPPING_RUN
  5. RUN_FAIED
---------------------------------------------------------------------------------------------------------------------------------------
|   timestamp   |                                                       message                                                       |
|---------------|---------------------------------------------------------------------------------------------------------------------|
| 1677562182630 | {"runStatus":"PENDING","logMessage":"CREATING_RUN","message":"Creating your workflow run."}                         |
| 1677562183819 | {"runStatus":"STARTING","logMessage":"STARTING_RUN","message":"Provisioning infrastructure for your workflow run."} |
| 1677562805638 | {"runStatus":"RUNNING","logMessage":"RUNNING_WORKFLOW","message":"Your workflow is now running."}                   |
| 1677562821647 | {"runStatus":"STOPPING","logMessage":"STOPPING_RUN","message":"Stopping workflow run."}                             |
| 1677563125045 | {"runStatus":"FAILED","logMessage":"RUN_FAILED","message":"Workflow run failed."}                                   |
---------------------------------------------------------------------------------------------------------------------------------------

ワークショップ内の注意事項で ZIP ファイルの内部構成について指示があり原因の特定に繋がりました。成功したログは以下です。

---------------------------------------------------------------------------------------------------------------------------------------------------------------------
|   timestamp   |                                                                      message                                                                      |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| 1677568802875 | {"runStatus":"RUNNING","logMessage":"RUNNING_WORKFLOW","message":"Your workflow is now running."}                                                 |
| 1677568826790 | {"runStatus":"RUNNING","logMessage":"STARTING_TASK","message":"Starting workflow run task: arn:aws:omics:us-east-1:123456789012:task/1284192"}    |
| 1677568985254 | {"runStatus":"RUNNING","logMessage":"RUNNING_TASK","message":"Running workflow run task: arn:aws:omics:us-east-1:123456789012:task/1284192"}      |
| 1677569022153 | {"runStatus":"RUNNING","logMessage":"TASK_COMPLETED","message":"Workflow run task: arn:aws:omics:us-east-1:123456789012:task/1284192 completed."} |
| 1677569050328 | {"runStatus":"RUNNING","logMessage":"EXPORTING_FILES","message":"Exporting your workflow run output."}                                            |
| 1677569241713 | {"runStatus":"RUNNING","logMessage":"EXPORT_COMPLETED","message":"Completed export of workflow run output."}                                      |
| 1677569257998 | {"runStatus":"STOPPING","logMessage":"STOPPING_RUN","message":"Stopping workflow run."}                                                           |
| 1677569622171 | {"runStatus":"COMPLETED","logMessage":"RUN_COMPLETED","message":"Workflow run successfully completed."}                                           |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------

比較してみると、成功時はRUNNING_WORKFLOWのあとSTARTING_TASKへ遷移しています。失敗時はRUNNING_WORKFLOW"のあとにSTOPPING_RUNへ遷移しSTARTING_TASKのログは残らないことがわかりました。また、実行から約5分後でジョブが失敗しています。

念のため、AWS CLI から失敗したジョブの情報を確認しても原因を特定できる情報はありませんでした。

$ aws omics get-run --id 2121980
{
    "arn": "arn:aws:omics:us-east-1:123456789012:run/2121980",
    "creationTime": "2023-02-28T05:29:42.528250+00:00",
    "digest": "sha256:2173f96fe614c53320d3126307c914a20d71260faed20b149170fc913cb714f9",
    "id": "2121980",
    "name": "Greetings Run 2",
    "outputUri": "s3://omics-work/output/result",
    "parameters": {
        "addressee": "Amazon Omics",
        "greeting": "Hello"
    },
    "priority": 100,
    "roleArn": "arn:aws:iam::123456789012:role/service-role/OmicsWorkflowServiceRole",
    "startTime": "2023-02-28T05:40:05.330000+00:00",
    "startedBy": "arn:aws:sts::123456789012:assumed-role/cm-ohmura.yasutaka/cm-ohmura.yasutaka",
    "status": "FAILED",
    "stopTime": "2023-02-28T05:45:24.970178+00:00",
    "storageCapacity": 1200,
    "tags": {},
    "workflowId": "2151259",
    "workflowType": "PRIVATE"
}

まとめ

実行成功、失敗のワークフローの実行ログを比較結果からSTARTING_TASKのメッセージが CloudWatch Logs に残っていない場合は、ワークフロー定義ファイルの ZIP 圧縮時の内部ディレクトリ構成を誤っていないか確認してみてください。

おわりに

確認はできていませんが、ワークフロー作成時にオプショナルな項目でワークフロー定義のファイルをフルパスで指定すればもしかしたら回避できるのかもしれません。

理由としてはワークフロー定義ファイルを ZIP 圧縮時の内部ディレクトリ構成についてはユーザーガイドでは記載がありません。ただ、現状はドキュメント内容がかなり薄いのため、単純に書いていないだけの可能性もあります。

Using workflows - Amazon Omics

Amzon Omics のワークショップ内容から内部ディレクトリ構成について説明した記述を確認できます。

Amazon Omics - End to End

AWS

関連記事

[アップデート] Amazon Omics Storage のシーケンスストアへファイルを直接保存できるようになりました

大村 保貴

2023.05.21

Nextflow の概要と AWS サービスとの関係性を IT エンジニア向けに紹介

大村 保貴

2023.05.14

Amazon Omics Analytics の Variant Store へファイルの一括インポートができるようになりました

大村 保貴

2023.04.01

【書評】新しいゲノムの教科書 DNAから探る最新・生命科学入門

大村 保貴

2023.03.21