--- title: "PythonのRotatingFileHandlerでログローテーション｜maxBytes・backupCountの設定と複数プロセス対策" url: "https://www.issoh.co.jp/tech/details/3696/" published: 2024-10-01 updated: 2026-07-13 categories: ["Python"] publisher: "株式会社一創" --- # PythonのRotatingFileHandlerでログローテーション｜maxBytes・backupCountの設定と複数プロセス対策 ログローテーションは、肥大化するログファイルを一定の条件で新しいファイルへ切り替え、古い世代を順に捨てていく仕組みです。Pythonの`logging.handlers.RotatingFileHandler`はこれを標準ライブラリだけで実現し、ローテーションに関わる設定は`maxBytes`と`backupCount`の2つで決まります。ただし、この2つは片方でも0にするとローテーションが一切起きず、複数プロセスから同じファイルへ書くと世代の入れ替えそのものが失敗します。ここでは最小構成から、保存世代の見積もり、`logrotate`との併用、複数プロセス環境での破綻の回避までを扱います（記載はPython 3.14系の標準ライブラリの挙動に基づきます）。 ## まとめ - `RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)`が実務の出発点。**`maxBytes`と`backupCount`はどちらかが0だとローテーションが起きない**ため、両方に非ゼロを入れる。 - ディスク使用量の上限は`maxBytes×(backupCount+1)`で決まる。上の例なら約60MBが上限。 - 日次・時刻で切り替えたいなら`TimedRotatingFileHandler`（`when="midnight"`など）。サイズ上限を守りたいならRotatingFileHandler。両方の性質は標準ライブラリでは併用できない。 - Linuxの`logrotate`でローテーションするなら、Python側は`WatchedFileHandler`にする。RotatingFileHandlerのまま外部ローテーションを併用すると、リネームされた古いファイルへ書き続ける。 - Gunicornのワーカーやマルチプロセスから同じログファイルへ書く構成では、標準のRotatingFileHandlerは壊れる。`QueueHandler`＋`QueueListener`で書き込みを1プロセスに集約するか、`concurrent-log-handler`に置き換える。 以下、パラメータの挙動から順に見ていきます。 ## RotatingFileHandlerの最小構成とパラメータ ### maxBytesとbackupCountの意味と「0」の罠 コンストラクタのシグネチャは`RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)`です。既定値がどちらも0である点が重要で、公式ドキュメントは**`maxBytes`と`backupCount`のいずれかが0ならロールオーバーは起こらない**と明記しています。`RotatingFileHandler("app.log")`とだけ書くと、ローテーションしないただの`FileHandler`と同じ動作になり、ログが無限に肥大します。 ``` import logging from logging.handlers import RotatingFileHandler logger = logging.getLogger("app") logger.setLevel(logging.INFO) handler = RotatingFileHandler( "logs/app.log", maxBytes=10 * 1024 * 1024, # 10MBでローテーション backupCount=5, # app.log.1 〜 app.log.5 を保持 encoding="utf-8", delay=True, # 最初の書き込みまでファイルを開かない ) handler.setFormatter(logging.Formatter( "%(asctime)s %(levelname)s %(name)s %(process)d %(message)s" )) logger.addHandler(handler) logger.info("起動しました") ``` `encoding="utf-8"`は日本語ログでは必須です。指定しないとロケール依存のエンコーディングになり、Windowsではcp932で書かれて文字化けや`UnicodeEncodeError`を招きます。`delay=True`を付けると最初の`emit()`までファイルを開かないため、ログを1行も出さないプロセスが空ファイルを作らずに済みます。ファイルを開く時点を遅らせるだけで、複数プロセスが同じファイルを開くこと自体は防げません（後述の破綻はこれでは回避できません）。出力先ディレクトリは事前に作っておく必要があり、パスの組み立てには[Python pathlibの使い方｜resolve・絶対パス取得・Path(\_\_file\_\_).resolve().parentとos.pathの違い](/tech/details/5986/)で解説している`Path`を使うと、実行ディレクトリに依存しない絶対パスにできます。 ### ロールオーバー時のファイル名と削除の順序 ローテーションの判定はレコードを書き出す直前に行われます。「今のファイルサイズ＋これから書く1行」が`maxBytes`を超えるなら、書く前に切り替えます。つまり`maxBytes`はほぼ上限として守られ、あとから超過分を削るような動きはしません。 厳密には「ほぼ」です。判定はファイル位置（バイト）にメッセージの**文字数**を足して行うため、UTF-8で1文字3バイトになる日本語ログでは、実ファイルが`maxBytes`をわずかに超えます（`maxBytes=1000`で日本語を出力すると1,057バイトになる、といった数%の超過です）。容量設計では上限ちょうどではなく数%の余裕を見てください。 切り替えでは、既存のバックアップが末尾から順にずれていきます。`backupCount=5`・ベース名`app.log`なら、`app.log.5`が削除され、`app.log.4`→`app.log.5`…と改名が進み、最後に現在の`app.log`が`app.log.1`になって新しい`app.log`が開かれます。番号が小さいほど新しいログです。 命名規則と移動処理は差し替えられます。上で作った`handler`に対して、`namer`（ローテーション後のファイル名を返す関数）と`rotator`（「移動」の実装）を設定すると、切り替えと同時にgzip圧縮できます。 ``` import gzip, os, shutil def gzip_rotator(source, dest): with open(source, "rb") as fin, gzip.open(dest, "wb") as fout: shutil.copyfileobj(fin, fout) os.remove(source) handler.namer = lambda name: name + ".gz" # app.log.1.gz として世代管理させる handler.rotator = gzip_rotator ``` `namer`を既定のままにして`rotator`の中で`.gz`を付け足す書き方は避けてください。ハンドラーは`app.log.1`が存在する前提で世代をずらすため、実体が`app.log.1.gz`しかないと世代シフトが空振りし、`backupCount`を指定しても最新の1世代しか残りません（`backupCount=3`で実行すると`app.log.1.gz`だけが毎回上書きされます）。圧縮後のファイル名は`namer`側で決めるのが正しい形です。 ## 時刻で切り替えるTimedRotatingFileHandler 「1日1ファイル」「毎週月曜に切り替え」のように時間で区切りたい場合は`TimedRotatingFileHandler`を使います。`when`に指定できる値は`S`（秒）、`M`（分）、`H`（時）、`D`（日）、`W0`〜`W6`（曜日指定・W0が月曜）、`midnight`の6系統です。`interval`と組み合わせて「`when="H", interval=6`＝6時間ごと」のように指定します。`midnight`と`W0`〜`W6`では`atTime`で切り替え時刻を指定でき、省略すると初回のロールオーバー時刻がプロセス起動時刻に引きずられます。深夜3時に切り替えたいなら`atTime=datetime.time(3, 0)`を明示してください。 ``` from logging.handlers import TimedRotatingFileHandler handler = TimedRotatingFileHandler( "logs/app.log", when="midnight", # 日付が変わるタイミングで切り替え interval=1, backupCount=14, # 14日分を保持 encoding="utf-8", utc=False, # ローカルタイム基準。コンテナのTZ設定に注意 ) ``` ローテーション後のファイルには日時サフィックスが付き、`app.log.2026-07-12`のような名前になります（`when`が時分秒の場合は`%Y-%m-%d_%H-%M-%S`まで含みます）。`backupCount`を超えた古いファイルは、このサフィックス形式にマッチするものを探して削除する実装になっているため、**`namer`で命名規則を大きく変えると古いファイルが削除されなくなる**点に注意してください。 時刻ベースの弱点は、サイズの上限を保証できないことです。障害時にエラーログが噴き出すと、1日分のファイルが数GBに膨らみます。逆にRotatingFileHandlerはサイズの上限を守れますが、「昨日のログ」を日付で特定できません。標準ライブラリはサイズと時刻の両方を条件にするハンドラーを持たないため、両立が必要なら後述の`concurrent-log-handler`のようにサイズ・時刻双方に対応した実装を使うか、OS側の`logrotate`に寄せる判断になります。 ## 保存世代とディスク使用量の見積もり 「ログの保存期間をどう決めるか」は`backupCount`の設計そのものです。RotatingFileHandlerが保証するのはサイズであり、期間ではありません。まず上限は次の式で決まります。 | 設定 | ファイル数 | ディスク上限 | 目安の保持期間 | | ------------------------------ | ----- | ------ | -------------- | | maxBytes=10MB / backupCount=5 | 6 | 約60MB | 1日1MB出るなら約60日 | | maxBytes=100MB / backupCount=3 | 4 | 約400MB | 1日100MB出るなら約4日 | | maxBytes=10MB / backupCount=0 | 1 | 無制限 | ローテーションされない | 上限は`maxBytes×(backupCount+1)`です。設計の順序は逆にします。まず「このサーバーでログに割ける容量」と「障害調査で遡りたい期間」を決め、1日あたりのログ量を実測してから`maxBytes`と`backupCount`を逆算します。1日あたりの量が読めないうちは、`backupCount`を多め（10〜20）にして`maxBytes`を小さく（10〜50MB）するほうが、調査可能な期間を確保しやすくなります。 監査要件などで「90日間の保存」が決まっている場合、サイズ基準のRotatingFileHandlerでは期間を保証できません。この場合は`TimedRotatingFileHandler`で日次に切り、`backupCount=90`とするのが素直です。アプリケーション以外のログ（データベースのスロークエリログなど）も含めた保存方針は、[スロークエリログとは｜MySQLの設定・見方・解析ツールと改善手順](/tech/details/3582/)のように出力元ごとの設定が別々になるため、サーバー全体では出力元を一覧化して合計容量を見積もってください。 ## dictConfigによる設定の外部化 ハンドラーをコード内で組み立てると、開発環境と本番環境でログ設定を切り替えるたびにコードを触ることになります。`logging.config.dictConfig()`を使えば、辞書（実務ではYAMLやJSONから読む）で宣言できます。 ``` import logging.config LOGGING = { "version": 1, "disable_existing_loggers": False, "formatters": { "standard": { "format": "%(asctime)s %(levelname)s %(name)s %(message)s", }, }, "handlers": { "file": { "class": "logging.handlers.RotatingFileHandler", "filename": "logs/app.log", "maxBytes": 10485760, "backupCount": 5, "encoding": "utf-8", "formatter": "standard", "level": "INFO", }, "console": { "class": "logging.StreamHandler", "formatter": "standard", "level": "DEBUG", }, }, "root": {"handlers": ["file", "console"], "level": "DEBUG"}, } logging.config.dictConfig(LOGGING) ``` `maxBytes`は辞書の中では数値リテラルで書きます（`10*1024*1024`のような式はJSON/YAMLでは評価されないため、10485760のように展開しておきます）。ロガーとハンドラーの`level`は独立で、レコードは**ロガーのレベルで足切りされてからハンドラーのレベルで再度足切りされます**。ロガー側が`INFO`のままハンドラーだけ`DEBUG`にしてもDEBUGログは出ません。上の例のようにルートロガーを`DEBUG`にし、ハンドラーごとに出す粒度を変えるのが定石です。 レベルは`DEBUG`(10) < `INFO`(20) < `WARNING`(30) < `ERROR`(40) < `CRITICAL`(50)の5段階で、設定した値**以上**のレコードが通ります。既定のルートロガーは`WARNING`のため、何も設定せず`logger.info()`を呼んでも出力されないのは仕様です。 ## 複数プロセス書き込みでのローテーション破綻 ここが実務で最も踏みやすい落とし穴です。GunicornやuWSGIのワーカー、`multiprocessing`で分岐した子プロセス、cronで並走するバッチ——これらが同じ`app.log`を同じRotatingFileHandlerの設定で開くと、ローテーションのタイミングで破綻します。Pythonの公式クックブックは、**複数プロセスから単一のファイルへログを書くことは標準ではサポートされない**と明言しています。ファイルへのアクセスをプロセス間で直列化する標準的な手段がないためです。 症状はOSによって違います。Windowsでは、あるプロセスがファイルを開いたままだと別プロセスがそれをリネームできないため、ロールオーバーが`PermissionError`で失敗します。このとき例外は呼び出し元へ伝播せず、標準エラー出力にトレースバックが出るだけなので（Gunicornのエラーログに埋もれて気づかれません）、そのまま以降のログが落ち続けます。Linuxではリネーム自体は成功しますが、他プロセスは開いたままの古いinodeへ書き続けるため、ローテーション後のログが「消えたファイル」に書かれて回収できなくなります。どちらも、ログが必要になった障害調査の当日に発覚します。 ### 書き込みを1プロセスに集約する（QueueHandler + QueueListener） 標準ライブラリだけで解決するなら、各プロセスは`QueueHandler`でキューにレコードを積むだけにして、実際にファイルへ書くのは`QueueListener`を持つ1プロセスだけにします。ファイルを開くプロセスが1つになるため、RotatingFileHandlerの前提が満たされます。 ``` import logging import multiprocessing from logging.handlers import QueueHandler, QueueListener, RotatingFileHandler from multiprocessing import Process, Queue def worker(queue): logging.getLogger().addHandler(QueueHandler(queue)) logging.getLogger().setLevel(logging.INFO) logging.getLogger("worker").info("子プロセスからのログ") if __name__ == "__main__": # multiprocessingの内部ロガーはQueueへのput時にDEBUGログを出す。 # 同じキューに載ると再帰・デッドロックを招くためINFO以上に上げる multiprocessing.get_logger().setLevel(logging.INFO) queue = Queue() # multiprocessing.Queue（queue.Queueはスレッド間専用） file_handler = RotatingFileHandler( "logs/app.log", maxBytes=10485760, backupCount=5, encoding="utf-8" ) listener = QueueListener(queue, file_handler, respect_handler_level=True) listener.start() procs = [Process(target=worker, args=(queue,)) for _ in range(4)] for p in procs: p.start() for p in procs: p.join() listener.stop() ``` キューには`multiprocessing.Queue`を使います（`queue.Queue`はスレッド間でしか共有できません）。なお公式ドキュメントは、`multiprocessing`内部のロガーが`multiprocessing.Queue`への`put`時にDEBUGログを出すため、同じキューを`QueueHandler`に渡すとデッドロックや無限再帰を招きうると警告しています。`multiprocessing`のロガーのレベルを上げるか、専用のキューを分けてください。`spawn`モード（WindowsとmacOSの既定）では子プロセスにハンドラーが引き継がれないため、上のように子側で`QueueHandler`を登録し直す実装が必要です。 ### concurrent-log-handlerへ置き換える プロセス構成に手を入れられない場合——たとえばGunicornのワーカーが直接ファイルに書く既存構成——は、ファイルロックで直列化する`concurrent-log-handler`が現実的です。最新版は0.9.29（2026年2月22日リリース、Apache-2.0）で、`ConcurrentRotatingFileHandler`はRotatingFileHandlerの差し替えとして設計されており、WindowsとPOSIXの両方でロックを取ります。時刻ベースの`ConcurrentTimedRotatingFileHandler`もあり、`use_gzip=True`でローテーション時の圧縮も指定できます。 ``` from concurrent_log_handler import ConcurrentRotatingFileHandler handler = ConcurrentRotatingFileHandler( "logs/app.log", maxBytes=10485760, backupCount=5, encoding="utf-8", use_gzip=True, ) ``` 判断基準ははっきりしています。**ログ量が多くスループットが要る、あるいはプロセス構成を自分で設計できるならQueueHandler方式**——書き込みが1プロセスに集約されるのでロック競合が起きず、標準ライブラリだけで完結します。**既存のワーカー構成を変えずに今のローテーション不具合を止めたいならconcurrent-log-handler**——ハンドラーのクラス名を差し替えるだけで済みます。反対に、複数プロセス環境で標準のRotatingFileHandlerをそのまま使い続ける選択だけは避けてください。「今は動いているように見える」のは、まだローテーションの瞬間に競合していないだけです。 ## logrotateと併用するならWatchedFileHandler Linuxサーバーでは、アプリケーションのログもOSの`logrotate`でまとめて管理する運用がよくあります。このとき**Python側でRotatingFileHandlerを使ってはいけません**。logrotateがファイルをリネームしても、Pythonプロセスは開いているファイルディスクリプタ（＝リネーム後の古いファイル）へ書き続けるため、新しい`app.log`には何も書かれなくなります。 正解は`WatchedFileHandler`です。このハンドラーは書き込みのたびにファイルのデバイス番号とinodeを確認し、変化していればストリームを閉じてファイル名で開き直します。外部ツールによるローテーションを検知するための実装で、Unix/Linux向けです（Windowsは開いているファイルをリネームできないため、この方式自体が成立しません）。書き込みのたびに`os.stat`を呼ぶため、毎秒数千行を吐くような高頻度のログでは相応のオーバーヘッドになります。その規模ではファイル出力自体を見直す段階です。 ``` from logging.handlers import WatchedFileHandler handler = WatchedFileHandler("/var/log/myapp/app.log", encoding="utf-8") ``` ``` /var/log/myapp/*.log { daily rotate 14 missingok notifempty compress delaycompress # 既定の方式。リネーム後に新しいファイルを作る create 0640 myapp myapp } ``` WatchedFileHandlerを使う場合、logrotate側は既定の`create`（リネーム＋新規作成）で構いません。`copytruncate`は「コピーしてから元ファイルを切り詰める」動作で、開き直しが不要になる代わりに、コピーと切り詰めの間に書かれたログが失われます。ハンドラーを差し替えられない事情がない限り、`copytruncate`は避けてください。 アプリケーションを[systemdとは何か？Linuxにおける役割と概要解説](/tech/details/8160/)で常駐サービス化しているなら、そもそもファイルへ書かず標準出力に出して`journald`に集める選択もあります。コンテナ環境でも同様で、標準出力に出してDockerのログドライバーやログ収集基盤へ委ねるなら、アプリ側のローテーション設定自体が不要になります。ファイル出力とローテーションが本当に必要なのは、ログ収集基盤がない、あるいはファイルとして手元に残す要件がある場合です。 ## ローテーションされない・ログが重複するときの確認 - **まったくローテーションしない**：`maxBytes`か`backupCount`が0のままになっていないか。どちらか一方でも0なら切り替わりません。 - **ローテーション後にログが書かれない**：複数プロセスが同じファイルを開いていないか。前章の症状です。`lsof`で同一ファイルを開いているプロセス数を確認します。 - **同じログが2回出る**：ハンドラーを二重登録しているか、子ロガーとルートロガーの両方にハンドラーが付いています。`logger.propagate`は既定で`True`のため、子ロガーのレコードは親にも伝播します。モジュール側では`logging.getLogger(__name__)`でロガーを取得するだけにし、ハンドラーの登録はエントリポイントで1回だけ行うのが原則です。 - **ファイルが空のまま**：ロガーのレベルが`WARNING`（既定）で`info()`が落とされている、あるいは`delay=True`でまだ1件も出力していない状態です。 - **日付が想定とずれる**：`TimedRotatingFileHandler`の`utc`とコンテナのタイムゾーン設定を確認します。TZ未設定のコンテナはUTCで動きます。 複数台のサーバーに散ったログを一箇所で確認したい段階に入ったら、SSH経由でログを回収する方法を[Paramikoとは？PythonでSSH接続・コマンド実行・SFTP転送を行う使い方【5.0対応】](/tech/details/4029/)にまとめています。恒常的な運用では、ログ収集基盤への転送を検討する時期です。 ## よくある質問 ### RotatingFileHandlerでログがローテーションされないのはなぜですか？ ほとんどの場合、`maxBytes`か`backupCount`が0のままです。公式ドキュメントのとおり、どちらか一方でも0だとロールオーバーは発生せず、単一ファイルに追記され続けます。`RotatingFileHandler("app.log")`のように引数を省略すると既定値が両方0になるため、必ず両方に非ゼロを指定してください。それでも切り替わらない場合は、複数プロセスが同じファイルを開いていないかを疑います。 ### maxBytesとbackupCountはどのくらいの値にすべきですか？ ディスク使用量の上限が`maxBytes×(backupCount+1)`になるため、ログに割ける容量から逆算します。1日あたりのログ量が読めない段階では、10MB×backupCount=10（上限約110MB）程度から始め、実測後に調整するのが安全です。1ファイルを大きくしすぎるとエディタで開けず調査しづらくなるため、`maxBytes`は10〜50MB程度に収めることをおすすめします。 ### RotatingFileHandlerとTimedRotatingFileHandlerはどちらを使うべきですか？ ディスク容量の上限を守ることが最優先ならRotatingFileHandler、障害調査で「何月何日のログ」を日付で特定したいならTimedRotatingFileHandlerです。標準ライブラリの両ハンドラーはサイズと時刻を同時に条件にできないため、両方が必要なら`concurrent-log-handler`のような外部実装か、OS側の`logrotate`（`size`と`daily`の併記が可能）に寄せます。 ### Gunicornのように複数ワーカーがある環境でも使えますか？ そのままでは使えません。複数プロセスが同じファイルを開いた状態でローテーションすると、WindowsではリネームがPermissionErrorで失敗し、Linuxでは古いinodeへ書き続けてログが失われます。`QueueHandler`と`QueueListener`で書き込みを1プロセスに集約するか、ファイルロックを持つ`ConcurrentRotatingFileHandler`へ差し替えてください。 ### logrotateでローテーションする場合、Python側の設定はどうしますか？ `WatchedFileHandler`を使います。書き込みのたびにinodeの変化を検出して開き直すため、logrotateが`create`方式でリネームしても新しいファイルへ追従できます。RotatingFileHandlerのまま併用すると、リネームされた古いファイルに書き続けることになります。 ## 関連記事 - [Python pathlibの使い方｜resolve・絶対パス取得・Path(\_\_file\_\_).resolve().parentとos.pathの違い](/tech/details/5986/) - [Python 3.14の新機能まとめ｜JITコンパイラ・フリースレッド版(GIL撤廃)・t-stringを最新版で解説](/tech/details/9409/) - [systemdとは何か？Linuxにおける役割と概要解説](/tech/details/8160/) - [スロークエリログとは｜MySQLの設定・見方・解析ツールと改善手順](/tech/details/3582/) - [Paramikoとは？PythonでSSH接続・コマンド実行・SFTP転送を行う使い方【5.0対応】](/tech/details/4029/) --- 出典: [PythonのRotatingFileHandlerでログローテーション｜maxBytes・backupCountの設定と複数プロセス対策]()（株式会社一創）