45395 - シコウサクゴ -

サイレント障害を1時間以内に検知する監視ハーネス:16日間気づけなかった機能停止とplist30ファイル破損から、5モジュール78テストの設計へ

データ処理システムのパイプラインが、exit 0 で終わっているのに実は何も生成していない。こうしたサイレント障害に気づくまで、8〜16日かかっていました。この記事では、その代表的な2つの事例と、それを受けて作った「監視ハーネス」の設計を記録します。監視ハーネスは5つの監視モジュールと78のテストケースからなり、検知までの時間を1時間以内に縮めました。


事例1:16日間、監視機能が無効になっていた

2026年3月8日、Claude Code で実装した新機能を本番にデプロイしました。テストは92件すべて PASS、CI も通っていました。ところが3月24日にたまたまログを精査したところ、リソース監視のプログラムが16日間、すべての監視機能を止めていたことが分かりました。

原因は3層に重なっていた

1
class ResourceMonitor:
2
def __init__(self):
3
api_key = os.getenv("API_KEY") # launchd 環境では None
4
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 [] # 認証エラーも「リソースなし」として扱う
  1. 環境変数がなかった: launchd(macOS の定時実行の仕組み)から起動されたプログラムは、~/.zshrc などのシェルプロファイルを読みません。plist の EnvironmentVariables に設定するか、プログラム内で load_dotenv() を呼ばない限り、os.getenv("API_KEY") は None を返します。plist には API_KEY の設定が漏れていました
  2. None でも初期化が成功した: API クライアントは api_key=None でもエラーを出さず、API を呼ぶ時点で初めて認証に失敗する作りでした
  3. 例外処理が障害を隠した: 認証エラーが except Exception で捕まえられ、空のリストが返りました。呼び出し側は「監視対象がない」と判断して正常終了しました

どの検出手段もすり抜けた

検出手段結果
ユニットテストPASS(テストでは API_KEY をモックしていた)
CIPASS(CI 環境には環境変数が設定されていた)
launchctl listジョブは表示される(実行自体はされていた)
ログファイルエラーなし(例外が捕まえられていた)
エラー通知なし(エラーのときだけ通知する作りだった)

修正

1
from dotenv import load_dotenv
2
load_dotenv(Path(os.getenv("PROJECT_ROOT", ".")) / ".env")
3
4
api_key = os.getenv("API_KEY")
5
if 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が書いたコード
2
def 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 は、一度読み込んだジョブ定義を保持して実行し続けるためです。

Terminal window
1
$ launchctl list | grep example
2
# → 30ジョブすべて表示される
3
4
$ plutil -lint ~/Library/LaunchAgents/com.example.pre.*.plist
5
# → 30ファイルすべて Invalid property list

このままでは、macOS を再起動してジョブが読み込み直されたときに、30ジョブがまとめて消えるところでした。生成には plistlib.dump() を使い、生成後に必ず plutil -lint で確かめるように直しました。

1
import plistlib
2
import subprocess
3
4
def 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. 寛容すぎるコンストラクタ

1
client = APIClient(api_key=None) # 危険: エラーにならない
2
client = APIClient(api_key=api_key) # 安全: api_key が None なら ValueError を出す作りにする

AI は「柔軟な設計」を好み、None を許すコンストラクタを書きがちです。

2. 広すぎる例外の捕捉

1
# 危険: すべてのエラーを飲み込む
2
try:
3
result = api_call()
4
except Exception:
5
result = default_value
6
7
# 安全: 想定するエラーだけを捕まえ、認証エラーなどは呼び出し元に伝える
8
try:
9
result = api_call()
10
except ConnectionError:
11
result = default_value

3. 実行環境の違いを考えない

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つのモジュールに分けて実装したものです。

全体構成

1
monitoring_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 として即座に通知し、その時点で以降のチェックを飛ばします。土台が崩れている状態で下流のエラーを数えても意味がないためです。

1
infra:
2
ssd_mount_path: "/Volumes/data_ssd"
3
tmp_symlink: "_tmp"
4
db_check_enabled: true
5
disk_warn_gb: 5.0

FR-1:パイプラインの生成物を見る

各パイプラインを YAML で定義し、生成物の存在・鮮度・件数を確かめます。

1
pipelines:
2
- name: pipeline_a
3
chain:
4
- name: fetchData
5
output_dir: _tmp/fetch_to_calc
6
pattern: "*.parquet"
7
min_active: 0 # 下流がすぐ消費するため、空が正常
8
max_age_hours: 4
9
weekday_only: true # 土日は閾値を +48h 緩める
10
schedule: hourly

ここで大事なのが Consumed Pipeline パターンです。下流のジョブが上流の出力をすぐに消費する場合、ディレクトリは空になります。これを障害と誤検知しないよう、処理済みの .bak ファイルの鮮度で判定します。

