April 16, 2017

Digdag Slack プラグインを作成 & 公開しました #digdag

タイトルにある通り digdag-slack プラグインを公開してみましたので紹介します。
その名の通り、DigdagからSlack通知をするためのプラグインです。

特徴

  • このプラグインを利用すると、 slack>: オペレータが使えます
  • ymlでslackのpayloadを定義するので、柔軟な通知が実現します
    • attachments などを利用することで表現力豊かな通知が可能です
  • template内でdigdag側で定義した様々な変数が利用できます
    • メッセージを変数にしておいて利用時に定義することができるなど再利用性に優れています

リポジトリのREADME.mdにも記載していますのであわせて見ていただけると嬉しいです。

実際に利用してみる

では早速説明がてら、利用してみましょう。

digdag-slackのリポジトリにも成功時・失敗時の通知に利用できそうなsampleを作成しておいてあります。

[NOTE]
今回紹介するサンプルおよびリポジトリのサンプルを動かしたい場合は、digdagのバージョンをv0.9.9以上にして試してみてください。(task_nameを使わなければそれ以下でもOK)

1. Slackへ通知のためWebhook URLを取得

Incoming Webhooksはこちらから発行できます。Webhook URLは後ほど使うのでとっておいてください。

2. ワークフロー作成 (e.g. slack.dig)

今回は新たにプロジェクトを作成してみます。

# プロジェクトを作成
$ digdag init slack
2017-04-16 22:25:48 +0900: Digdag v0.9.9
  Creating slack/slack.dig
  Creating slack/.gitignore
Done. Type `cd slack` and then `digdag run slack.dig` to run the workflow. Enjoy!
# ディレクトリを移動
$ cd slack
# 現状の成果物を確認
$ ls
slack.dig

プロジェクト作成時にできた、slack.digをエディタで開いてまるっと消して下記のように編集してください。

_export:
  plugin:
    repositories:
      - https://jitpack.io
    dependencies:
      - com.github.szyn:digdag-slack:0.1.1
  webhook_url: https://hooks.slack.com/services/XXX/XXX/XXX
  workflow_name: slack
  ENV: develop

+step1-1:
  echo>: "Next will be success!"

+step1-2:
  slack>: good-template.yml

pluginの成果物は jitpack で公開しています。必ず指定してください。また先ほど、発行したWebhook URLは webhook_url として必ず指定してください。

slack> オペレータで指定するのは、templateのPATHおよびファイル名を指定するようにしてください。
上記の例では、ワークフローの定義ファイル(slack.dig)と同ディレクトリ内に good-template.ymlがあることになります。

3. 通知に利用するpayloadのテンプレート作成 (e.g. good-template.yml)

次に、slackへ送るpayloadのテンプレートをymlで作成します。
先の説明の通り、今回は同一ディレクトリにgood-template.ymlという名前でテンプレートを作成します。

---
username: Digdag
icon_emoji: ':blush:'
attachments:
- fallback: '[SUCCESS] ${workflow_name} workflow'
  color: "good"
  text: '*[SUCCESS]* `${workflow_name}` Workflow'
  mrkdwn_in:
  - text
  - pretext
  - fields
  fields:
  - title: Task Name
    value: "${task_name}"
    short: false
  - title: Session Date
    value: "${session_date}" # digdag build-in values
    short: true
  - title: Environment
    value: "${ENV}" # 環境変数も利用できます
    short: true

もっと凝りたい OR シンプルでいいという場合は、 Incoming Webhooksを参考にして作成してみてください。 ちなみに、jsonをymlに変換する便利サービス(JSON to YAML)もあるので、ある程度Message Builderで編集して作成したjsonを変換するのも良いでしょう。 ※ Message Builderを利用すると簡単にslackへのpayload作成を試せるのでオススメです。

またこの例では行っていませんが、 slack:> オペレータでのタスク実行時に適宜変数を渡してテンプレート側で利用することもできます。

4. 作成したワークフロー(slack.dig)を実行

さて、ここまでで作成できたら実際に実行してみましょう。

$ ls
good-template.yml slack.dig

$ digdag r -a slack.dig
2017-04-16 22:48:09 +0900: Digdag v0.9.9
2017-04-16 22:48:21 +0900 [WARN] (main): Reusing the last session time 2017-04-16T00:00:00+00:00.
2017-04-16 22:48:21 +0900 [INFO] (main): Using session /Users/shota/Workspace/digdag-sample/slack/.digdag/status/20170416T000000+0000.
2017-04-16 22:48:21 +0900 [INFO] (main): Starting a new session project id=1 workflow name=slack session_time=2017-04-16T00:00:00+00:00
2017-04-16 22:48:22 +0900 [INFO] ([email protected]+slack+step1-1): echo>: Next will be success!
Next will be success!
2017-04-16 22:48:22 +0900 [INFO] ([email protected]+slack+step1-2): slack>: good-template.yml
Success. Task state is saved at /Users/shota/Workspace/digdag-sample/slack/.digdag/status/20170416T000000+0000 directory.
  * Use --session <daily | hourly | "yyyy-MM-dd[ HH:mm:ss]"> to not reuse the last session time.
  * Use --rerun, --start +NAME, or --goal +NAME argument to rerun skipped tasks.

上記のテンプレートをそのまま利用された方は、以下のようにslackへの通知が来るはずです!
sample-good

ポイント

また、digdagのv0.9.9からタスク名が取得できるようになったので、それも取得できるようにテンプレートを作成してみました。
これでどのタスクが成功したか、わかりやすくなりますね。
失敗時にも同様に通知することでどのタスクが失敗したのか一目瞭然になります(๑•̀ㅂ•́)و✧

プラグインを使うメリット

例えば、SLA用・タスクのエラー発生時に通知を送るようにテンプレートを分けておくなどの運用が可能となるところです。

現状だと slackへの通知は digdag で標準搭載している http>: オペレータを利用した通知方法が一番有力で手軽かと思います。 ただし少し凝った通知を送るに長いpayloadを定義ファイル内に書くことになります。これは、冗長になりがちですし毎回書くのが大変だと感じました。そんな時にこの slack>: オペレータが活躍できると信じています(๑•̀ㅂ•́)و✧

最後に

手軽に利用できるので、ぜひ使っていただけたら嬉しいです! リポジトリはこちらです。

© szyn 2017