ステータスとログ

ワークフローを投入したあとは、ステータスコマンドでワークフローとタスクの進捗を確認し、ログコマンドでタスクエージェントが何をしたかを確認します。これらを使って上の階層から順に原因を調べる方法と、ログの読み方は、投入、監視、ログを参照してください。

ステータスを確認する

ステータスコマンドには 3 つの階層があります。cdg status はプロジェクト全体のワークフローを一覧表示し、cdg dag status は 1 つのワークフローに含まれる各タスクを表示し、cdg task status は指定したタスクの詳しいステータスを表示します。

3 つのコマンドはいずれも、--watch を付けると表示を更新し続けます。ステータス表示を更新し続けるを参照してください。出力に現れるフェーズ、ステータス、サブステータス、レビュー結果がそれぞれ何を表すかは、状態の意味を参照してください。

cdg status

cdg status [--watch]

cdg status は引数を取らず、現在のプロジェクトにあるすべてのワークフローを、フェーズごとに 3 つのグループに分けて表示します。まだ投入していないもの、キューにあるもの、レビューが終了したものです。cdg dag ls と cdg dag list は同じコマンドの別の書き方で、動作はまったく同じです。

まだ投入していないワークフローのグループには、.codedag/dags/ とそのすべての階層のサブディレクトリにあるワークフローファイルが並びます。先にこのディレクトリの直下にあるファイルが、続いて各サブディレクトリのファイルが順に表示されます。投入済みのワークフローとレビューが終了したワークフローは残りの 2 つのグループに入り、このグループに重複して表示されることはありません。

cdg dag status

cdg dag status [ワークフロー] [--watch]

cdg dag status は、1 つのワークフローのフェーズとステータス、およびその各タスクのステータスを表示します。対象は、キューにあるワークフローに限りません。まだ投入していないワークフローを指定した場合は、そのタスクを一覧表示します。レビューが終了したワークフローを指定した場合は、ワークフローと各タスクのレビュー結果を表示します。cdg task ls と cdg task list は、task の下に置かれた別の書き方で、表示される内容は同じです。

ワークフローは、位置引数として書くことも、-w（または --workflow-file、--dag）で指定することもできますが、一度に指定できるのはどちらか一方だけです。位置引数と -w を参照してください。省略した場合はキューの先頭のワークフローが表示され、キューが空の場合、コマンドはエラーになります。

cdg task status

cdg task status <タスク ID...> [-w <ワークフロー>] [--watch]

cdg task status は、1 つのワークフローの中から指定したタスクのステータスを表示します。タスク ID は省略できません。1 つ、またはスペースで区切って複数書けます。書き方は 1 つまたは複数のタスクを指定するを参照してください。このコマンドではタスクセレクターを使えません。ワークフロー内のすべてのタスクを確認するには、cdg dag status を使います。ワークフローは -w で指定し、省略した場合はキューの先頭のワークフローになります。cdg dag status と同じく、まだ投入していないワークフローや、レビューが終了したワークフローも指定できます。

タスク ID を 1 つだけ書いた場合、コマンドはそのタスクの詳細を表示します。タスクが保留になっているときは、Reason: 行に理由が示されます。多くの場合、その次に Diagnostic: 行が続き、具体的な状況を補足します。開始前の準備に失敗して止まったタスク（workspace-dirty、branch-name-conflict などの理由）では、この行に失敗の原因が示され、エージェントセッションに問題が起きたタスクでは、エージェントの側で何が起きたかが示されます。さらに次の Docs: 行は、その理由に対応するトラブルシューティングのページへのリンクです。ID を複数書いた場合は、タスクごとにステータスが 1 行ずつ表示されるだけで、これらの行もコードの場所も表示されません。そのため、タスクが止まった理由を調べるときは、ID を 1 つだけ指定します。

cdg task status 2 -w feature

コードの場所

cdg task status が出力する単一タスクの詳細と、cdg dag status が冒頭の Workflow: の下に出力するワークフロー情報欄には、コードがあるワークスペース、ブランチ、ベースコミットが表示されます。位置は、ステータス、理由、診断の各行のあとです。レビューの前にタスクの変更内容を確認したいときや、手作業で修正するために該当のディレクトリへ移動したいときは、ここに表示される値を使います。たとえば、タスクのワークスペースとベースコミットがわかれば、git -C <ワークスペース> diff <ベースコミット> で、そのタスクのすべての変更を確認できます。

表示されるのは実行中に記録された値で、Git の現在の状態を読み取ったものではありません。まだ確定していない値は表示されず、その行自体が出力されません。