1
処理待ちのファイルがある → 鮮度チェック → OK または ERROR
2
処理待ちのファイルがない → .bak ファイルを確認
3
├─ .bak が新しい → OK(正常に消費された)
4
└─ .bak が古い、またはない → ERROR(パイプラインが止まっている)

外部のデータソースによっては、土日に更新が止まります。weekday_only: true のステージは土日の閾値を48時間緩め、「金曜の夜に作られたファイルが日曜の朝に古い」と誤判定しないようにしています。

FR-2:業務メトリクスを見る

exit 0 でも、業務として異常な状態を拾います。

  1. 処理件数0の連続: ログから processed=N を取り出し、N=0 が3日続いたら WARNING
  2. フォールバックの検知: ログにフォールバックの記録が出たら ERROR

FR-3:根本原因だけを通知する

上流のジョブが止まると、下流のジョブも連鎖してエラーになります。そのまま通知すると、1つの障害で3件のアラートが届きます。因果追跡モジュールは、パイプラインのチェーン定義を使って根本原因だけを通知し、下流のアラートを抑えます。

1
fetchData: ERROR ← 根本原因として通知(影響範囲を付記)
2
calcMetrics: ERROR ← 抑制(上流 fetchData の障害による影響)
3
buildReport: 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)
2
class CheckResult:
3
source: str # "pipeline:pipeline_a:fetchData"
4
severity: Severity # OK / INFO / WARNING / ERROR / CRITICAL
5
message: str # 人間が読むメッセージ
6
pipeline: str = "" # 因果追跡用
7
stage: str = "" # 因果追跡用

frozen=True にして、チェック結果が後から書き換えられないようにしています。因果追跡で結果を差し替えるときも、新しいインスタンスを作ります。パイプラインの追加や閾値の変更は YAML の編集だけで済み、設定は起動時に frozen dataclass に変換されるので、設定ミスはその場でエラーになります。


シェルのヘルスチェックで踏んだ罠:set -e で全部止まった

監視ハーネスとは別に、launchd のジョブを確かめるシェルスクリプトも育ててきました。こちらでは、シェルの定石として冒頭に set -euo pipefail を書いたところ、正常な状態でもスクリプト全体が途中で終わるようになりました。

Terminal window
1
set -euo pipefail
2
3
# launchctl list は、対象のラベルがないと exit 1 を返す
4
last_exit=$(launchctl list "$JOB_LABEL" | awk '/LastExitStatus/ {print $3}')

「ラベルが見つからない」こと自体を検査したいのに、検査の前にスクリプトが落ちてしまいます。grep も、一致しないと exit 1 を返すので同じことが起きます。

Terminal window
1
set -euo pipefail
2
3
# 検査対象のコマンドは || true で守り、結果は別に判定する
4
list_output=$(launchctl list "$JOB_LABEL" 2>/dev/null || true)
5
if [[ -z "$list_output" ]]; then
6
echo "NG: $JOB_LABEL not loaded"
7
fi

大事なのは、「検査対象が 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ケースです。

カテゴリテスト数主な検証内容
Types3frozen dataclass、デフォルト値
Config Loader8YAML の解析、異常系(FileNotFound など)
Infra Monitor7SSD / symlink / DB / ディスク容量
Pipeline Monitor18正常 / 異常 / 境界値 / Consumed パターン / 土日の緩和
Business Monitor7処理件数の追跡、フォールバックの検知
Causal Tracker7上流の障害 → 下流の抑制、独立したパイプライン
Alert Manager15状態の変化、永続化、エスカレーション
E2E + Incident13全モードの結合テスト + 過去のインシデントの再現

特に重視したのが、過去のインシデントを再現するテストです。「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通知に収めています。


まとめ

  1. サイレント障害は、複数の層の「寛容さ」が重なって起きる: 環境変数の欠落、None を許すコンストラクタ、すべてを飲み込む例外処理が重なり、16日間気づけませんでした
  2. 監視は「プロセスが動いたか」ではなく「生成物があるか」で判断する: パイプラインの期待する出力を YAML に定義し、実際の状態と突き合わせ、一致しなければ通知します
  3. 5モジュール78テストで、検知を8〜16日から1時間以内にした: インフラ・生成物・業務メトリクス・因果追跡・通知制御に分け、過去の事故を再現するテストで検知を確かめています

個人で運用するシステムでは、「誰も見ていない間に静かに壊れる」ことが最大のリスクです。それを構造的につぶす仕組みとして、同じ課題を持つ方の参考になれば幸いです。

AI駆動開発での開発・自動化・監視の仕組みづくりについて、ご相談を受け付けています

お仕事のご相談

記事へのご質問・ご感想はこちらのフォームからお送りください

Article title:サイレント障害を1時間以内に検知する監視ハーネス:16日間気づけなかった機能停止とplist30ファイル破損から、5モジュール78テストの設計へ
Article author:45395
Release time:2026-04-05