はじめに
Ansible のプレイブックの実行結果にめちゃくちゃシンプルなタイムスタンプを表示するだけのコールバックプラグイン community.general.timestamp をリリースしました。
簡単に使い方を紹介します。
概要
このプラグインは、プレイブックの実行結果の ヘッダ行（アスタリスクが並んでいる行）の 右端にタイムスタンプを表示 します。デフォルトでは時刻のみです。
最小限のシンプルなさりげない表示を目指した実装です。かわいいですね。もはやこれだけで充分なことも多いと思っています。
タイムゾーンの変更と、タイムスタンプのフォーマットの変更にも対応しています。下はタイムゾーンを UTC にして ISO 8601 拡張形式で日付も表示させた例です。
タイムゾーンやフォーマットの設定に関わらず、タイムスタンプは常にヘッダ行の右端に右寄せで表示 されます（ただし、見出しの文字列が長すぎる場合やウィンドウの幅が狭すぎる場合は、折り返されます）。
使い方と設定
実行結果にタイムスタンプを表示するには、コレクション community.general の 9.0.0 以降をインストールした状態で、ansible.cfg に以下の設定を追加するだけです。
[defaults]
stdout_callback = community.general.timestamp
または、環境変数 DEFAULT_STDOUT_CALLBACK で指定します。
export DEFAULT_STDOUT_CALLBACK="community.general.timestamp"
設定の変更
タイムゾーンやフォーマットを指定したい場合は、ansible.cfg にさらに以下の設定を追加します。設定値は例です。
[callback_timestamp]
timezone = Asia/Tokyo
format_string = %Y/%m/%d %H:%M:%S (%Z)
それぞれ、次の環境変数でも設定できます。
export ANSIBLE_CALLBACK_TIMESTAMP_TIMEZONE="Asia/Tokyo"
export ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING="%Y/%m/%d %H:%M:%S (%Z)"
タイムゾーンの指定
タイムゾーンは、ansible.cfg の callback_timestamp セクションの timezone、または環境変数 ANSIBLE_CALLBACK_TIMESTAMP_TIMEZONE で指定できます。
指定した値は Python の zoneinfo にそのまま渡されるので、Asia/Tokyo、America/Los_Angeles、UTC など、IANA Time Zone Database で定義された名前が利用できます（英語版 Wikipedia のページ のほうが人間にはやさしいです）。
timezone = Asia/Tokyo
timezone = America/Los_Angeles
timezone = UTC
デフォルトは 無指定 なので、デフォルトのタイムスタンプの中身は Naive な（タイムゾーンを持たない）時刻情報です。設定で明示的にタイムゾーンを指定すれば Aware な時刻になります。
フォーマットの指定
フォーマットは、ansible.cfg の callback_timestamp セクションの format_string、または環境変数 ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING で指定できます。
フォーマットの値は Python の datetime の strftime() にそのまま渡されるので、strftime() で使えるフォーマット文字列 が使えます。
format_string = %Y/%m/%d %H:%M:%S (%Z)
format_string = %Y-%m-%dT%H:%M:%S%z
format_string = %H:%M:%S.%f
デフォルトは %H:%M:%S です。
応用例
このプラグインは、デフォルトのコールバックプラグインである ansible.builtin.default を拡張する形で実装しています。したがって、ansible.builtin.default で使えるパラメータもそのまま機能します。
例えば、実行結果を JSON 形式から YAML 形式に切り替える設定とも組み合わせられます。
[defaults]
stdout_callback = community.general.timestamp
callback_result_format = yaml
[callback_timestamp]
timezone = UTC
format_string = %Y-%m-%dT%H:%M:%S%z
利用上の注意
残念ながら、AWX や Ansible Runner、Ansible Navigator など EE を使ってプレイブックを実行する場合 には、仕様上、（だいぶ強引にパッチをあてないかぎり）このプラグインは機能しません。。
EE でコールバックプラグインを変更するややこしさは 別のエントリ で過去に紹介しています。
参考情報
類似のプラグイン
プレイブックの実行結果にタイムスタンプを表示するプラグインとして、既成の ansible.posix.profile_tasks も知られています。ただし、これはタスクごとの実行時間の確認を主目的とするプラグインなので、実行結果に追加される情報が多く、タイムスタンプの確認だけを目的に使うのは少し大げさです。
$ ansible-playbook main.yml
PLAY [timestamp demo] ********************************************************************************************
TASK [timestamp demo] ********************************************************************************************
Tuesday 21 May 2024 23:47:12 +0900 (0:00:00.009) 0:00:00.009 ***********
ok: [localhost] =>
msg: Hello Ansible !!
TASK [timestamp demo] ********************************************************************************************
Tuesday 21 May 2024 23:47:12 +0900 (0:00:00.018) 0:00:00.027 ***********
Pausing for 5 seconds
(ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort)
ok: [localhost]
TASK [timestamp demo] ********************************************************************************************
Tuesday 21 May 2024 23:47:17 +0900 (0:00:05.020) 0:00:05.048 ***********
ok: [localhost] =>
msg: Hello Ansible !!
TASK [timestamp demo] ********************************************************************************************
Tuesday 21 May 2024 23:47:17 +0900 (0:00:00.016) 0:00:05.065 ***********
Pausing for 5 seconds
(ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort)
ok: [localhost]
PLAY RECAP *******************************************************************************************************
localhost : ok=4 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Tuesday 21 May 2024 23:47:22 +0900 (0:00:05.021) 0:00:10.087 ***********
===============================================================================
timestamp demo -------------------------------------------------------------------------------------------- 5.02s
timestamp demo -------------------------------------------------------------------------------------------- 5.02s
timestamp demo -------------------------------------------------------------------------------------------- 0.02s
timestamp demo -------------------------------------------------------------------------------------------- 0.02s
また、Ansible ではなく AWX では、ジョブテンプレートのログの画面で、ヘッダ行にタイムスタンプが表示される仕様です。この仕様をコールバックプラグインとして実装したのが今回のプラグインとも言えます。
本プラグインのしくみ
ヘッダ行は、CallbackModule クラスのインスタンス変数 _display の中身、Display クラスの banner() によって出力されています。
そこで本プラグインは、タイムスタンプを右端に表示するようにカスタマイズした banner() を新しく定義して、それをデフォルトのコールバックプラグインの _display の中の banner() と置き換えています。
参考リンク
- Ansible Community Documentation の
community.general.timestampのページ- まだ
latestに降ってきていないので、リンク先はdevelです
- まだ
- Ansible Galaxy の
community.general.timestampのページ community.general.timestampのソースコード- プルリクエスト
- 開発の動機のひとつになった Forum の投稿
おわりに
ふと思い立って作ったものですが、実装は強引なものの、見かけ上はシンプルでよいものができた感触です。
EE で動かせないのがかなしいですが、ゆくゆくはどうにかしたいところです。