• 単一タスクの詳細： Workspace: はタスクが実際に実行されるワークスペースのディレクトリ、Branch: はそのタスクブランチです。どちらもタスクの起動が始まった時点で同時に確定し、一度も起動していないタスクにはどちらもありません。Base Commit: は、タスクの開始前にタスクブランチが指していたコミットです。このコミットからタスクブランチの現在の内容までの差分がタスクの変更であり、スナップショットの作成、変更の破棄、rework のいずれでも、タスクブランチはこのコミットまで巻き戻されます。この値は、タスクブランチの準備と上流の結果のマージがどちらも完了して初めて確定します。そのため、workspace-dirty や merge-conflict のように起動の段階で生じる理由で止まっているタスクには、最初の 2 行しかありません。
• ワークフロー情報欄： Integration Workspace: と Integration Branch: は、統合ワークスペースと統合ブランチです。Base Commit: はワークフロー全体のベースコミットで、すべてのタスクブランチがここから作られます。cdg dag review cancel または defer でワークフローを終了させた場合は、統合ブランチもこのコミットに戻ります。この 3 行は、ワークフローの起動が完了した時点でまとめて確定します。そのため、まだ投入していないワークフロー、キューで待っているワークフロー、起動した直後に dag-startup-failed や mirror-unavailable で止まったワークフローには、コードの場所が表示されません。
• 共有ワークスペースモード： タスクブランチは作られず、専用の統合ワークスペースもありません。単一タスクの詳細にもワークフロー情報欄にも Workspace: の 1 行しかなく、これがワークフロー全体の実行ディレクトリです。

ワークスペースが解放されたあとは、Workspace: または Integration Workspace: のパスの後ろに (released; used by this run) が付きます。これは、そのパスが今回の実行で使われた場所にすぎないことを表します。そのディレクトリは、その後に別のタスクやワークフローに割り当てられているかもしれず、チェックアウトされているのも別のブランチかもしれません。分離ブランチモードのタスクは、タスク自身が reviewed になった時点でワークスペースを解放します。共有ワークスペースモードのタスクは、属するワークフローと同じタイミングで解放します。ワークフロー自体は、どちらのモードでも reviewed になった時点で解放します。ブランチとベースコミットの 2 行はそのまま表示されるので、この 2 行をもとに、そのときの変更を引き続きたどれます。

cdg task review clear または cdg dag review clear でレビュー記録をクリアすると、タスクまたはワークフローは planning に戻り、コードの場所は表示されなくなります。

実行を進めるプロセスがないタスク

コンピューターの再起動、プロセスのクラッシュ、プロセスの強制終了のあとは、タスクの状態が working のままなのに、そのタスクを進めるプロセスがもう存在しない、ということが起こります。ステータスコマンドはこうしたタスクを見分け、復旧の方法を出力で案内します。ステータスコマンドは読み取り専用で、ステータスを確認しても実行が再び起動されることはありません。

• 単一タスクの詳細： サブステータスが working (stale owner) と表示されます。次の Diagnostic: 行にこのタスクを復旧するコマンドが示され、その次の行が Docs: のリンクです。
• タスクの一覧： cdg dag status と、ID を複数書いた cdg task status は、Submitted Tasks グループで、こうしたタスクのサブステータスの列を [working (stale owner)] と表示します。cdg dag status はさらに、ワークフロー情報欄に Diagnostic: 行を 1 行出力し、ワークフロー内の該当するタスクの ID をすべて挙げます。その次が Docs: のリンクです。cdg task status は、この行をすべてのグループのあとに出力します。挙げられるのは今回指定したタスクだけで、リンクは付きません。
• キュービュー： cdg status は、こうしたタスクを含むワークフローの行の下に Diagnostic: 行を 1 行追加します。内容はタスクの一覧の場合と同じで、ワークフローの行そのものは変わりません。

# 単一タスクの詳細に表示される診断行
Diagnostic: The persisted task worker is no longer running. Use 'cdg task recover 2 -w .codedag/dags/feature.yaml' to resume the original session.
# 一覧とキュービューに表示される診断行
Diagnostic: The persisted task workers for tasks 2, 3 are no longer running. Use 'cdg dag recover feature' to resume the original sessions.

