# 任意の付録：自作チェッカーの内部を読む

本編は [Uptime Kuma と Compose のラボ](README.md) です。この付録は、
すでに Python を使える方が自作チェッカーの仕組みを調べるための別実験です。
本編を完了するために実行する必要はありません。この付録では Compose の `demo` と同じポートを使います。
始める前に本編の `compose.yaml` があるフォルダーで、次のコマンドを実行します。

```powershell
docker compose --profile notifications stop
```

Ubuntu の Bash と Python 3.10 以上を使います。Python 標準ライブラリだけで動き、
追加パッケージ、Docker、認証情報、本番環境、外部ネットワークは不要です。
配布 ZIP を本編とは別のフォルダーに展開してください。以下の 5 ファイルは ZIP に同梱されています。

- `common.py`：共有処理。ほかのプログラムの実行にも必要
- `app.py`：監視対象のアプリ
- `labctl.py`：初期化、故障の注入・解除、証拠の確認
- `monitor.py`：回数を限定した監視
- `watchdog.py`：監視結果の鮮度の確認

`test_lab.py` は動作確認用の追加ファイルです。

## 起動

このディレクトリへ移動して実行します。

```sh
python3 labctl.py init
python3 app.py
```

アプリはフォアグラウンドで動かしたままにします。別のターミナルで実行します。

```sh
python3 monitor.py --path /health
python3 monitor.py --path /items/1 --expect-name monitoring-demo --max-ms 500
python3 labctl.py inspect
```

接続先は `127.0.0.1:18080` 固定です。ポートが使用中なら、自分で起動したラボの
アプリをそのターミナルで Ctrl+C により停止してください。不明なプロセスは停止しません。
`/health` は意図的に静的な応答を返します。`/items/1` はリクエストごとに SQLite を
読み取り専用で開き、実際に SELECT を実行して接続を閉じます。DB がない場合、
アプリが空の DB を勝手に作ることはありません。

SQLite は別プロセスの DB サーバーではありません。この実験で PostgreSQL のサービス停止やネットワーク障害を再現したとは言いません。

## 故障と復旧

各故障には解除コマンドがあります。`delay` は `/items/1` だけに作用します。

```sh
python3 labctl.py db-unavailable on
python3 labctl.py db-unavailable off
python3 labctl.py wrong-data on
python3 labctl.py wrong-data off
python3 labctl.py delay 0.8
python3 labctl.py delay 2
python3 labctl.py delay 0
```

- 学習用 DB ファイルの一時退避：`/health` は 200 のまま、`/items/1` は 503 になる。
- 不正なデータ：`/items/1` は 200 のままだが、`--expect-name monitoring-demo`
  が失敗する。この内容検証は、整数の `id: 1` と期待する `name` の両方を要求する。
- 0.8 秒の遅延：タイムアウトを 2 秒に設定すれば応答を受け取れるが、500 ms の
  応答時間の条件は満たさない。
- 2 秒の遅延：既定の 1 秒タイムアウトなら、`--max-ms` を指定しなくても失敗する。

応答時間の条件とタイムアウトは、次のように分けて確認できます。

```sh
python3 labctl.py delay 0.8
python3 monitor.py --path /items/1 --max-ms 500 --timeout 2
python3 labctl.py delay 2
python3 monitor.py --path /items/1 --timeout 1
python3 labctl.py delay 0
```

連続した失敗と復旧を確認する例です。

```sh
python3 monitor.py --path /items/1 --expect-name monitoring-demo --max-ms 500 --timeout 2 --count 30 --interval 2 --failures 3 --recoveries 2
```

この有限回の監視が動いている間に、3 つ目のターミナルで故障を注入・解除します。
毎回 `CHECK`、指定回数の連続失敗で一度だけ `ALERT`、その後の連続成功で
一度だけ `RECOVERY` を表示します。失敗が続いてもアラートは重複しません。
確認回数に達しない一時的な失敗の後には、復旧通知を出しません。

連続回数とアラート状態は、この実行のメモリ内だけで管理します。再起動すると
初期状態に戻ります。メールなどへの通知配信は行いません。

`--interval` は各チェックの**完了後**に待つ時間です。開始時刻を固定間隔にそろえる
機能ではありません。終了コードは、全チェック成功なら 0、一度でも失敗したら
その後復旧しても 1、設定・状態ファイルのエラーなら 2、Ctrl+C なら 130 です。
故障実験中の終了コード 1 は想定どおりです。

## 回数・サイズ・時間の上限

