目標

Digdagの公式サイトのドキュメントのConceptsの翻訳＋α
DigdagのRubyを使ってRailsにバッチを作るまでが最後の目標
http://docs.digdag.io/concepts.html

#＃目次
Getting started
Architecture
Concepts
Workflow definition
Scheduling workflow
Operators
Command reference
Language API -Ruby
Digdagで環境毎に設定値を変える（RubyOnRails）
Digdagを用いてRubyOnRails環境でバッチ実装

Projects and revisions

ワークフローはワークフローで使用される他のファイルと一緒にパッケージ化されます。
ファイルはSQLスクリプト、Python / Ruby / Shellスクリプト、構成ファイルなど何でもかまいません。
このワークフロー定義セットをプロジェクトと呼ばれます。

プロジェクトがDigdagサーバーにアップロードされるとDigdagサーバーは新しいバージョンを挿入し古いバージョンを保持します。プロジェクトのバージョンはリビジョンと呼ばれます。ワークフローを実行するとDigdagはデフォルトで最新のリビジョンを使用します。ただし、次の目的で古いリビジョンを使用することも可能です。

1. 過去のワークフロー実行の定義を確認する目的。
2. 以前のリビジョンを使用してワークフローを実行し以前と同じ結果を再現する目的
3. 最新バージョンで起きた問題を解決するため古いリビジョンに戻す目的

プロジェクトには複数のワークフローを含めることができます。ただし、新しいワークフローが他のワークフローに関連していない場合は、新しいプロジェクトを作成する必要があります。理由は、新しいリビジョンをアップロードすると、プロジェクト内のすべてのワークフローが一緒に更新されるためです。

Sessions and attempts

セッションは、正常に完了するはずのワークフローの実行計画です。Attemptとはセッションの実行を意味する。失敗したワークフローを再実行するとセッションは複数の試行を持つます。
セッションは実行計画、試行はその実行計画を実行するのを意味している。

セッションと試行を分離する理由は、実行が失敗する可能性があるためです。
セッションをリストアップすると、予想されるステータスはすべてのセッションが緑になることです。
失敗したセッションを見つけたらその試行をチェックしログから問題をデバッグします。
問題を修正するために新しいリビジョンをアップロードした後新しい試行を開始できます。
セッションでは、計画されたすべての実行が正常に行われたことを簡単に確認できます。

Scheduled execution and session_time

セッションにはsession_timeというタイムスタンプがあります。ワークフローの実行開始時間を意味します。

session_timeはワークフローの履歴で一意です。同じsession_timeで2つのセッションを送信すると後の要求は拒否されます。これにより以前に同時に実行されたセッションが誤って送信されるのを防ぎます。
ワークフローを同時に実行する必要がある場合は、新しいセッションを送信するのではなく過去のセッションを再試行する必要があります。

Task

セッションの試行が開始されると、ワークフローはタスクセットに変換されます。
タスクには相互に依存関係があります。Digdagは依存関係を理解しタスクを順番に実行します。

Export and store parameters

1. local: タスクに直接設定されるパラメーター
2. export: 親タスクからエクスポートされるパラメーター
3. store: 前のタスクで保存されたパラメーター

上記のパラメーターはタスクの実行時に1つのオブジェクトにマージされます。localパラメータが最も優先されます。
exportとstoreパラメーターはお互いを上書きするため、後のタスクで設定されたパラメーターの優先度が高くなります。

exportパラメーター は、親タスクが子に値を渡すために使用します。
storeパラメーター は、子を含む後続のすべてのタスクに値を渡すタスクで使います。

exportパラメータの影響はstoreパラメータに比べて制限されています。これにより、ワークフローをモジュール化できます。たとえば、ワークフローはいくつかのスクリプトを使用してデータを処理します。
スクリプトの動作を制御するために、スクリプトにいくつかのパラメーターを設定できます。一方、他のスクリプトをパラメータの影響を受けないようにする必要があります（たとえば、データ読み込み部分はデータ処理部分の変更の影響を受けてはなりません）。この場合、スクリプトを単一の親タスクの下に置き、親タスクにパラメーターをexportさせることができます。

storeパラメータは、以降のすべてのタスクで表示されます-storeパラメータは、前のタスクでは表示されません。たとえば、ワークフローを実行して再試行したとします。この場合、タスクによって保存されたパラメーターは、タスクが最後の実行で正常に終了した場合でも、以前のタスクからは見えません。

storeパラメータはグローバル変数ではありません。 2つのタスクが並行して実行される場合、それらは異なるstoreパラメータを使用します。これにより、実際の実行タイミングに関係なく、ワークフローの動作が一貫します。たとえば、2つの並列タスクに依存して別のタスクが実行された場合、最後のタスクによって保存されたパラメーターがタスクの送信順に使用されます。

Operators and plugins

オペレーターはタスクの実行者です。オペレーターは、ワークフロー定義でsh>、pg>などとして設定されます。
タスクが実行されると、Digdagは1つのオペレーターを選択し、すべてのパラメーター（local、export、およびstoreパラメーター）をマージしてマージされたパラメーターをオペレーターに渡します。

