【ITニュース解説】48-Hour Field Notes: It Passed Locally and Died Remotely — Eight Environment Facts I Now Diff First

システムエンジニアを目指す皆さんにとって、開発したプログラムが自分のパソコンでは問題なく動いたのに、いざ別のサーバーやクラウド環境にデプロイすると予期せぬエラーで停止するという経験は、IT開発で非常によくある課題の一つである。これは通称「ローカルでは動くのにリモートでは動かない」という現象で、多くの開発者を悩ませてきた。この問題は、単にプログラムのバグというよりも、実はプログラムが動作する「環境」の違いに起因している場合が少なくない。

具体的には、タイムゾーンの設定、プログラムが利用できるファイル数の上限、あるいは文字コードの扱い方など、一見するとプログラム本体とは直接関係ないように思える細かな環境設定の差異が、プログラムの予期せぬ挙動を引き起こすことがある。そして厄介なことに、このような環境の差異による問題は、一般的なプログラムのエラーのようにエラーの発生場所を詳細に教えてくれる「スタックトレース」が表示されないことが多い。プログラムはただ「終了コード1」といった漠然としたメッセージを残して停止するため、どこに問題があるのか特定するのに膨大な時間がかかってしまう。開発者は、誤って動かない原因をプログラムのロジックにあると信じ込み、実際には問題ない箇所を何時間もかけて修正してしまうこともある。

このような状況を解決するための効果的なアプローチは、アプリケーションのログを詳細に分析するのではなく、プログラムが動作する「環境の事実（ファクト）」を比較することである。アプリケーションログは、問題が起きた「後」の出来事を記録しているに過ぎない。しかし、環境の事実は、なぜ同じ入力に対して異なる動作が発生したのか、その「原因」を教えてくれる。両方の環境の事実を並べて比較することで、どちらの環境が「おかしい」のかという議論はすぐに終わり、具体的な対策に移ることができる。

そこで提案されるのが、以下の8つの環境事実を比較するアプローチだ。まず「Pythonのバージョンとバイナリ名」は、マイナーバージョンの違いで標準ライブラリの挙動が変わったり、シェルが示すPythonと実際に実行されるPythonが異なる可能性があるため重要である。次に「デフォルトおよび推奨されるエンコーディング」は、プログラムが文字をどのように解釈・出力するかに影響し、これが異なると文字化けやプログラムの異常終了を引き起こすことがある。

また「タイムゾーン名とUTCオフセット」は、日付や時刻を扱う処理で結果が変わる原因となり得る。特に、協定世界時（UTC）と現地時刻の違いが問題になることはよくある。さらに「ロケール環境変数」は、数字や日付の書式、文字のソート順などに影響を与え、プログラムが想定外のデータを処理する原因になることもある。「CPU数とCPUアフィニティ」は、マルチスレッド処理や並列処理を行うプログラムのパフォーマンスや挙動に影響する。特に、コンテナ環境などでは見かけ上のCPU数と実際に利用可能なCPU数が異なる場合があるため注意が必要だ。

重要な項目として「ファイルディスクリプタとプロセス制限」がある。これは、プログラムが同時に開けるファイルの数や、生成できるプロセスの数に上限を設けるもので、データベース接続のプールや、多数のファイルを扱う処理でこの上限を超えると、プログラムは突然エラーで停止する。次に「一時ディレクトリのファイルシステムと空き容量」は、一時ファイルを大量に作成するプログラムや、一時ファイルの削除・移動に関する挙動に影響を与える。例えば、一時ファイルがメモリ上に作成される「tmpfs」とディスク上に作成される「ext4」では、パフォーマンスや耐久性が異なる。「カレントディレクトリのファイルシステム」も同様に、ファイル操作のコストや挙動に影響を与える場合があり、特にネットワークファイルシステムなど、特殊な環境では予期せぬ問題が発生することがある。

