--- name: log-capture description: 機器のシリアルコンソールに PC からつなぎ、必要ならログインして、決めたコマンドを機器のシェルで実行し、出力を記録する。機器でプログラムを動かして出力を見たいとき、機器のコンソールに出る文字を記録したいとき、シリアルの設定を確かめたいときに使う。/embedded-debug-loop:log-capture で、このスキルだけを呼び出して使える。 --- # log-capture：シリアルコンソールの記録 ## 何をするスキルか - PC から、機器のシリアルコンソールにつなぎます。 - 機器がログインを求めたら、設定のユーザー名でログインします。 - 設定したコマンドを、機器のシェルで順に実行し、出力を記録します。 - コマンドごとに、機器での終了コードも調べます。 - 機器から届いた文字は、ログのファイルに残します。 ## 設定ファイル - 場所は、作業フォルダの `.embedded-debug-loop/log-capture.yaml` です。 - 作業フォルダは、ふつうは今のフォルダです。 - ファイルがなければ、スクリプトがひな形から作ります。 - 各項目の意味は、項目のすぐ上のコメントに書いてあります。 - `.embedded-debug-loop` フォルダに `.gitignore` がなければ、作ります。 中身は `*` です。設定やログを git に入れないためです。 - 設定ファイルに、ひな形にある項目が足りないことがあります（スキルを新しくしたときなど）。 そのときは、足りない項目を、説明のコメントと一緒にファイルの最後に足します。 値はひな形のままです。ほかの所は変えません。 - この2つは、どのコマンドでもスクリプトがします。 ## 頼まれ方と、すること 下の `<このスキルのフォルダ>` は、このスキルを読み込んだときに示されるフォルダです。 コマンドは、作業フォルダで実行します。 ### 1. 「ログを取って」「機器で動かして出力を見せて」と頼まれたとき ``` python3 <このスキルのフォルダ>/scripts/capture.py run ``` - 設定の commands を、機器のシェルで上から順に実行します。 - 各コマンドの後に、終了コードを調べる短いコマンドを機器に送ります。 そのコマンドと返事は、`output` にもログにも残しません。 - ログでは、各コマンドの出力の後に「（終了コード：0）」の行を書きます。 読めなかったときは「（終了コード：読めませんでした）」です。 - 今回だけ別のコマンドを実行するときは、`--command` を付けます。 何回でも書けます。例：`run --command "/opt/myapp/my_app"` - コマンドを実行せず、出力を記録するだけのときは、`--listen-only 秒数` を付けます。 例：`run --listen-only 30` - 作業フォルダが今のフォルダと違うときは、`--workdir フォルダ` を付けます。 - 設定ファイルを別の場所に置くときは、`--config ファイル` を付けます。 - 時間がかかることがあります。途中で止めずに、終わるまで待ってください。 最長の目安は「コマンドの数 ×（command_timeout_seconds ＋ 10 秒）＋ listen_seconds ＋ 1 分」です。 ### 2. 設定ファイルの場所を聞かれたとき、用意するよう頼まれたとき ``` python3 <このスキルのフォルダ>/scripts/capture.py config-path ``` - 設定ファイルがなければ、ひな形から作ります。 - 結果の `config` がファイルの場所、`missing` がまだ空の必須の項目です。 - ファイルを作れなかったときや読めないときは、`problems` に理由があります。 ### 3. 設定を確かめるよう頼まれたとき ``` python3 <このスキルのフォルダ>/scripts/capture.py check ``` - 設定の書き方を確かめます。 - シリアルポートを開いて Enter を送り、機器が答えるかを見ます。 - ログインが要るときは、ログインできるかも確かめ、すぐにログアウトします。 - 機器のシェルでコマンドは実行しません。 ## 結果の伝え方 スクリプトは、標準出力に JSON を1つ出します。 うまくいったかは `ok` で、設定の問題があるかは `problems` で見分けます。 利用者には、次のように伝えます。 - `message` を、そのまま伝えます。 - ログのファイルの場所（`log`）を伝えます。 - `added` に項目があれば、設定ファイルに新しい項目を足したことを伝えます。 `message` にも書いてあります。値はひな形のままなので、書き換えてよいと伝えます。 - JSON の項目名（`ok`、`exit_code`、`timed_out`、`not_run` など）は、利用者に見せません。 ふつうの言葉で言い換えます（例：「終了コード N」「時間切れ」「実行しなかったコマンド」）。 - 設定ファイルの項目名（commands、listen_seconds など）は、見せてかまいません。 利用者が自分で書き換えるものだからです。 - 結果にない原因を、事実として書きません。 原因の見込みを書くときは、「〜かもしれません」のように、推測だと分かるように書きます。 前のやり取りで見たことも、この結果で確かめていなければ、推測として書きます。 - run のとき - コマンドごとに、`command` と `output` を見せます。 - `exit_code` は、機器でそのコマンドが終わったときの終了コードです。 0 なら、ふつうに終わっています。 - `exit_code` が 0 以外の数なら、そのことを必ず伝えます。 `ok` が true でも、機器のコマンドはうまく動いていないことがあります。 「終了コード N で終わった」ことと、`output` の最後の行を伝えます。 `message` にも、同じことが書いてあります。 - `exit_code` が null なら、機器での終わり方は分かりません（時間切れのときなど）。 - 利用者には「終了コード N」とだけ書き、`exit_code` という項目名は見せません。 - `timed_out` が true なら、時間内に終わらず Ctrl-C で止めたと伝えます。 それまでの出力は記録されていて、判断に使えます。終わらないプログラムを見るときは、command_timeout_seconds を見たい長さの秒数にします。 - `truncated` が true なら、`output` は最後の 60 行だけです。全部はログにあります。 - `listen` があれば、記録した出力（`listen` の `output`）を見せます。 - `not_run` があれば、実行しなかったコマンドを伝えます。 - check のとき - つながったかどうかと、`problems` の各文を伝えます。 - 設定の要点（`summary`）を、表にして見せます。 - 設定に問題があるとき（`problems` があるとき） - `problems` の各文を、そのまま伝えます。 - 設定ファイルの場所（`config`）を伝えます。 - 設定ファイルは、利用者が直接直してよいと伝えます。 - 各項目の意味は、項目のすぐ上のコメントにあると伝えます。 ## 守ること - 頼まれない限り、設定ファイルを書き換えません。 ただし、足りない項目は、スクリプトが自分で足します。 - つながらなかったときに、むやみにやり直しません。 やり直さずに、原因を伝えて終えます。どうするかは、頼んだ側か利用者が決めます。 - パスワードを、画面やチャットに出しません。 設定の要点を見せるとき、パスワードは、空なら「（空）」、空でなければ「＊＊＊」と書きます。 - このスクリプト自身の終了コードは、利用者に伝えません。機器のコマンドの終了コードとは別です。