一覧とキュービューが案内するのは、タスクを 1 つずつ復旧するコマンドではなく、cdg dag recover です。コンピューターが再起動すると、ワークフロー内で実行中だったタスクは通常すべて中断されるため、ワークフロー全体を一度復旧すれば足ります。このコマンドは、意図して一時停止または強制停止していたタスクも一緒に復旧します。対処の手順全体は、コンピューターの再起動またはプロセスのクラッシュのあとを参照してください。

レビューの結論がないタスク

cdg dag review cancel や defer のようなワークフローレベルのレビューでワークフローをそのまま終了させると、その中ですでに実行が始まっていてまだレビューされていないタスクには、ワークフローと同じ結論が付きます。まだ開始されていないタスクも、ワークフローと一緒に reviewed になりますが、タスク自身にはレビューの結論がありません。

• 単一タスクの詳細： Disposition: 行に unreviewed と表示され、アイコンは付きません。その後ろに、タスクがワークフローと一緒に reviewed になった時点の Status: と Substatus: が続きます。
• 複数タスクの一覧： これらのタスクは Unreviewed Tasks グループに入ります。各行の形式は Submitted Tasks と同じで、その時点のステータスとサブステータスが表示されます。グループは Submitted、Unreviewed、Reviewed、Planning の順に並び、空のグループは表示されません。

ステータス表示を更新し続ける

3 つのステータスコマンドには、いずれも --watch を付けられます。付けると、コマンドは 1 回表示して終了するのではなく、1 秒ごとに表示を更新し、次の表の条件が満たされた時点で自動的に終了します。途中でも、Ctrl+C でいつでも終了できます。

--watch が有効になるのは、まだ変化する可能性があるときだけです。cdg status では、キューにワークフローが 1 つ以上あることが条件です。cdg dag status では、対象のワークフローが投入済みで、レビューがまだ終了していないことが条件です。cdg task status では、対象のタスクのうち少なくとも 1 つが、投入済みでレビューがまだ終了していないことが条件です。条件を満たさない場合、コマンドはメッセージを 1 行出力し、現在のステータスを 1 回表示して終了します。

ワークフローを省略した場合、cdg dag status --watch と cdg task status --watch は、開始した時点でキューの先頭にあったワークフローを最後まで対象にし、次にキューの先頭に来たワークフローに切り替わることはありません。終了条件は、2 つのコマンドで異なります。cdg dag status --watch は、このワークフローのレビューが終了するまで待ちます。cdg task status --watch は、選んだタスクだけを見ます。それらのレビューがすべて終了した時点で更新を終え、ワークフローは待ちません。

対話型ターミナルでは、更新のたびに同じ位置の表示が書き換えられます。出力をファイルにリダイレクトした場合や、スクリプト、エージェントのシェルツールの中で実行した場合は、更新のたびにステータス全体がもう 1 回分、後ろに追加されていきます。また、コマンドは終了条件が満たされるまで終了しません。こうした場面では、--watch を付けないコマンドを必要なときに実行するほうが適しています。

cdg dag logs と cdg task logs

cdg dag logs は 1 つのワークフローに含まれるすべてのタスクのログを読み取り、cdg task logs はそのうち 1 つのタスクのログだけを読み取ります。オプションは、どちらのコマンドも同じです。

cdg dag logs [ワークフロー] [-f] [-n <行数>]
cdg task logs <タスク ID> [-w <ワークフロー>] [-f] [-n <行数>]

-w は、--workflow-file または --dag とも書けます。ワークフローの指定方法は、ワークフローを指定するを参照してください。どちらのコマンドも、プライマリリポジトリの .codedag/local/logs/ にあるログファイルを読み取ります。ファイルの場所と名前の付け方は、ログファイルの場所を参照してください。

どちらのコマンドも、ワークフローのパスをもとにログファイルを探します。キューにあるワークフロー、レビューが終了したワークフロー、まだ投入していないワークフローのどれでも、ワークフローファイルが残っていて検証に通るかぎり、ログを読み取れます。そのため、cdg dag review clear でレビュー記録をクリアしたあとも、再投入せずに、このワークフローの以前のログを引き続き読めます。まだ投入していないワークフローのログを読み取る場合、cdg dag logs の区切りの見出しと cdg task logs のタスク ID は、どちらもワークフローファイルの現在の内容をもとに決まります。ログにはあるものの、ファイルにはもうないタスクは、見出しが Task N と表示されます。

ログファイルは、ワークフローの最初のタスクの実行が始まった時点で初めて作成されます。ワークフローがまだキューで待っている間や、開始されたものの最初のタスクがまだ起動していない間は、読み取れるログがありません。