これらの環境事実を効率的に収集・比較するために、記事ではPython製のシンプルなスクリプトが紹介されている。このスクリプトはPythonの標準ライブラリのみを使用しており、外部の依存関係がないため、どんな環境でも手軽に実行できる。使い方は非常にシンプルで、まず正常に動作するローカル環境で「capture」コマンドを実行し、環境情報をJSONファイルとして保存する。次に、問題が発生するリモート環境で全く同じコマンドを実行し、同様に環境情報を保存する。そして、これら二つのJSONファイルを同じ場所に集めて、「diff」コマンドを実行するだけで、両方の環境の異なる点が明確に表示される。

この比較結果（diff）は、非常に具体的で分かりやすい。例えば、タイムゾーンのオフセットがローカルとリモートで異なれば、「time.utc_offset_s」の項目にそれぞれの値が表示され、タイムゾーンの設定が異なっていることが一目でわかる。文字エンコーディングが異なれば、「encoding.stdout」の項目にそれぞれの値が表示される。このように、具体的な差異がリストアップされることで、漠然としたエラーに悩まされることなく、具体的な仮説を立てることができる。タイムゾーンのずれによるファイル名の日付のずれ、ASCIIエンコーディングしか扱えないために発生する文字化け、ファイルディスクリプタの制限を超える接続プールなどが、すぐに具体的な疑いとして浮かび上がる。

重要なのは、この比較結果から立てた「仮説」は、まだ「証拠」ではないということである。仮説は、必ず具体的なシェルコマンドを使って検証する必要がある。例えば、ファイルディスクリプタの制限が怪しいと思ったら、「ulimit -n」などのコマンドを実行して、実際に制限値を確認する。この「仮説→コマンドによる検証」というプロセスをきちんと踏むことで、無駄な試行錯誤を避け、効率的に問題解決に導くことができる。検証せずに修正を試みると、結局は当てずっぽうな対応に時間を費やし、最初の48時間を無駄にするような事態に陥りかねない。

また、どのような環境の差異が、どのようなジョブの挙動に影響を与えやすいかを示した決定表も非常に有用である。例えば、タイムゾーンのオフセットは日付を含むファイル名やcronの実行時間には影響を与えやすいが、日付を扱わない純粋な計算ジョブには影響しない可能性が高い。エンコーディングの違いは非ASCII文字の入出力に影響するが、ASCII文字のみを扱うログには問題ないかもしれない。このような知識があれば、diff結果の多くの行の中から、本当に問題を引き起こしていそうな箇所を素早く特定できる。

このアプローチを実践する上で重要なヒントがいくつかある。問題が起きる前に、つまり正常な環境と、問題が起こりうる環境の両方で環境情報をキャプチャすることが望ましい。また、キャプチャしたJSONファイルは、プログラムの出力結果と一緒に保存しておくと、将来同じ問題が発生した際に役立つ。さらに、環境情報を取得するコマンドも含め、実行するすべてのコマンドでPythonインタプリタのパスを明示的に指定することで、異なるPython環境が起動するリスクを減らせる。

逆に避けるべきなのは、環境情報を確認する前に、やみくもにログ出力を追加したり、まずライブラリのバージョンを疑ったりすることである。また、検証コマンドが提示されていない情報を鵜呑みにするのも危険である。

ただし、この環境比較ツールにも限界がある。取得できるのはある時点での環境情報であり、もし実行セッションごとにリモートホストが再作成されるような環境であれば、その都度情報をキャプチャする必要がある。また、Windows環境では取得できる情報が一部制限される。さらに、プログラムのパッケージバージョンや、ネットワーク・DNSの挙動についてはこのツールでは把握できないため、別途ロックファイルやネットワーク診断ツールと組み合わせて利用する必要がある。もし、すでにコンテナ環境やCI/CDパイプラインを適切に利用し、完全に再現可能な環境を構築している場合は、この問題はより高度な方法で解決されているため、このツールは不要だろう。

しかし、自分のパソコンでは動くのにリモートで動かないという問題に直面し、何日も原因不明のエラーに悩まされた経験がある開発者にとっては、この「環境の事実を比較する」アプローチは非常に強力な武器となる。一度このツールを作成し、10分程度で両環境の情報を取得して比較するだけで、何日ものデバッグ時間と混乱を回避できるのだ。システムエンジニアを目指す上では、このような問題解決の思考法と具体的なツールを学ぶことは、非常に有益である。