2.20. トラブルシューティング

このセクションでは、CWLの実行に問題がある場合にトラブルシューティングを行う方法を説明します。ここでは、cwltool に焦点を当てますが、いくつかのテクニックは他のCWL runnerでも使えるかもしれません。

2.20.1. cwltool をcachedir で実行する

ワークフロー実行時に--cachedir オプションを使用すると、cwltool に中間ファイル（入力ファイルでも出力ファイルでもないが、ワークフロー実行中に作成されるファイル）をキャッシュするよう指示できます。デフォルトでは、これらのファイルは一時ディレクトリに作成されますが、別のディレクトリに書き込むことでアクセスが容易になります。

次の例では、troubleshooting-wf1.cwl step_a とstep_b という2つのステップを用意しています。このワークフローは、echo "Hello World" | rev と同等で、"Hello World" というメッセージを反転して、すなわち "dlroW olleH" と表示します。しかし、2番目のステップであるstep_b,にはタイプミス があり、rev コマンドを実行する代わりにrevv を実行しようとし、失敗しています。

troubleshooting-wf1.cwl

cwlVersion: v1.2
class: Workflow

inputs:
  text:
    type: string
    default: 'Hello World'
outputs:
  reversed_message:
    type: string
    outputSource: step_b/reversed_message

steps:
  step_a:
    run:
      class: CommandLineTool
      stdout: stdout.txt
      inputs:
        text: string
      outputs:
        step_a_stdout:
          type: File
          outputBinding:
            glob: 'stdout.txt'
      arguments: ['echo', '-n', '$(inputs.text)']
    in:
      text: text
    out: [step_a_stdout]
  step_b:
    run:
      class: CommandLineTool
      stdout: stdout.txt
      inputs:
        step_a_stdout: File
      outputs:
        reversed_message:
          type: string
          outputBinding:
            glob: stdout.txt
            loadContents: true
            outputEval: $(self[0].contents)
      baseCommand: revv
      arguments: [ $(inputs.step_a_stdout) ]
    in:
      step_a_stdout:
        source: step_a/step_a_stdout
    out: [reversed_message]

--cachedir に /tmp/cachedir/ を指定して、このワークフローを実行してみましょう（cwltool は、ディレクトリがまだ存在しない場合、新規作成します）：

$ cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-language-user-guide-ja/envs/latest/bin/cwltool 3.1.20240508115724
INFO Resolved 'troubleshooting-wf1.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-language-user-guide-ja/checkouts/latest/src/_includes/cwl/troubleshooting/troubleshooting-wf1.cwl'
INFO [workflow ] start
INFO [workflow ] starting step step_a
INFO [step step_a] start
INFO [job step_a] Output of job will be cached in /tmp/cachedir/edb2bbda4f67d8bf15e1112f6a5a10cf
INFO [job step_a] /tmp/cachedir/edb2bbda4f67d8bf15e1112f6a5a10cf$ echo \
    -n \
    'Hello World' > /tmp/cachedir/edb2bbda4f67d8bf15e1112f6a5a10cf/stdout.txt
INFO [job step_a] completed success
INFO [step step_a] completed success
INFO [workflow ] starting step step_b
INFO [step step_b] start
INFO [job step_b] Output of job will be cached in /tmp/cachedir/609ea62e2a895d4dd4f7fd481ae06273
INFO [job step_b] /tmp/cachedir/609ea62e2a895d4dd4f7fd481ae06273$ revv \
    /tmp/lwiqpoii/stg7c73e32d-eb4f-4af6-9038-ee180821150f/stdout.txt > /tmp/cachedir/609ea62e2a895d4dd4f7fd481ae06273/stdout.txt
ERROR 'revv' not found: [Errno 2] No such file or directory: 'revv'
WARNING [job step_b] completed permanentFail
ERROR [step step_b] Output is missing expected field file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-language-user-guide-ja/checkouts/latest/src/_includes/cwl/troubleshooting/troubleshooting-wf1.cwl#step_b/reversed_message
WARNING [step step_b] completed permanentFail
INFO [workflow ] completed permanentFail
{
    "reversed_message": null
}WARNING Final process status is permanentFail

step_b が存在しない revv コマンドの実行に失敗したため、ワークフローは permanentFail ステータスになっています。step_a は正常に実行され、その出力は cachedir にキャッシュされました。作成された中間ファイルを確認できます：

$ tree /tmp/cachedir
/tmp/cachedir
├── 2p23qd1b
├── 609ea62e2a895d4dd4f7fd481ae06273
│   └── stdout.txt
├── 609ea62e2a895d4dd4f7fd481ae06273.status
├── edb2bbda4f67d8bf15e1112f6a5a10cf
│   └── stdout.txt
└── edb2bbda4f67d8bf15e1112f6a5a10cf.status

3 directories, 4 files

各ワークフローのステップには、一意のID（ハッシュのような長い値）が付与されています。${HASH}.status ファイルは、ワークフローによって実行された各ステップのステータスを表示します。そして、step_a 出力ファイルstdout.txt は、上記のコマンドの出力で確認できます。

step_b がrev を実行するように、タイプミスを修正します（すなわち、step_b のrevv をrev で置き換えます）。タイプミスを修正した後、前回と同じ引数でcwltool を実行すると、cwltool の出力に、step_a の出力が事前にキャッシュされていることと、step_b の出力の新しいキャッシュ・エントリーがあることがわかります。また、step_b のステータスは、今度は、成功であることに注目してください。

$ cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1-stepb-fixed.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-language-user-guide-ja/envs/latest/bin/cwltool 3.1.20240508115724
INFO Resolved 'troubleshooting-wf1-stepb-fixed.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-language-user-guide-ja/checkouts/latest/src/_includes/cwl/troubleshooting/troubleshooting-wf1-stepb-fixed.cwl'
INFO [workflow ] start
INFO [workflow ] starting step step_a
INFO [step step_a] start
INFO [job step_a] Using cached output in /tmp/cachedir/edb2bbda4f67d8bf15e1112f6a5a10cf
INFO [step step_a] completed success
INFO [workflow ] starting step step_b
INFO [step step_b] start
INFO [job step_b] Output of job will be cached in /tmp/cachedir/3dfb3e8c82b46e9e2d650a90a303a16a
INFO [job step_b] /tmp/cachedir/3dfb3e8c82b46e9e2d650a90a303a16a$ rev \
    /tmp/pzffyqpw/stg2364527d-368f-4b7f-bf0a-8e4c2cc3c47f/stdout.txt > /tmp/cachedir/3dfb3e8c82b46e9e2d650a90a303a16a/stdout.txt
INFO [job step_b] completed success
INFO [step step_b] completed success
INFO [workflow ] completed success
{
    "reversed_message": "dlroW olleH"
}INFO Final process status is success

この例では、ワークフローのステップstep_a はキャッシュされていたため再実行されず、その実行や出力に変化はありませんでした。さらに、cwltool は、実行したいコマンド名を修正した後、step_b を再実行する必要があることがわかりました。このテクニックは、CWL文書のトラブルシューティングに役立つだけでなく、cwltool が不必要にステップを再実行するのを防ぐ方法としても有効です。