【ITニュース解説】My job feed broke silently for 3 days. So I built a CI guardrail that fails the build when it happens again

システム開発において、私たちが作ったプログラムやシステムが正しく動いているかを確認することは非常に重要だ。しかし、時にはシステムが「見かけ上は正常なのに、実は間違ったデータを返している」という、非常に厄介な問題が発生することがある。今回の記事は、まさにそのような問題に直面し、それを解決するために構築されたツールについて解説している。

ある開発者が運用していたリモート求人情報のフィードが、ある日突然、誰も気づかないうちに機能不全に陥った事例から話は始まる。このフィードは、求人サイトの情報を収集して表示するシステムだったが、求人サイトのAPI（外部システムと連携するための窓口）自体は正常に稼働していた。つまり、システムからAPIにアクセスすると、HTTP 200 OKという「正常です」という応答が返ってきたのだ。しかし問題は、APIが返すデータの内容にあった。以前は求人情報のリストが返されていたはずのデータフィールドが、突然「空っぽ」になってしまったのである。

これは非常に厄介な種類の失敗だ。なぜなら、システムはAPIから正常な応答を受け取ったと判断し、エラーを検知しないため、通常のエラー監視システムではこの問題を捉えられないからだ。求人情報のスクレイパー（情報収集プログラム）は動き続け、ダッシュボードも更新され続けた。しかし、ダッシュボードに表示される求人件数は、約340件から静かに0件へと減っていった。アラートもなければ、エラーメッセージも表示されず、システムのステータスページには何の問題もないと表示され続けた。

このようなサイレントな失敗は、システムの信頼性を大きく損なう。外部APIが返すデータの形式がわずかに変わったり、必須のフィールドが名前変更されたり、あるいは単に空のコンテナが返されるようになったりするだけで、システム全体が健全に見えながらも、実際には間違った情報を表示し続けることになってしまう。開発者自身がダッシュボードを開いて「あれ、データがないぞ？」と気づくまで、誰もその問題に気づかない可能性があるのだ。

この深刻な問題に対処するため、記事の作者は「CIガードレール」と呼ばれる仕組みを構築した。CIとは「継続的インテグレーション」の略で、ソフトウェア開発のプロセスにおいて、コードの変更を頻繁に統合し、自動的にテストを行うことで品質を保つ手法を指す。このCIの仕組みに組み込む形で、データの構造を「契約」とみなし、その契約が一方的に破られた瞬間にビルド（プログラムを動かせる形にすること）を意図的に失敗させるツールが開発された。それが「jobfeed-watchdog」である。

jobfeed-watchdogは、設定されたJSONやYAML形式のエンドポイント（データが提供されるURLなど）に対して、定期的にそのデータの「構造的なフィンガープリント」を取得して監視する。フィンガープリントとは、データの内容そのものではなく、そのデータの「形」や「骨格」を識別するための情報だ。例えば、データがリスト形式なのか辞書形式なのか、含まれるキー（データの項目名）の種類は何か、といった情報を指す。

このツールは、監視するエンドポイントから取得したデータの現在の構造を、以前に正常だったと認識されている構造と比較する。もし両者に違いが見つかり、構造が「後退（regression）」していると判断された場合、GitHub ActionsなどのCIツール上での実行を「赤く」、つまり失敗させる。これにより、開発者はシステムが見かけ上は正常でも、内部で問題が発生していることにすぐに気づくことができるのだ。

jobfeed-watchdogが具体的にどのような構造の変化を検出するかを説明する。まず、「トップレベルコンテナタイプ」の変化を検出する。これは、データ全体がリスト形式から辞書形式に変わったり、その逆になったりするような、データ構造の根本的な変更を指す。記事の事例のように、本来リストが返されるべき場所が空の辞書になったようなケースがこれに該当する。次に、「レコードキーセットの差分」を検出する。これは、データ内の個々のレコード（例えば求人情報一つ一つ）に含まれるキー（例えば「タイトル」や「給与」といった項目名）が削除されたり、名前が変更されたりした場合に反応する。最後に、「レコードカウントの急激な減少」を検出する。これは、設定した閾値（例えば340件）を下回ってレコード数が急減するような場合にアラートを出す。記事の事例では、求人件数が0になったことで、この機能が活躍する場面だ。

なぜデータの「内容」ではなく「構造」をフィンガープリントするのか、ここがjobfeed-watchdogの肝となる部分だ。求人フィードのようなデータは、常に内容が変化する。新しい求人が追加されたり、古い求人が削除されたり、給与情報が変わったりすることは日常茶飯事だ。もしデータの内容そのものを比較して変化を検出するようにすると、このような正当な変更のたびにアラートが大量に発生し、開発者はどれが本当に重要な変化なのかを判別できなくなり、ツールの信頼性が失われてしまう。これを「誤検知の火の海」と表現している。

それに対し、データの構造、つまり「形」をフィンガープリントすることで、正当な内容の変化には反応せず、データの「契約」、つまり形式が予期せず変わった場合にのみ反応するようになる。このフィンガープリントは、「コンテナタイプ」と「ソートされたレコードキーのセット」、そして「レコードカウントのバケット」のハッシュ（特定のデータを短い文字列に変換したもの）で構成されており、計算コストが安価で、正当な内容変更に対しては安定している。そして、フィードが「静かに契約変更」した際に、最初に壊れるポイントを捉えることができるのである。

このjobfeed-watchdogは、PyPIというPythonのパッケージ管理システムから簡単にインストールできる。また、GitHub Actionsのワークフローに数行のYAMLコードを追加するだけで利用可能だ。feeds.jsonというファイルに監視したいエンドポイントのリストを記述し、min_recordsというパラメータで最小レコード数の閾値を設定する。設定は非常にシンプルで、特別なサーバーや課金、機密情報の管理も不要だ。

実際に問題が発生し、フィードの構造が期待値から外れた場合、GitHub Actionsの実行は赤く表示され、GitHubからの通知が届く。ログには、どのフィードで、どのような変化（コンテナタイプの変更、特定のキーの欠落、レコード数の減少など）が発生したかが詳細に記録されるため、開発者はすぐに原因を特定し、対処することができる。

このツールは、26個のテストケースによってその信頼性が確保されている。これらのテストは、リストから辞書への変更、必須キーの名前変更、閾値を下回るカウントの減少といった、それぞれの失敗モードを個別に検証している。最も重要なテストは、正当な内容の変更があった場合には誤ってエラーを報告しないことだ。信頼性のないツールは、まるで「オオカミ少年」のように頻繁に嘘のアラートを出すため、結局誰も信用しなくなり、役に立たなくなってしまうからだ。

開発者がこのツールを構築した背景には、個人的な課題があった。彼はサイドプロジェクトでいくつかのリモート求人フィードを運用しており、サイレントなデータ破損を検出するために、毎朝手動でダッシュボードをリフレッシュして確認していたという。しかし、そのためだけに高価なモニタリングシステムを導入したり、稼働監視ツールにお金を払ったりしたくなかった。そこで彼は、すでに利用しているCIシステム（GitHub Actions）を無料で活用し、監視を行うことを決めたのである。

jobfeed-watchdogはオープンソースとして公開されており、MITライセンスで提供されている。もし、あなたが求人情報や市場データ、APIのリストなど、何らかのJSONフィードを利用しており、そのフィードが静かに構造を変更した瞬間にビルドを失敗させて検出したいと考えているならば、わずか数行のワークフローでこの強力なガードレールを導入できる。これは、見つけにくいサイレントな問題を未然に防ぎ、システムの信頼性を高めるための、シンプルながらも非常に効果的な解決策だと言えるだろう。