- `--count`：1～120 回、既定は 1 回
- `--interval`：0.1～60 秒、既定は 2 秒
- `--failures` / `--recoveries`：各 1～120 回、既定は各 1 回
- `--timeout`：0.1～5 秒、既定は 1 秒
- `--max-ms`：任意指定の 1～10000 ms。タイムアウトとは別の応答品質の条件
- `--path`：`/health` または `/items/1` のみ。ホスト・ポートは変更不可
- 1 チェックにつき 1 リクエスト。再試行、リダイレクト、プロキシ、DNS は不使用
- 本文は最大 4097 バイトまで読み、4096 バイトを超えたら失敗

監視の親プロセスが `subprocess.run(timeout=...)` で検査用の子プロセス全体を制限します。
読み取りごとのソケットタイムアウトだけに頼らないため、少量ずつ届く応答により
いつまでも待ち続けることを防ぎます。期限を超えた子プロセスは停止して回収します。

ただし、OS のプロセス生成・実行スケジューリング・停止には追加の時間がかかります。
指定秒数ぴったりで必ず戻るリアルタイム処理ではありません。
単調増加時計による `elapsed_ms` には、子プロセスの起動・待機と HTTP 処理が含まれます。
アプリだけの処理時間とは異なるため、アプリログの `duration_ms` と比較してください。
ログの突き合わせには UTC の時刻、所要時間の計測には単調増加時計を使います。

## 監視自体の確認

監視は、失敗も含めた**完了済みの各チェック**の後に `.state/last-check.json` を
書き出し、ファイルを原子的に置き換えます。途中で中断された検査では更新しません。
これは最後の観測結果であり、永続的なアラート状態や過去のメトリクスの保存ではありません。

```sh
python3 watchdog.py --max-age 5
```

新しく正しい形式の結果があれば、監視が最近まで検査を完了できていたと分かります。
`last_check_ok=false` でも、監視は動いています。アプリの正常性とは別の確認です。
未作成、古い結果、形式不正、未来の時刻は終了コード 1、新しい有効な結果は 0 です。
これは一度だけの確認です。監視を止めた後で再実行すると、結果が古くなる様子を確認できます。
`--max-age` は、検査のタイムアウト + 検査後の待機時間 + 実行の余裕より長く設定します。

両プログラムは `--state-file .state/another-check.json` にも対応しています。
実行元ディレクトリにかかわらず、このラボの `.state` 直下の単純な JSON ファイル名だけを
許可します。複数の監視には別々のファイルを使ってください。`delay.json` は予約済みです。
任意名の観測ファイルは `reset` では削除しません。

この watchdog は**同じホスト**で動き、時計・ディスク・電源・ネットワークの障害を
監視対象と共有します。ホスト全体が停止したことを独立して確認できず、
本番の外部監視の代わりにはなりません。時計の変更も鮮度判定に影響します。
外部通知、監視再起動後の状態保持、永続的な障害履歴、認証、TLS、本番用の防御は対象外です。

## 証拠の確認と後片付け

`python3 labctl.py inspect` は、既知の DB 行、故障設定、最後の観測結果、
直近最大 5 件のログを表示します。ログには UTC 時刻、パス、ステータス、所要時間、
関連する DB エラー名が含まれます。ヘッダー、クエリ文字列、任意のパスは記録しません。
クライアントがタイムアウトしてもアプリは停止しません。ログは実験中に増え、reset で消去します。

1. アプリと実行中の監視を、それぞれのターミナルで Ctrl+C により停止する。
2. `python3 labctl.py reset` を実行する。

reset/init は専用 DB を作り直し、既知の故障、既定の観測結果、ログを初期化します。
プロセスを停止する機能はありません。実行中にファイルを置き換えると競合するため、
アプリや監視が動いている間は reset/init を使わないでください。

無関係なファイルを残し、ディレクトリ全体・ワイルドカード・任意のパスを削除することは
ありません。状態ファイルのシンボリックリンク、通常ファイル以外、ハードリンクは拒否します。
これは信頼できるローカル環境での誤操作を防ぐための仕組みです。同時に別のプロセスが
ファイルを差し替えるような攻撃に対するセキュリティ境界ではありません。

## テスト

ポート 18080 を使うアプリを停止してから実行します。

```sh
python3 test_lab.py
```

リポジトリのルートから実行する場合はこちらです。

```sh
python3 docs/public/monitoring-intro/lab/test_lab.py
```

テストはプログラムを自身の一時ディレクトリへコピーし、同じループバックの固定ポートを
使います。自分で起動したプロセスだけを停止し、名前を明示したテスト専用ファイルだけを
後片付けします。利用者がダウンロードして使っているラボの状態は初期化しません。
