Literate Computing for Reproducible Infrastrucre is our project, which seeks to utilize Jupyter Notebook in operational engineering area for seeking ..
計算機インフラの御守では種々雑多なドキュメンテーションが不可欠です。日々の作業で証跡を残す、手順を整理して共有・再利用する、ユーザマニュアルや教材を整備する.. 国立情報学研究所（NII）のクラウド運用担当では、これらをシームレスに記述・蓄積する方法を研究しています。
表題の Literate Computing for Reproducible Infrastructure は、そのような取り組みのプロジェクト名です。プロジェクトでは Jupyter Notebook を用いてドキュメンテーションを行うことで、運用作業の信頼性向上、手順やノウハウの蓄積・流通が容易になることを目指しています。
インフラ運用の場面において 機械的に再現できる、人が読み解ける手順 を手段として、過度に自動化に依存することのない、レジリエントな 人間中心の機械化 をめざしています。そこでは、作業を効率化しつつもブラックボックス化せず、作業に対する理解をチーム内でコミュニケーションできる、また、目的と手段の整合性や限界を理解し議論・評価できると言った場を維持することで、ノウハウの移転・共有を促し運用者のスキル向上とエンジニアリングチームの再生産をはかる ことを重視しています。
多くの現場では、管理サーバにログインしコンソール上で作業を行う、作業内容や証跡はWiki等に随時転記して共有する.. といった形態が一般的と思います。これに対しLC4RIでは運用管理サーバ上にNotebookサーバを配備し、作業単位毎にNotebookを作成、作業内容やメモを記述しながら随時実行するといった作業形態を推奨しています。作業の証跡を齟齬なく記録する仕組み、過去の作業記録を参照して機械的に再現あるいは流用できる仕組み、機械的に実行できるとともに人が読み解き補完することもできるNotebook手順を整備しています。
プロジェクトの成果物は GitHub NII Cloud Operation Teamで公開しています。 Hadoop や Elastic Search など学術機関でポピュラーなインフラにに関する構築や 運用の手順を整理したもの、また、構築や運用の手順を記述するために便利な Jupyterの機能拡張 を掲載しています。
This notebook demonstrates our project's extensions for Literate Computing for Reproducible Infrastructure.
この Notebook では拡張した機能の概要を紹介します。
(2019.06.20)
Usage:
Freeze: Preventing miss-operation; once a code cell has been executed, it freezes against unintended execution and modification. Note that the freeze is implemented as different state from standard cell lock's. The freeze only make an executed cell un-editable temporally.
//誤操作を防ぐ; いったんセルを実行すると"凍結"され解凍しないと再実行できない。また、セルの編集をロックすることもできる。
Bricks: Giving a summarized perspective for execution control; embedded "cells" underneath are represented as bricks and be able to run through altogether with a click, while markdowns and codes are collapsed using Collapsible Headings
//まとめ実行; マークダウンを畳み込んだ際に、畳み込まれた範囲にあるすべての"Cell"を一連の"brick"として表示する。一連の"brick"を1-clickでまとめて実行できる。
Run_through: Execute collapsed code cells as a whole; Simply reuse workflows without paying much attention to details, whithout needs for arrenge nor customization. Run throughout the notebook as an executable checklist, then verify error if it occurs.
//定型的な作業をまとめて実行する; 詳細は気にせずNotebook形式の手順を気軽に利用, アレンジやカスタマイズはあまり必要がない。まとめて実行してエラーが発生した時だけ詳細を確認したい; 実行可能なチェックリストとして用いる。
GitHub: Jupyter-LC_run_through
How-to: run_through
The on the collapsed headding indicates there are collapsed markdowns and cells. With clicking and switch the expand/collapse.
まとめ実行機能
表題の左側にある は、詳細な手順が畳み込まれていることを示しています。 をクリックすると、 に変化し、畳み込まれている内容を表示することができます。この畳み込み表示機能は "Collapsible Headings"を利用しています。オリジナルの Collapsible Headings ではマークダウンの階層を畳み込むだけだったのですが、、
実行が正常に終わったセルは凍結 されます。凍結状態のセルはそのままでは実行することも、修正することもできません。凍結状態を解除するにはツールからをクリックします。
凍結機能は、実行済みの範囲を識別するとともに、偶発的な重複実行を防止するためのものです。また、まとめ実行ボタンは一定期間、チャタリングを防止するように制御しています。
エラーのセルは内容を修正して再実行することができます。実行が終わって凍結状態 のセルはスキップされるので、エラーを修正した後、まとめ実行ボタンを再度押すことで作業を継続できます。修正したセル（未実行）と継続する未実行のセルが実行されます。
エラーの原因が当該のセル単体ではなく、遡ったセルの実行結果に依存している場合は、必要な範囲まで凍結を解除することになります。まとめて凍結を解除するには、ツールから、を利用することができます。
Run_through: Try “”, which will collapse cells, then, “” will run through four bricks.
: The light green bricks indicate successfull completion.
: The third light coral brick indicates some error.
: The snow flake indicates those bricks are frozen. Executions and edits are prohibitted. The “” will unfrozen bricks.
The succeeded cells will be automatically frozen in order to prevent accidental duplicate operations. Error cells
remain unfrozen, then you can fix errors and re-execute the cell. You can continue execution on following not-yet-executed cells .
畳み込んだステップのまとめ実行: 表題の横に が表示されている場合はクリックしてセルを畳み込んでください。畳み込まれた状態では に変化します。
この例では をクリックすると４ステップをまとめ実行します。実行が終わったステップは薄緑の表示となります。以下では３番目がエラーとなり薄紅表示され、実行が中断します。
をクリックしてエラーの内容を確認します。
エラーのセルを修正すると、続きから実行することができます。
凍結状態のセルは実行することも、修正することもできません。再度実行する場合にはウインドウ上部のをクリックすることで凍結を解除します。
In [ ]:
! echo "This is 1st step" > foo; cat foo
In [ ]:
! echo ".. 2nd step..." >> foo && cat foo
In [ ]:
!echooooo ".. 3rd step... will fail" >> foo && cat foo
"echo" に修正して実行してみましょう。
In [ ]:
! cat foo
Usage:
You can review whole output and compare with previous results from different executions.
When you install some pakages, there would be massive log lines. Jupyter Web UI is inefficient for handling a large number of output lines.
例えば、某かのパッケージ群をインストールしたりすると大量のログが出力されますが、JupyetrのWeb UI上で大量の出力を扱うのはなにかと不便です。 Jupyterの Cell の中でログの内容を検索したり、比較したりするのはまどろっこしく手間がかかります。
Jupyter-LC_wrapper を用いると:
・ Output Cell には要約されてた結果が出力されるようになります（例：最初10行と最後の10行）。
・ オリジナルの出力結果全体はファイルに保存されます。
・ 実行毎に各々のファイルに結果が保存されるので出力結果を比較することができます。
・ 要約中でも、エラーなど特定のパターン含む行を表示します（lc_wrapper_regex.txt などいくつかの方法でカスタマイズ可）。
Cellでコマンドを実行する際に先頭に "!!" を付加すると、LC_wrapper の機能が有効になります。 Cellで shell を呼び出す場合は "!!!" を付加してください。
In [ ]:
%env lc_wrapper 8:8:10:10
# lc_wrapper s:h:e:f
#
# s : Summary starts when # of output lines exceed 's' (default s=1)
# h : Summary displays the first h lines and max 2 x h error lines.
# e : Max # of output lines in progress.
# f : Summary displays the last f lines (default f=1)
In [ ]:
!!from time import sleep
with open("./resources/bootstrap.log", "r") as f: # "/var/log/bootstrap.log"
count = 0
limit = 100
for line in f:
count = count+1
if count > limit: break
print(line, end=''),
sleep(0.05)
print ("after", limit, "lines are ignored")
#
# Emulate large log output..
In [9]:
import pandas
import matplotlib
import matplotlib.pyplot as plt
import random
In [10]:
%matplotlib inline
In [15]:
plot_df = pandas.DataFrame({
'col1': [12, 3, random.randint(1,10), 4],
'col2': [3, 12, 5, 2],
'col3': [random.randint(4,7), 10, 3, random.randint(0,2)],
'col4': [random.randint(0,11), 5, random.randint(6,12), random.randint(0,5)],
})
plot_df
plot_df.plot()
Out[15]:
上の例では、タブをクリックすると以前の出力結果を参照することができます。
In [16]:
plot_df
Out[16]:
以前の出力結果を選択表示すると が に変わります。この をクリックすると、選択している出力と現在の出力を比較することができます。
In [ ]:
plot_df.transpose