• -f を付けない場合： コマンドは、ログファイルがまだ作成されていないことを知らせ、-f を付けて待つためのコマンドを示します。終了コードは 0 です。
• -f を付けた場合： コマンドは、このワークフローのログを待っていることを知らせ、そのまま実行を続けます。ログファイルが作成されるとすぐに先頭から表示し、そのあともログを追い続けます。

$ cdg dag logs feature
No logs yet for .codedag/dags/feature.yaml. The log file is created when the workflow's first task starts.
→ Use 'cdg dag logs feature -f' to wait for log output

レビューが終了したワークフローや、まだ投入していないワークフローでは、これ以上ログは生成されません。こうしたワークフローにログファイルがない場合、コマンドは -f の有無にかかわらず No logs found for <ワークフローのパス>. と出力して終了します。終了コードは 0 です。

これらのメッセージはすべて stderr に出力され、stdout に出力されるのはログの行だけです。そのため、出力をファイルにリダイレクトすると、ファイルにはログだけが入ります。

cdg task logs のタスク ID は、ワークフローファイルの定義と照らし合わせて検証されます。ワークフローにそのタスクがない場合、コマンドは Task N not found in workflow: <ワークフローのパス> と出力し、終了コード 1 で終了します。タスクは存在するものの、ログの行がまだ 1 行も書き込まれていない場合、コマンドはエラーにならず、何も出力しません。

ログのオプション

2 つのログコマンドには、どちらにも -f と -n の 2 つのオプションがあります。-f は新しく書き込まれるログを追い続け、-n は末尾の指定した行数だけを表示します。どちらも付けない場合、コマンドは既存のログをログファイルの先頭からすべて表示して終了します。

-n が受け付ける値は 0 以上の整数だけです。abc、-1、1.5 のような値を指定すると、コマンドはエラーになり、ログを一切出力せずに終了コード 1 で終了します。

-n を付けない場合は、ログファイル全体が読み取られます。同じワークフローのログは、実行のたびにこのファイルに追記されるため、再投入したことのあるワークフローでは、以前の実行のログも一緒に表示されます。-f だけを付けて -n を付けない場合も、先にこれらのログをすべて表示してから、ログを追い始めます。最近の内容だけを見たいときは、-n を付けます。コマンドを起動したあとに追加された内容だけを見たいときは、-n 0 -f を使います。

cdg dag logs の表示形式は、オプションによって変わります。-f も -n も付けない場合、ログはタスクごとに区切られ、同じタスクの行がまとめて表示されます。-n を付けた場合は、ファイル全体の末尾から指定した行数が取り出され、タスクごとには区切られません。そのため、複数のタスクの行が混ざることがあります。-f を付けた場合は、各タスクの行が書き込まれた順に入り混じって表示されます。どの行もタスク ID と時刻で始まるので、入り混じっていても、どのタスクの行かを見分けられます。cdg task logs は 1 つのタスクの行だけを表示し、-n が数えるのもそのタスクの行だけです。

-f によるログの追跡がいつ終わるかは、個々のタスクではなく、ワークフロー全体で決まります。cdg task logs -f は、タスクの実行が終わって END: 行が書き込まれたあとも、そのタスクが属するワークフローのレビューが終了するまで待ち続けます。このタスクだけを見たい場合は、見終わったところで Ctrl+C で終了すれば済みます。ワークフローを省略した場合は、開始した時点でキューの先頭にあったワークフローのログを追います。ワークフローがすでにキューにない場合は、レビューが終了したものでも、まだ投入していないものでも、-f を付けたコマンドは既存のログを表示し終えた時点で終了します。

# ワークフロー feature のすべてのログを、タスクごとに区切って表示する
cdg dag logs feature
# ワークフロー全体の末尾 100 行を、タスクごとに区切らずに表示する
cdg dag logs feature -n 100
# まずタスク 2 の末尾 20 行を表示し、そのあと新しいログを追う
cdg task logs 2 -w feature -n 20 -f

関連ページ

• 投入、監視、ログ：3 つの階層のステータスを上から順に見て原因を調べる方法、ログの読み方、タスクが止まったままかどうかの見分け方。
• 状態の意味：フェーズ、ステータス、サブステータス、レビュー結果がそれぞれ何を表すか、表示されたときに待てばよいのか、対処が必要なのか。
• 制御と介入：介入が必要なときに使う、タスクの一時停止、強制停止、復旧と、タスクのセッションに入るコマンドの書き方。
• トラブルシューティング：タスクまたはワークフローが on-hold で止まったときの、理由ごとの対処方法。