オペレーターは、一般的なワークロードのパッケージと見なすことができます。オペレーターを使用するとスクリプトより多くのことができます。

オペレーターはプラグインとして設計されています（ただし、まだ完全には実装されていません）。オペレーターをインストールしてワークフローを簡略化し、他のワークフローで再利用できるようにオペレーターを作成します。
Digdagは多くのオペレーターを実行するためのシンプルなプラットフォームです。

Dynamic task generation and _check/_error tasks

Digdagはワークフローを依存関係のある一連のタスクに変換します。このタスクのグラフは、DAG、Directed Acyclic Graph(有向非巡回グラフ)と呼ばれます。 DAGは、最も依存性の高いタスクから最後まで実行するのに適しています。

ただし、ループを表すことはできません。 IF分岐を表現するのも簡単ではありません。

しかし、ループと分岐は便利です。この問題を解決するために、Digdagは実行中のDAGにタスクを動的に追加します。
例）
Digdagはループを表す3つのタスクを生成します：+example^sub+loop-0、+example^sub+loop-1、+example^sub+loop-2（動的に生成されたタスクの名前は^subが追加される）：


+example:
  loop>: 3
  _do:
    echo>: this is ${i}th loop

実行結果

2020-07-10 20:48:11 +0900 [INFO] (0017@[0:default]+mydag+example): loop>: 3
2020-07-10 20:48:12 +0900 [INFO] (0017@[0:default]+mydag+example^sub+loop-0): echo>: this is 0th loop
this is 0th loop
2020-07-10 20:48:12 +0900 [INFO] (0017@[0:default]+mydag+example^sub+loop-1): echo>: this is 1th loop
this is 1th loop
2020-07-10 20:48:12 +0900 [INFO] (0017@[0:default]+mydag+example^sub+loop-2): echo>: this is 2th loop
this is 2th loop

_checkおよび_errorオプションは、動的タスク生成を使用します。これらのパラメーターは、タスクが成功または失敗した場合にのみ別のタスクを実行するためにDigdagによって使用されます。

_checkタスクは、タスクが正常に完了した後に生成されます。これは、次のタスクを開始する前にタスクの結果を検証する場合に特に役立ちます。

_errorタスクは、タスクの失敗後に生成されます。これは、タスクの失敗を外部システムに通知するのに役立ちます。

次の例は、後続のタスクの成功を出力します。またタスクの失敗に失敗したとメッセージを出力します。

+example:
  sh>: echo start
  _check:
    +succeed:
      echo>: success
  _error:
    +failed:
      echo>: fail

実行結果(success)

2020-07-10 21:05:33 +0900 [INFO] (0017@[0:default]+mydag+example): sh>: echo start
start
2020-07-10 21:05:33 +0900 [INFO] (0017@[0:default]+mydag+example^check+succeed): echo>: success
success

errorを発生させるためyour_script.shを削除

実行結果(error)

2020-07-10 20:56:49 +0900 [INFO] (0017@[0:default]+mydag+example^error+failed): echo>: fail
fail
2020-07-10 20:56:49 +0900 [INFO] (0017@[0:default]+mydag^failure-alert): type: notify
error:

Task naming and resuming

試行中のタスクには一意の名前があります。
試行を再試行するとこの名前は最後の試行でのタスクの照合に使用されます。

子タスクには、親タスクの名前がプレフィックスとして付いています。ワークフロー名もルートタスクとしてプレフィックスされます。次の例では、タスク名は+ my_workflow+load+from_mysql+tables、+my_workflow+load+from_postgres、および+my_workflow+dumpになります。

my_workflow.dig

+load:
  +from_mysql:
    +tables:
        sh>: echo tables
  +from_postgres:
    sh>: echo from_postgres
+dump:
   sh>: echo dump

結果

2020-07-10 21:12:12 +0900 [INFO] (0017@[0:default]+my_workflow+load+from_mysql+tables): sh>: echo tables
tables
2020-07-10 21:12:13 +0900 [INFO] (0017@[0:default]+my_workflow+load+from_postgres): sh>: echo from_postgres
from_postgres
2020-07-10 21:12:13 +0900 [INFO] (0017@[0:default]+my_workflow+dump): sh>: echo dump
dump

Workspace

ワークスペースは、タスクが実行されるディレクトリです。
Digdagは、プロジェクトアーカイブからこのディレクトリにファイルを抽出し、そこでディレクトリを変更して、タスクを実行します（注：ローカルモードの実行では、現在の作業ディレクトリがワークスペースであると想定されているため、ワークスペースを作成することはありません）。

プラグインは、ワークスペースの親ディレクトリへのアクセスを許可しません。これは、digdagサーバーが共有環境で実行されているためです。プロジェクトは外部環境に依存する必要がないように自己完結型である必要があります。スクリプトオペレーターは例外です（例：sh>オペレーター）。 docker：オプションを使用してスクリプトを実行することをお勧めします。