データ処理システムのパイプラインが、exit 0 で終わっているのに実は何も生成していない。こうしたサイレント障害に気づくまで、8〜16日かかっていました。この記事では、その代表的な2つの事例と、それを受けて作った「監視ハーネス」の設計を記録します。監視ハーネスは5つの監視モジュールと78のテストケースからなり、検知までの時間を1時間以内に縮めました。
事例1:16日間、監視機能が無効になっていた
2026年3月8日、Claude Code で実装した新機能を本番にデプロイしました。テストは92件すべて PASS、CI も通っていました。ところが3月24日にたまたまログを精査したところ、リソース監視のプログラムが16日間、すべての監視機能を止めていたことが分かりました。
原因は3層に重なっていた
1class ResourceMonitor:2 def __init__(self):3 api_key = os.getenv("API_KEY") # launchd 環境では None4 self.client = APIClient(api_key) # api_key=None でも初期化に成功する5
6 def fetch_resources(self):7 try:8 return self.client.get_resources()9 except Exception:10 return [] # 認証エラーも「リソースなし」として扱う- 環境変数がなかった: launchd(macOS の定時実行の仕組み)から起動されたプログラムは、
~/.zshrcなどのシェルプロファイルを読みません。plist のEnvironmentVariablesに設定するか、プログラム内でload_dotenv()を呼ばない限り、os.getenv("API_KEY")はNoneを返します。plist にはAPI_KEYの設定が漏れていました Noneでも初期化が成功した: API クライアントはapi_key=Noneでもエラーを出さず、API を呼ぶ時点で初めて認証に失敗する作りでした- 例外処理が障害を隠した: 認証エラーが
except Exceptionで捕まえられ、空のリストが返りました。呼び出し側は「監視対象がない」と判断して正常終了しました
どの検出手段もすり抜けた
| 検出手段 | 結果 |
|---|---|
| ユニットテスト | PASS(テストでは API_KEY をモックしていた) |
| CI | PASS(CI 環境には環境変数が設定されていた) |
launchctl list | ジョブは表示される(実行自体はされていた) |
| ログファイル | エラーなし(例外が捕まえられていた) |
| エラー通知 | なし(エラーのときだけ通知する作りだった) |
修正
1from dotenv import load_dotenv2load_dotenv(Path(os.getenv("PROJECT_ROOT", ".")) / ".env")3
4api_key = os.getenv("API_KEY")5if api_key is None:6 logger.error("API_KEY is not set. Monitoring will be disabled.")7 raise EnvironmentError("API_KEY is required")あわせて、CLAUDE.md に「launchd から起動されるスクリプトはシェルプロファイルを読まない。os.getenv() で読む値は plist の EnvironmentVariables か load_dotenv() でしか設定されない」というルールを足しました。この事故が、本番と同じ条件で Dry-Run する Pre 環境を作るきっかけにもなりました。その環境の設計は「本番・Pre・開発の3環境を1台のMacで1人で運用する」に書いています。
事例2:plist 30ファイルが壊れていたのに、ジョブは動いていた
同じ時期、Pre 環境の30個の plist を自動生成するスクリプトを Claude Code に書かせました。生成されたファイルは、plist(XML)ではなく JSON でした。
1# AIが書いたコード2def generate_plist(config: dict, output_path: str) -> None:3 with open(output_path, "w") as f:4 json.dump(config, f, indent=2) # JSON で出力していたそれでも、launchctl list には30ジョブすべてが表示されていました。launchd は、一度読み込んだジョブ定義を保持して実行し続けるためです。
1$ launchctl list | grep example2# → 30ジョブすべて表示される3
4$ plutil -lint ~/Library/LaunchAgents/com.example.pre.*.plist5# → 30ファイルすべて Invalid property listこのままでは、macOS を再起動してジョブが読み込み直されたときに、30ジョブがまとめて消えるところでした。生成には plistlib.dump() を使い、生成後に必ず plutil -lint で確かめるように直しました。
1import plistlib2import subprocess3
4def generate_plist(config: dict, output_path: str) -> None:5 with open(output_path, "wb") as f:6 plistlib.dump(config, f)7 result = subprocess.run(["plutil", "-lint", output_path], capture_output=True, text=True)8 if result.returncode != 0:9 raise ValueError(f"Invalid plist: {result.stderr}")AI にとって「設定ファイルを生成する」といえば JSON が最も一般的です。plist という macOS 固有の形式は、明示しないと選ばれません。CLAUDE.md に「plist の生成は plistlib.dump() のみ。json.dump() や手書きの文字列は禁止」と書きました。
AI が書くコードで起きやすい3つのパターン
2つの事例から、AI が書くコードでサイレント障害につながりやすいパターンを3つに整理しました。
1. 寛容すぎるコンストラクタ
1client = APIClient(api_key=None) # 危険: エラーにならない2client = APIClient(api_key=api_key) # 安全: api_key が None なら ValueError を出す作りにするAI は「柔軟な設計」を好み、None を許すコンストラクタを書きがちです。
2. 広すぎる例外の捕捉
1# 危険: すべてのエラーを飲み込む2try:3 result = api_call()4except Exception:5 result = default_value6
7# 安全: 想定するエラーだけを捕まえ、認証エラーなどは呼び出し元に伝える8try:9 result = api_call()10except ConnectionError:11 result = default_value3. 実行環境の違いを考えない
AI は「ターミナルから実行する」前提でコードを書きます。launchd、cron、Docker、systemd などの実行環境の制約は、CLAUDE.md で明示する必要があります。
他にもあったサイレント障害
| インシデント | 気づくまで | 表面上の動作 |
|---|---|---|
| 環境変数の未設定で、機能が静かに無効化(事例1) | 16日 | exit 0、ログも正常 |
| SSD が未マウントで、パイプライン全体が停止 | 8日 | launchd のジョブ自体は起動 |
| 上流パイプラインの出力が消失 | 9日 | 下流は「入力なし」で正常終了 |
| ログは更新されているが、処理件数0が連続 | 平日10日分 | exit 0、ログに完了メッセージあり |
共通しているのは、終了コードは0なのに、生成されるべきファイルや処理結果が存在しないことです。exit code を見ているだけでは、いつまでも気づけません。
設計方針:「生成物があるか」で判断する
監視の基本を、「プロセスが動いたか」から「期待する生成物があるか」に切り替えました。
1従来: launchd → スクリプト実行 → exit 0 → 正常と判断2今回: launchd → スクリプト実行 → 生成物チェック → 鮮度・件数・内容を検証この考え方は「exit code 0は正常ではない」でも詳しく書きました。監視ハーネスは、これを5つのモジュールに分けて実装したものです。
全体構成
1monitoring_harness.py(エントリーポイント)2 │3 ├─ infra_monitor (FR-5: インフラの前提条件)4 │ SSD マウント / symlink / DB 接続 / ディスク容量5 │6 ├─ pipeline_monitor (FR-1: 生成物の監視)7 │ ディレクトリの存在 / ファイル数 / 鮮度 / ログのパターン8 │9 ├─ business_monitor (FR-2: 業務メトリクス)10 │ 処理件数0の連続日数 / フォールバックの検知11 │12 ├─ causal_tracker (FR-3: 因果追跡)13 │ 上流の障害 → 下流のアラートを抑制14 │15 └─ alert_manager (FR-4: 通知の制御)1 collapsed line
16 新規通知 / 復旧通知 / エスカレーション / 状態の永続化FR-5:インフラの前提条件を最初に見る
パイプライン全体が依存する土台を最初に確かめます。SSD の未マウントや symlink 切れは CRITICAL として即座に通知し、その時点で以降のチェックを飛ばします。土台が崩れている状態で下流のエラーを数えても意味がないためです。
1infra:2 ssd_mount_path: "/Volumes/data_ssd"3 tmp_symlink: "_tmp"4 db_check_enabled: true5 disk_warn_gb: 5.0FR-1:パイプラインの生成物を見る
各パイプラインを YAML で定義し、生成物の存在・鮮度・件数を確かめます。
1pipelines:2 - name: pipeline_a3 chain:4 - name: fetchData5 output_dir: _tmp/fetch_to_calc6 pattern: "*.parquet"7 min_active: 0 # 下流がすぐ消費するため、空が正常8 max_age_hours: 49 weekday_only: true # 土日は閾値を +48h 緩める10 schedule: hourlyここで大事なのが Consumed Pipeline パターンです。下流のジョブが上流の出力をすぐに消費する場合、ディレクトリは空になります。これを障害と誤検知しないよう、処理済みの .bak ファイルの鮮度で判定します。
1処理待ちのファイルがある → 鮮度チェック → OK または ERROR2処理待ちのファイルがない → .bak ファイルを確認3 ├─ .bak が新しい → OK(正常に消費された)4 └─ .bak が古い、またはない → ERROR(パイプラインが止まっている)外部のデータソースによっては、土日に更新が止まります。weekday_only: true のステージは土日の閾値を48時間緩め、「金曜の夜に作られたファイルが日曜の朝に古い」と誤判定しないようにしています。
FR-2:業務メトリクスを見る
exit 0 でも、業務として異常な状態を拾います。
- 処理件数0の連続: ログから
processed=Nを取り出し、N=0 が3日続いたら WARNING - フォールバックの検知: ログにフォールバックの記録が出たら ERROR
FR-3:根本原因だけを通知する
上流のジョブが止まると、下流のジョブも連鎖してエラーになります。そのまま通知すると、1つの障害で3件のアラートが届きます。因果追跡モジュールは、パイプラインのチェーン定義を使って根本原因だけを通知し、下流のアラートを抑えます。
1fetchData: ERROR ← 根本原因として通知(影響範囲を付記)2calcMetrics: ERROR ← 抑制(上流 fetchData の障害による影響)3buildReport: ERROR ← 抑制通知を減らす考え方全体は「アラート疲労の定量分析と段階的治療」にまとめています。
FR-4:状態の変化だけを通知する
| 状態の変化 | 通知 | 理由 |
|---|---|---|
| 新規の障害 | する | すぐ対応するため |
| 続いている障害 | しない | 同じ通知の繰り返しを防ぐ |
| 復旧 | する | 対応が終わったことを確かめるため |
| エスカレーション(WARNING→ERROR) | する | 6時間放置された WARNING を格上げする |
アラートの状態は JSON ファイルに保存します。書き込みは一時ファイルに書いてから rename するアトミックな操作にして、途中でクラッシュしても壊れないようにしています。
1[監視ハーネス]2🚨 [CRITICAL] infra:ssd_mount: /Volumes/data_ssd 未マウント3❌ [ERROR] pipeline:pipeline_a:fetchData: 最新ファイルが28h前 (閾値: 4h)4✅ [復旧] pipeline:pipeline_b:fetchDataB: 正常に復旧5⬆️ [エスカレーション WARNING→ERROR] infra:disk_space: 6h超過実行モード
4つの launchd ジョブで、時間帯ごとに見る範囲を変えています。
| モード | 実行タイミング | 監視対象 |
|---|---|---|
hourly | 毎時 | インフラ + パイプラインA(毎時実行のステージのみ) |
post-a | パイプラインAの完了後 | インフラ + パイプラインAの全ステージ + 業務メトリクス |
post-b | パイプラインBの完了後 | インフラ + パイプラインB + 業務メトリクス |
post-c | パイプラインCの完了後 | インフラ + パイプラインC + 業務メトリクス |
「結果が出ているはずの時刻に、結果を確かめる」という単純な考え方です。
共通のデータ型と YAML 駆動の設定
すべてのモジュールは、同じ型の結果を返します。
1@dataclass(frozen=True)2class CheckResult:3 source: str # "pipeline:pipeline_a:fetchData"4 severity: Severity # OK / INFO / WARNING / ERROR / CRITICAL5 message: str # 人間が読むメッセージ6 pipeline: str = "" # 因果追跡用7 stage: str = "" # 因果追跡用frozen=True にして、チェック結果が後から書き換えられないようにしています。因果追跡で結果を差し替えるときも、新しいインスタンスを作ります。パイプラインの追加や閾値の変更は YAML の編集だけで済み、設定は起動時に frozen dataclass に変換されるので、設定ミスはその場でエラーになります。
シェルのヘルスチェックで踏んだ罠:set -e で全部止まった
監視ハーネスとは別に、launchd のジョブを確かめるシェルスクリプトも育ててきました。こちらでは、シェルの定石として冒頭に set -euo pipefail を書いたところ、正常な状態でもスクリプト全体が途中で終わるようになりました。
1set -euo pipefail2
3# launchctl list は、対象のラベルがないと exit 1 を返す4last_exit=$(launchctl list "$JOB_LABEL" | awk '/LastExitStatus/ {print $3}')「ラベルが見つからない」こと自体を検査したいのに、検査の前にスクリプトが落ちてしまいます。grep も、一致しないと exit 1 を返すので同じことが起きます。
1set -euo pipefail2
3# 検査対象のコマンドは || true で守り、結果は別に判定する4list_output=$(launchctl list "$JOB_LABEL" 2>/dev/null || true)5if [[ -z "$list_output" ]]; then6 echo "NG: $JOB_LABEL not loaded"7fi大事なのは、「検査対象が NG」と「スクリプト自体のバグ」を分けることです。
- スクリプトのバグ(コマンドの打ち間違い、未定義の変数)→ 非ゼロで止める(
set -e本来の用途) - 検査対象が NG → スクリプトは最後まで走り、NG の件数をメッセージで出す
混ぜると、「監視が止まっているのか、対象が NG なのか」を区別できなくなります。
同じ理由で、NG の件数を ((ng_count++)) で数える書き方にも注意が必要です。後置インクリメントは増やす前の値を返すので、ng_count が0のときの ((ng_count++)) は終了ステータス1になり、set -e の下ではそこでスクリプトが止まります。ng_count=$((ng_count + 1)) と書けば避けられます。
78テストの設計
テストは8カテゴリ、78ケースです。
| カテゴリ | テスト数 | 主な検証内容 |
|---|---|---|
| Types | 3 | frozen dataclass、デフォルト値 |
| Config Loader | 8 | YAML の解析、異常系(FileNotFound など) |
| Infra Monitor | 7 | SSD / symlink / DB / ディスク容量 |
| Pipeline Monitor | 18 | 正常 / 異常 / 境界値 / Consumed パターン / 土日の緩和 |
| Business Monitor | 7 | 処理件数の追跡、フォールバックの検知 |
| Causal Tracker | 7 | 上流の障害 → 下流の抑制、独立したパイプライン |
| Alert Manager | 15 | 状態の変化、永続化、エスカレーション |
| E2E + Incident | 13 | 全モードの結合テスト + 過去のインシデントの再現 |
特に重視したのが、過去のインシデントを再現するテストです。「SSD の未マウントが8日間放置された」「exit 0 なのにパイプラインが止まっていた」といった実際の事故の状況を再現し、ハーネスが検知できることを確かめています。
過去のインシデントをどう検知するか
| インシデント | 以前の検知まで | 監視ハーネスでの検知 |
|---|---|---|
| 環境変数の未設定で機能が無効化 | 16日 | インフラチェック |
| SSD の未マウント | 8日 | マウント状態の確認(CRITICAL) |
| ログが更新されない(symlink に書き込めない) | 8日 | ファイルの鮮度チェック |
| exit 0 だがパイプラインが停止 | 不明 | 生成物の件数確認 |
| ログは正常だが処理件数0が連続 | 平日10日分 | 業務メトリクスの監視 |
| 上流が停止し、下流は正常終了 | 9日 | 因果追跡 + 生成物の監視 |
| plist の破損 | 不明 | 毎朝の plutil -lint による構文検証 |
plist の破損を除き、いずれも検知までの時間が1時間以内になります。plist の構文は毎朝1回確かめています。
学んだこと
1. exit code は信用できない
exit 0 は「プロセスが異常終了しなかった」ことしか意味せず、「期待する処理が終わった」ことは意味しません。監視は「生成物があるか」で判断します。
2. 「エラーが出ない」は「正常」ではない
16日間気づけなかったのは、エラーが出なかったからです。ログの鮮度、出力の量、生成物の件数で、「動いていること」を積極的に確かめる必要があります。
3. launchctl list を信用しない
ジョブが「登録されている」ことと「正しく動いている」ことは別です。plist が壊れていてもジョブは動き続け、ログが空でもジョブは正常終了します。
4. Consumed Pipeline と因果追跡は、誤検知と通知の洪水を防ぐ
「ファイルがない=障害」と一律に判定すると誤検知が多発し、上流の障害で下流も全部通知すると、障害対応中にノイズが増えます。正常な状態の定義を工夫し、根本原因だけを通知することで、1回の障害を1通知に収めています。
まとめ
- サイレント障害は、複数の層の「寛容さ」が重なって起きる: 環境変数の欠落、
Noneを許すコンストラクタ、すべてを飲み込む例外処理が重なり、16日間気づけませんでした - 監視は「プロセスが動いたか」ではなく「生成物があるか」で判断する: パイプラインの期待する出力を YAML に定義し、実際の状態と突き合わせ、一致しなければ通知します
- 5モジュール78テストで、検知を8〜16日から1時間以内にした: インフラ・生成物・業務メトリクス・因果追跡・通知制御に分け、過去の事故を再現するテストで検知を確かめています
個人で運用するシステムでは、「誰も見ていない間に静かに壊れる」ことが最大のリスクです。それを構造的につぶす仕組みとして、同じ課題を持つ方の参考になれば幸いです。