自作ロガーの最小要件

まず結論

自作ロガーの最初の目標は、高機能化ではなく「障害時に信じられること」です。最初の版で押さえたい要点は次のとおりです。

• 形式は UTF-8 の JSON Lines にする
• 1 レコード 1 行を崩さない
• 必須項目: timestamp, level, category, message, fields, sessionId, processId
• 基本は 1 プロセス 1 ファイル
• 低負荷なら同期書き込み、多めなら single writer + bounded queue
• Error / Critical とセッション開始・終了は同期 flush する
• 回転と保持は v1 から入れる
• 保存先が使えないときに、黙って別の場所へ逃がさない

対象範囲を狭くする

対象はアプリケーション障害の切り分けに使う診断ログに絞ります。「いつ」「どの処理で」「何が起き」「そのときどんな文脈だったか」を後から追えることを優先します。

最低限必要な要件

1. 形式は UTF-8 JSON Lines

1 行が 1 レコードであれば、テキストとしても読みやすく、後でスクリプトやツールから解析しやすくなります。途中で書き込みが切れても、壊れたのがどの行かを切り分けやすい点も実務向きです。

2. 必須項目を固定する

7 つの必須項目: timestamp, level, category, message, fields, sessionId, processId。message だけの文字列ログにすると検索が困難になります。逆に項目を増やしすぎると呼び出し側の負担が増えます。

3. 1 プロセス 1 ファイルを基本にする

複数プロセスから同じファイルへ追記させる設計は、排他制御や部分書き込み、回転タイミング、異常終了時の扱いが一気に難しくなります。

4. 書き込み戦略は負荷で分ける

• ログ量が少ない → 同期書き込み（分かりやすく障害調査しやすい）
• ログ量が多い → single writer + bounded queue
• キューあふれ時の方針（古いログを捨てる/新しいログを落とす/警告を出す）を先に決める

5. flush 条件を決める

Error と Critical、セッション開始・終了のログは同期 flush します。普段の Info まで全部 flush すると遅くなります。

6. 回転と保持は v1 から

「後で入れればよい」と思われがちですが、運用に入ると急に困ります。少なくとも「無限に増え続けない」ことと「何本残すか」を決めておきます。

7. 保存失敗時に勝手な代替保存をしない

保存先が使えないときに黙って別の場所へ書くと、運用担当が「あるはずの場所」にログがないことで初動が遅れます。通知や標準エラー出力など、明示的に失敗を表に出してください。

よくある NG

• message 文字列にすべてを詰め込む
• 複数プロセスで同じファイルを共有する
• flush 条件を決めずに全面非同期化する
• 回転と保持を後回しにする
• 保存失敗時に黙って別フォルダへ逃がす
• ネットワーク転送やローカル DB 保存まで v1 に入れる

結合テスト項目

logger はユニットテストだけでは安心できません。実ファイル・実スレッド・実プロセスでの結合テストが必要です。v1 で最低限通したい 6 本:

1. 単一スレッドでの正常書き込み
2. 複数スレッド同時書き込み（レコードが壊れないか）
3. Error / Critical の flush（即時反映されるか）
4. 回転と保持（条件で切り替わり、上限を超えた古いファイルが削除されるか）
5. 保存先異常時の失敗通知（ディレクトリ不在、権限不足、ディスクフル）
6. 正常終了時の drain と最終 flush

追加で確認したい異常系

• 保存先ディレクトリが存在しないときの挙動
• 書き込み権限がないときの挙動
• ディスクフル時の通知や戻り値
• キューあふれ時の動作
• 改行混入で複数行に壊れないか
• 例外終了に近い経路でも必要な終了ログが残るか

まとめ

自作ロガーの最初の目標は、高機能化ではなく「障害時に信じられること」です。形式を UTF-8 JSON Lines に固定し、必須項目を絞り、1 プロセス 1 ファイルを基本にし、flush・回転・保持・失敗時挙動を早めに決めます。そして実ファイル・実スレッド・実プロセスを使う結合テストで確認します。実装を大きくする前に、最小構成と最低限のテストセットを先に固めましょう。