Bottleアプリの運用で絶対に避けたいログ設計のアンチパターンと標準ライブラリの正しい連携

BottleフレームワークとPython標準loggingモジュールで堅牢なログ基盤を構築するイメージ バックエンド

Bottleの軽量さは開発速度を上げてくれますが、ログ設計を誤ると本番環境で原因追跡が途端に困難になります。
print()で流したデバッグ出力が標準出力に埋もれる、リクエストIDが紐付かず並行アクセスのログが判別不能になる。
そんな状況に心当たりはないでしょうか。

特に陥りがちなのが、標準ライブラリのloggingをフレームワーク任せにしてしまうことです。
ハンドラ内でのbasicConfig()の都度呼び出しや、ルートロガーへの直接出力は、ログレベルの制御不能や二重出力という典型的なアンチパターンを招きます。
運用時のノイズとなり、本当に必要なエラーシグナルを見逃す原因になります。

本記事では、Bottleアプリケーションで絶対に避けたいログ設計のアンチパターンを整理し、loggingモジュール本来の思想であるロガー・ハンドラ・フォーマッタの分離に立ち返った、正しい連携方法を解説します。

  • なぜlogging.getLogger(__name__)が原則なのか
  • WSGIサーバーのログとアプリケーションログをどう統合すべきか
  • 構造化ログで運用性をどう担保するか

小さいからこそ設計が問われるBottleだからこそ、堅牢な可観測性の土台を構築します。

  1. Bottleでログ設計が運用を左右する理由とは
    1. 小規模フレームワークだからこそログが重要になる背景
    2. Python標準ライブラリloggingの基本思想をおさらい
  2. 絶対に避けたいBottleのログ設計アンチパターン5選
    1. printデバッグの残留と標準出力への直接依存
    2. ルートハンドラ内でbasicConfigを呼び出す問題
    3. ルートロガーへの直接出力とログレベルの固定化
    4. 例外を握りつぶすtry-exceptとログ出力の欠落
    5. コンテキスト情報なしのログがもたらすデバッグ困難
  3. printデバッグと標準出力依存が招く運用崩壊
    1. なぜprintは本番環境で機能しないのか
    2. loggingへの置き換えで得られるレベル制御と出力先分離
  4. logging.basicConfig()をルートハンドラで呼ぶ危険性
    1. basicConfigの多重呼び出しによる二重出力と設定上書き
    2. アプリケーション初期化時に一度だけ設定する正しい方法
  5. BottleとPython標準ライブラリloggingを正しく連携させる基本設計
    1. getLogger(name)による階層化とモジュール別ロガー管理
    2. ハンドラとフォーマッタを分離して再利用性を高める
    3. 辞書設定dictConfigで実現する宣言的なログ構成
  6. WSGIサーバーとBottleのログを統合する実践テクニック
    1. gunicornやuWSGIのアクセスログとアプリログの分離と統合
    2. Bottleのhookとミドルウェアで共通ログ処理を実装する
  7. 運用で役立つ構造化ログとリクエストID付与の実装方法
    1. JSON形式の構造化ログで可観測性を向上させる
    2. リクエストIDとコンテキスト変数でトレーサビリティを確保する
  8. 本番環境でのログローテーションと例外処理のベストプラクティス
    1. RotatingFileHandlerとTimedRotatingFileHandlerの使い分け
    2. 例外情報を正しくスタックトレース付きで記録する方法
    3. ログレベル運用と不要なDEBUGログを本番で出さない設計
  9. まとめ:Bottleアプリのログ設計で失敗しないためのチェックリスト

Bottleでログ設計が運用を左右する理由とは

Bottleフレームワークでログ設計の重要性を示す開発環境とコードエディタのイメージ

Bottleは単一ファイルで動作するほどの軽量さが最大の魅力です。
しかし、その手軽さゆえにログ設計が後回しにされがちです。
開発初期はprint()で十分に見えても、リクエストが並行し、WSGIサーバー配下で動き始めた瞬間に、運用の可観測性が崩れることがあります。

ログは単なるデバッグ出力ではありません。
本番環境における唯一の事後検証手段です。
特にBottleのようなマイクロフレームワークでは、DjangoやFlaskのような規約によるログ機構が存在しないため、設計の良し悪しが直接運用負荷に跳ね返ってきます。

小規模フレームワークだからこそログが重要になる背景

大規模フレームワークでは、リクエストログやエラーハンドリングがある程度自動で整備されています。
一方でBottleは最小限の機能しか提供しません。
つまり、何を、どの粒度で、どこに出力するかを全て開発者が定義する必要があるのです。

小規模だからログは不要、というのは誤解です。
むしろ以下のような理由から、小規模であるほどログ設計の重要度は増します。

  • middlewareや拡張の機構が少なく、横断的な関心事を自前で実装する必要がある
  • WSGIサーバーであるgunicornやuWSGIとのログの責務分界が曖昧になりやすい
  • 障害時にフレームワーク側の保護が少ないため、アプリケーションログが唯一の手がかりになる

構成がシンプルであるがゆえに、ログという観測点を自ら埋め込まなければ、システムはブラックボックス化してしまいます。

Python標準ライブラリloggingの基本思想をおさらい

この問題を解く鍵は、Python標準ライブラリのloggingが持つ思想に立ち返ることです。
loggingは、ログの発生源・出力先・整形方法を明確に分離する設計になっています。

その中心となるのが3つの要素です。
ログを生成するLogger、出力先を制御するHandler、そして書式を決めるFormatterです。
この分離を理解することが、Bottleにおける正しい連携の第一歩になります。

例えば、アプリケーションの初期化時に一度だけ設定を行うのが原則です。
リクエストを処理する関数の中で毎回設定を行うと、ハンドラが重複登録され二重出力の原因になります。

# app.py の初期化部分で一度だけ設定する
import logging
from logging.config import dictConfig

dictConfig({
    "version": 1,
    "handlers": {
        "app": {"class": "logging.StreamHandler", "formatter": "default"}
    },
    "formatters": {
        "default": {"format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s"}
    },
    "root": {"level": "INFO", "handlers": ["app"]}
})

logger = logging.getLogger(__name__)

このように、設定は集約し、利用は各モジュールでgetLogger(__name__)を通じて行う。
この設定の一元化と利用の分散という原則を守ることで、Bottleのシンプルさを損なわずに、運用に耐えるログ基盤を構築できます。

絶対に避けたいBottleのログ設計アンチパターン5選

Bottleアプリでやってはいけないログ設計の禁止事項を示す警告イメージ

Bottleの開発では、動けば良いという段階から一歩進んで、運用を意識したログ設計が求められます。
ここでは、実務で頻発し、かつ本番環境で致命傷になりかねない5つのアンチパターンを整理します。
いずれも一見すると動作しますが、長期的な保守性を著しく損ないます。

printデバッグの残留と標準出力への直接依存

最も基本的かつ最も危険なのが、print()によるデバッグ出力の残留です。
標準出力はWSGIサーバーやコンテナ環境によって扱いが異なり、ログ収集基盤に取り込まれない、あるいはレベル制御ができないという問題を抱えます。

# アンチパターン: 本番に残ったprintデバッグ
@route('/api/user/')
def get_user(id):
    print(f"get_user called id={id}")  # ログレベルも出力先も制御できない
    return db.find(id)

このような出力は、INFOなのかDEBUGなのか判別できず、障害時のフィルタリングも不可能になります。
全ての出力はlogging経由に統一するのが原則です。

ルートハンドラ内でbasicConfigを呼び出す問題

次に多いのが、各ルートハンドラの中でlogging.basicConfig()を呼び出すパターンです。
basicConfig()はプロセス内で最初の一回のみ有効な設定関数であり、リクエストのたびに呼び出すことでハンドラが重複登録され、ログの二重・三重出力が発生します。

リクエスト数が増えるほどログ量が指数的に増大し、ディスクを圧迫する。
原因が設定の重複にあると気づくまで、かなりの時間を要することになります。
設定はアプリケーションのエントリーポイントで一度だけ行うべきです。

ルートロガーへの直接出力とログレベルの固定化

logging.info()やlogging.error()のように、ルートロガーへ直接出力する方法も避けるべきです。
モジュール名という重要なコンテキストが欠落し、どのコンポーネントからの出力か追跡できなくなります。

  • モジュールごとのログレベル制御ができない
  • ライブラリとアプリケーションのログが混在し、ノイズが増える
  • 出力元がroot固定になり、フィルタリング精度が低下する

正しくはlogging.getLogger(__name__)でモジュール固有のロガーを取得し、そのロガー経由で出力します。
これにより、パッケージ単位でのレベル制御や、出力先の分離が可能になります。

例外を握りつぶすtry-exceptとログ出力の欠落

Bottleでは、例外を握りつぶして200を返してしまう実装が散見されます。
運用上、最も調査を困難にするパターンです。

# アンチパターン: 例外を握りつぶし、ログも残さない
@route('/api/update')
def update():
    try:
        service.update(request.json)
    except Exception:
        return {"status": "error"}  # 何が起きたのか、ログに何も残らない

例外は握りつぶさず、必ずスタックトレースと共に記録するのが鉄則です。
logger.exception()やexc_info=Trueを用いることで、事後検証に必要な情報を残せます。
失敗を隠すことは、可用性を下げる行為に他なりません。

コンテキスト情報なしのログがもたらすデバッグ困難

最後に、コンテキスト情報の欠如です。
User not foundというログだけでは、どのリクエストで、どのユーザーIDで発生したのか分かりません。
並行リクエストが飛び交う本番環境では、ログ同士を紐付けるための識別子が不可欠です。

リクエストID、ユーザーID、処理対象のIDといった付加情報なしのログは、再現不能な事象の原因究明を不可能にします。
次の章以降で解説する構造化ログとコンテキスト付与によって、この問題は解消できます。
ログは点ではなく、線として追えるように設計すべきです。

printデバッグと標準出力依存が招く運用崩壊

本番環境の標準出力に埋もれて発見できないprintデバッグログのイメージ

開発中に手軽なprint()は非常に有用です。
しかし、その手軽さがそのまま本番環境に持ち込まれると、運用全体の可観測性を崩壊させる要因になります。
BottleのようなWSGIアプリケーションでは、標準出力の扱いが実行環境に強く依存するためです。

なぜprintは本番環境で機能しないのか

なぜprint()は本番で機能しないのでしょうか。
理由は、標準出力がログ基盤ではないからです。

gunicornやuWSGIといったWSGIサーバーでは、標準出力はキャプチャされ、ワーカープロセスのログに混在するか、バッファリングにより出力順序が入れ替わることがあります。
DockerやKubernetes環境では、標準出力がコンテナログとして収集されますが、そこにはアクセスログ、サーバーの起動ログ、そしてアプリケーションのprint()が全て混在します。
レベルもタイムスタンプもない大量の文字列から、障害の兆候を見つけ出すのは極めて困難です。

さらに致命的なのは、制御不能である点です。
print()にはログレベルという概念がありません。
DEBUG用途の出力と、本当に通知すべきERRORが同列に扱われます。
本番環境でDEBUG出力を止めたいと思っても、コードを書き換えて再デプロイするしか手段がありません。

観点 print() loggingモジュール
レベル制御 不可、一律出力 DEBUG/INFO/WARNING/ERRORで動的制御可能
出力先制御 標準出力固定 StreamHandler, FileHandler等で分離可能
付加情報 手動で埋め込む必要あり Formatterで時刻やロガー名を自動付与
運用連携 ログ収集基盤でのフィルタ困難 構造化により検索・集計が容易

この表の通り、print()は開発時の一時的な確認には適していますが、運用ログの要件を一つも満たしていません。

loggingへの置き換えで得られるレベル制御と出力先分離

では、loggingへ置き換えることで何が得られるのでしょうか。
最大の利点は、コードを変更せずに振る舞いを変えられる点です。

# 置き換え後: レベルと出力先を制御可能に
import logging

logger = logging.getLogger(__name__)

@route('/api/user/')
def get_user(id):
    logger.debug("get_user called id=%s", id)  # 本番では非表示、開発では表示
    try:
        return db.find(id)
    except NotFound:
        logger.warning("user not found id=%s", id)
        abort(404)

このように書き換えることで、環境変数や設定ファイルでログレベルをINFOにすれば、大量のdebug()は自動的に抑制されます。
コードの再デプロイは不要です。

また、出力先の分離も容易になります。
開発環境ではStreamHandlerでコンソールへ、本番環境ではFileHandlerやStreamHandlerをJSONフォーマットにして標準出力へ出し、ログアグリゲータに渡す。
そういった切り替えが、アプリケーションコードに手を入れることなく実現できます。

print()依存からの脱却は、単なる作法の問題ではありません。
障害発生時に、必要な情報を必要な粒度で即座に取得できるかという、運用の死活問題です。
小さなBottleアプリだからこそ、最初からloggingを正しく使い、将来の自分を助ける設計にしておくべきです。

logging.basicConfig()をルートハンドラで呼ぶ危険性

Bottleのルート関数内でbasicConfigを呼んでしまう危険なコード例のイメージ

Bottleのチュートリアルや断片的なサンプルコードを参考にすると、logging.basicConfig()を各ルートハンドラ内で呼び出している例を見かけることがあります。
手軽にログ設定ができるため一見合理的に見えますが、これは本番環境で深刻な副作用を引き起こす典型的なアンチパターンです。

basicConfig()は、ルートロガーに対してハンドラが一つも存在しない場合にのみ設定を行う、という特殊な挙動を持つ関数です。
つまり、一度設定された後は二回目以降の呼び出しは原則無視されます。
しかし、この仕様を正しく理解せずに使うと、思わぬ挙動を招きます。

basicConfigの多重呼び出しによる二重出力と設定上書き

問題は、開発中にforce=Trueを付けたり、ハンドラを手動でクリアしたりした場合、あるいはテスト実行時に顕著になります。
リクエストのたびにbasicConfig()が呼ばれると、どのような事態が起きるでしょうか。

# アンチパターン: リクエストのたびにbasicConfigを呼ぶ
from bottle import route
import logging

@route('/api/items')
def list_items():
    logging.basicConfig(level=logging.INFO)  # 毎回呼ばれる
    logging.info("list_items called")
    return {"items": []}

開発環境の単一プロセスでは問題が表面化しないかもしれません。
しかし、以下のようなケースで破綻します。

  • テストランナーでforce=Trueを併用すると、リクエストごとにハンドラが追加され、1回のログ出力が2回、3回と重複して記録される
  • basicConfig()にfilenameを指定していると、リクエストごとにファイルがオープンされ、ファイルディスクリプタの枯渇やパフォーマンス劣化を招く
  • 最初に呼ばれたハンドラの設定が残り続け、後からログレベルやフォーマットを変更しようとしても反映されない

特に二重出力は、ログ量を倍増させ、ログ管理サービスのコストを直接押し上げます。
設定はリクエストスコープではなく、プロセススコープで行うという原則がここで問われます。

アプリケーション初期化時に一度だけ設定する正しい方法

では、正しい方法とは何でしょうか。
答えは明確です。
アプリケーションのエントリーポイントで、プロセス起動時に一度だけ設定することです。

Bottleでは、app.pyやwsgi.pyといったアプリケーションを組み立てる場所でログ設定を完結させ、ルート定義のファイルでは設定を一切行わないようにします。

# main.py - エントリーポイントで一度だけ設定
import logging
import bottle

def configure_logging():
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s %(name)s [%(levelname)s] %(message)s",
        force=True  # ここで一度だけ上書きを許可する
    )

def create_app():
    configure_logging()
    app = bottle.Bottle()
    # ルート登録は別モジュールで行う
    import routes
    app.merge(routes.app)
    return app

app = create_app()

この構成により、各ルートハンドラは設定の存在を意識する必要がなくなります。

# routes.py - 設定は行わず、取得して使うだけ
import logging
logger = logging.getLogger(__name__)
from bottle import Bottle

app = Bottle()

@app.route('/api/items')
def list_items():
    logger.info("list_items called")
    return {"items": []}

設定の責務と利用の責務を分離する。
この分離こそが、loggingモジュールが本来意図している使い方です。
初期化時に一度だけ設定し、以降はgetLogger()で取得して使う。
このシンプルな規律を守るだけで、二重出力や設定の競合といった運用上のトラブルの大半は未然に防げます。

BottleとPython標準ライブラリloggingを正しく連携させる基本設計

BottleアプリとPython標準loggingを正しく連携させる設計パターン図

Bottleと標準ライブラリのloggingを正しく連携させるためには、場当たり的な設定をやめ、関心の分離を徹底することが重要です。
設定は集約し、利用は分散する。
この原則を具体的な設計パターンに落とし込んでいきます。

getLogger(name)による階層化とモジュール別ロガー管理

まず、全てのモジュールでlogging.getLogger(__name__)を用いてロガーを取得します。
これは単なる慣習ではありません。
Pythonのロガーがドット区切りで階層構造を持つことを利用した、極めて論理的な設計です。

# project/services/user.py
import logging
logger = logging.getLogger(__name__)  # services.user という名前のロガーが生成される

def find_user(user_id):
    logger.info("find_user user_id=%s", user_id)

このようにすることで、servicesパッケージ配下のログレベルだけをDEBUGに上げる、といった柔軟な制御が可能になります。
ルートロガーに直接出力するlogging.info()では、この粒度での制御は一切できません。
どのモジュールからの出力かを名前に埋め込むことで、フィルタリングとトラブルシュートの効率が格段に向上します。

ハンドラとフォーマッタを分離して再利用性を高める

次に、ハンドラとフォーマッタの分離です。
ロガーはあくまでログを発生させる責務のみを持ち、どこに出力するか、どのような形式で出すかはハンドラとフォーマッタが担います。

例えば、コンソールには人間が読みやすいテキスト形式で、ファイルには機械処理しやすいJSON形式で出力したい場合、ロガーのコードを変更する必要はありません。
ハンドラを二つ用意し、それぞれに異なるフォーマッタを割り当てるだけで実現できます。

  • Logger: ログの発生とレベル判定
  • Handler: 出力先の決定(Stream, File, Syslogなど)
  • Formatter: 出力形式の決定(テキスト、JSONなど)
  • Filter: 付加的なフィルタリング条件

この分離により、Bottleアプリケーション本体のコードはログ出力の詳細から完全に解放されます。
テスト時にはハンドラを差し替えてメモリ上にログを溜める、といった応用も容易になります。

辞書設定dictConfigで実現する宣言的なログ構成

これらの要素を手続き的にaddHandler()で組み立てていくと、設定コードが煩雑になります。
そこで推奨されるのがdictConfigによる宣言的な構成です。

dictConfigは、ログ構成を辞書やYAMLで記述できるため、環境ごとに設定を切り替える運用に非常に適しています。
コードと設定を分離できるのです。

# logging_config.py
LOGGING_CONFIG = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "standard": {"format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s"},
        "json": {"()": "pythonjsonlogger.jsonlogger.JsonFormatter"}
    },
    "handlers": {
        "console": {"class": "logging.StreamHandler", "formatter": "standard", "level": "DEBUG"},
        "file": {"class": "logging.FileHandler", "filename": "app.log", "formatter": "json", "level": "INFO"}
    },
    "loggers": {
        "services": {"level": "DEBUG", "handlers": ["console"], "propagate": False},
    },
    "root": {"level": "INFO", "handlers": ["console", "file"]}
}

この辞書をアプリケーション起動時にlogging.config.dictConfig(LOGGING_CONFIG)で読み込むだけで、全てのロガーが意図通りに動作します。
Bottleのコード内にはbasicConfig()の呼び出しは一切不要になります。
設定ファイルの差し替えだけで、開発環境と本番環境のログ挙動を切り替えられる。
これが、Bottleのシンプルさを保ちつつ、堅牢なログ基盤を実現する最も論理的で再現性の高い方法です。

WSGIサーバーとBottleのログを統合する実践テクニック

gunicornやuWSGIなどWSGIサーバーとBottleのログを統合する構成図

Bottle単体でapp.run()している開発環境と、gunicornやuWSGI配下で動作する本番環境では、ログの流れが全く異なります。
本番環境では、BottleのアプリケーションログとWSGIサーバー自体のアクセスログ、エラーログという3つの流れが混在します。
この3つをどう分離し、どう統合するかが運用性を決めます。

gunicornやuWSGIのアクセスログとアプリログの分離と統合

gunicornを例にすると、gunicornにはgunicorn.errorとgunicorn.accessという2つのロガーが存在します。
Bottleアプリケーション側でbasicConfig()を呼んでルートロガーを上書きしてしまうと、これらのサーバーロガーの設定まで巻き込んでしまい、サーバーの起動ログが意図せず抑制されるといった副作用が起きます。

推奨されるのは、伝播(propagate)を意識した統合です。
アプリケーションのロガーはpropagate=Falseにして独立させるか、あるいはサーバーのエラーロガーに委譲する形を取ります。

# gunicorn_conf.py
import logging

# gunicornのエラーロガーのハンドラを再利用して、Bottleのログも同じ場所に出す
def on_starting(server):
    # アプリ側のロガーがgunicornのハンドラを継承するようにする
    app_logger = logging.getLogger("myapp")
    gunicorn_logger = logging.getLogger("gunicorn.error")
    app_logger.handlers = gunicorn_logger.handlers
    app_logger.setLevel(gunicorn_logger.level)

このようにすることで、Bottleのログもgunicornのエラーログと同じストリーム、同じフォーマットで出力され、コンテナログとして一元的に収集できるようになります。
一方でアクセスログはサーバーに任せ、アプリケーション側ではビジネスロジックに関わるログに専念する。
責務を分離することで、重複と欠落を防げます。

Bottleのhookとミドルウェアで共通ログ処理を実装する

全てのリクエストで共通して行いたいログ処理、例えばリクエストの開始・終了ログや処理時間の計測は、各ルートに散りばめるべきではありません。
Bottleが提供するhook機構とWSGIミドルウェアを活用します。

Bottleのbefore_requestとafter_requestフックは、横断的な関心事を集約するのに最適です。

import time
import logging
from bottle import Bottle, request, response

app = Bottle()
logger = logging.getLogger("myapp.request")

@app.hook('before_request')
def log_request_start():
    request.environ['REQUEST_START_TIME'] = time.time()
    logger.info("request started method=%s path=%s", request.method, request.path)

@app.hook('after_request')
def log_request_end():
    start = request.environ.get('REQUEST_START_TIME', time.time())
    duration = time.time() - start
    logger.info("request finished status=%s duration=%.3f sec", response.status_code, duration)

さらに高度なケースでは、WSGIミドルウェアでリクエストIDの付与や例外の捕捉を行います。
ミドルウェア層で例外を捕捉し、ログ出力してから再送出することで、Bottleのルートハンドラ側では純粋なビジネスロジックに集中できます。

このように、サーバーログとの統合は設定の共有で、アプリケーション内の共通処理はフックとミドルウェアで実装する。
この二層構造を意識することで、Bottleの軽量さを保ったまま、本番環境でも破綻しないログ基盤が構築できます。

運用で役立つ構造化ログとリクエストID付与の実装方法

リクエストID付きの構造化ログがJSON形式で出力されている運用画面イメージ

ログがテキストの羅列である限り、運用での活用には限界があります。
grepで検索することはできても、特定のユーザーの一連の操作を追跡したり、処理時間を集計したりすることは困難です。
そこで必要になるのが、構造化ログとリクエストIDによるトレーサビリティの確保です。

JSON形式の構造化ログで可観測性を向上させる

構造化ログとは、ログを単なる文字列ではなく、機械的に解析可能なJSONなどの形式で出力する手法です。
これにより、ログ管理基盤であるDatadogやCloudWatch Logs、Elasticsearchでの検索・集計が飛躍的に容易になります。

Pythonでは、フォーマッタを差し替えるだけで実現できます。
テキストフォーマットとJSONフォーマットを、コード変更なしに切り替えられるのがloggingの強みです。

# 構造化ログ用のカスタムフォーマッタの適用例
import json
import logging

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "timestamp": self.formatTime(record),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "request_id": getattr(record, "request_id", "-"),
        }
        return json.dumps(log_obj, ensure_ascii=False)

handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logging.getLogger("myapp").addHandler(handler)

このように出力されれば、level=ERRORかつrequest_id=xxxといったクエリで、障害の関連ログを即座に抽出できます。
可観測性とは、ログを検索可能にすることに他なりません。

リクエストIDとコンテキスト変数でトレーサビリティを確保する

構造化しても、並行するリクエストのログが混在しては追跡できません。
そこで、全てのリクエストに一意なIDを付与し、全てのログにそのIDを自動的に含める仕組みが必要です。

Python 3.7以降で導入されたcontextvarsは、この用途に最適です。
スレッドローカルではなく、コンテキストごとに値を保持できるため、非同期環境でも安全にリクエストIDを伝播できます。

import uuid
import contextvars
from bottle import request
import logging

request_id_var = contextvars.ContextVar("request_id", default="-")

class RequestIdFilter(logging.Filter):
    def filter(self, record):
        record.request_id = request_id_var.get()
        return True

# BottleのフックでリクエストIDを設定
def setup_request_id():
    rid = request.headers.get("X-Request-ID") or str(uuid.uuid4())[:8]
    request_id_var.set(rid)

# 利用側
# app.add_hook('before_request', setup_request_id) のように登録する
# ロガーには上記のFilterを追加しておく

logger = logging.getLogger("myapp")
logger.addFilter(RequestIdFilter())
logger.info("user lookup started user_id=%s", 123)

この実装により、user lookup startedというログにも、自動的にrequest_idが付与されます。
開発者はログ出力時にIDを意識する必要がありません。
フィルタが透過的に付与してくれます。

  • リクエストIDにより、1リクエストに紐づく全ログを時系列で追跡可能になる
  • フロントエンドから渡されたX-Request-IDを引き継ぐことで、マイクロサービス間の横断的なトレースも実現できる
  • contextvarsを用いることで、Bottleの同期処理だけでなく、将来的な非同期化にも対応できる

ログにコンテキストを持たせる。
この一手間が、再現不能と諦めていた障害を、再現可能な事象へと変えてくれます。
運用で役立つログとは、単に記録されているログではなく、追跡できるログのことです。

本番環境でのログローテーションと例外処理のベストプラクティス

本番環境でログローテーションと例外ログを適切に管理するサーバー運用イメージ

ログ設計の最終段階は、本番環境での持続可能性です。
ログは出力して終わりではありません。
ディスク容量を圧迫せず、障害時に必要な情報を確実に残すための運用設計が不可欠です。
ここではローテーションと例外処理、そしてレベル運用の3点からベストプラクティスを解説します。

RotatingFileHandlerとTimedRotatingFileHandlerの使い分け

ファイルへのログ出力を本番で行う場合、無限に肥大化するログファイルは必ず障害を引き起こします。
そこで標準ライブラリが提供するローテーションハンドラを使い分けます。

2つのハンドラの特性は明確に異なります。

ハンドラ ローテーション基準 適した用途
RotatingFileHandler ファイルサイズ 1ファイルあたりのサイズを厳密に制限したい場合
TimedRotatingFileHandler 時間 日次や時間単位でログを分離し、保管したい場合

多くのWebアプリケーションでは、日付で管理できるTimedRotatingFileHandlerが扱いやすいでしょう。

import logging
from logging.handlers import TimedRotatingFileHandler

handler = TimedRotatingFileHandler(
    filename="app.log",
    when="midnight",
    backupCount=30,  # 30日分保持
    encoding="utf-8"
)
handler.setFormatter(logging.Formatter("%(asctime)s %(name)s [%(levelname)s] %(message)s"))
logger = logging.getLogger("myapp")
logger.addHandler(handler)

ただし、コンテナ環境ではファイルではなく標準出力にJSONを流し、ローテーションはログ基盤側に任せるのが現在の主流です。
環境に応じてアプリケーション側でローテーションするか、基盤側に委譲するかを明確に選択することが重要です。

例外情報を正しくスタックトレース付きで記録する方法

例外発生時にlogger.error(str(e))のように文字列化してしまうのは、最も避けたいアンチパターンです。
スタックトレースという最も重要な情報が失われます。

正しくはlogger.exception()を用います。
このメソッドはERRORレベルで出力しつつ、現在の例外情報を自動的に付与してくれます。

import logging
logger = logging.getLogger(__name__)

@route('/api/update')
def update():
    try:
        service.update(request.json)
    except Exception:
        # スタックトレース付きで記録し、クライアントには汎用的なエラーを返す
        logger.exception("failed to update resource")
        abort(500, "internal server error")

logger.error("... ", exc_info=True)と書いても同等の効果が得られますが、exceptブロック内ではexception()の方が意図が明確です。
例外は握りつぶさず、必ずスタックトレースと共に残す。
この原則が、障害原因の特定時間を数時間から数分へと短縮します。

ログレベル運用と不要なDEBUGログを本番で出さない設計

最後に、ログレベルの運用設計です。
本番環境でDEBUGログを常時出力することは、パフォーマンス低下とコスト増大を招きます。
一方で、障害時には一時的にDEBUGを出したいという要望もあります。

このジレンマを解決するのが、環境変数によるレベル制御と、ロガーごとの粒度設定です。

  • ルートロガーはINFOに設定し、全体のノイズを抑制する
  • 問題が発生している特定のパッケージのみ、環境変数でDEBUGに上げる
  • getLogger(__name__)による階層化を活かし、services.paymentだけを詳細化するといった運用を可能にする
import os
import logging

# 環境変数 LOG_LEVEL_SERVICES=DEBUG のようにパッケージごとに制御可能にする
level = os.getenv("LOG_LEVEL", "INFO")
logging.getLogger("myapp").setLevel(level)

コードの変更や再デプロイなしに、ログの詳細度を動的に制御できる。
これがloggingモジュールを使う最大の運用上の利点です。
本番ではINFO以上をデフォルトとし、必要な時だけ必要な箇所をDEBUGにする。
この規律を徹底することで、ログはノイズではなく、シグナルとして機能します。

まとめ:Bottleアプリのログ設計で失敗しないためのチェックリスト

Bottleアプリのログ設計チェックリストとベストプラクティスがまとまった要約イメージ

本記事では、Bottleアプリケーションにおけるログ設計のアンチパターンと、Python標準ライブラリloggingとの正しい連携方法を解説してきました。
Bottleは軽量であるがゆえに、ログに関する規約をフレームワーク側が提供してくれません。
だからこそ、開発者自身が論理的で再現性のある設計を持つ必要があります。

最後に、本番投入前に必ず確認すべきチェックリストとして、本記事の要点を整理します。
このチェックリストを満たすことで、運用時のトラブルシュート時間を大幅に短縮できます。

まず、アンチパターンの排除から確認します。

  • print()によるデバッグ出力がコード内に残留していないか。全てlogger.debug()等に置き換わっているか
  • ルートハンドラ内でbasicConfig()を呼び出していないか。設定はアプリケーションのエントリーポイントで一度だけ行われているか
  • logging.info()のようなルートロガーへの直接出力をしていないか。全てのモジュールでgetLogger(__name__)を用いているか
  • exceptブロックで例外を握りつぶしていないか。必ずlogger.exception()でスタックトレースを記録しているか
  • コンテキスト情報なしのログを出力していないか。リクエストIDやユーザーIDが紐付け可能になっているか

次に、正しい設計パターンが実装されているかを確認します。

  • 設定と利用が分離されているか。dictConfig等で宣言的に設定を記述し、コード内では取得して使うだけになっているか
  • ハンドラとフォーマッタが分離され、環境ごとに切り替え可能になっているか。開発環境ではテキスト、本番ではJSONといった切り替えがコード変更なしに可能か
  • WSGIサーバーであるgunicornやuWSGIのログと、アプリケーションログの責務分界が明確か。ハンドラの共有やpropagateの制御が適切に行われているか
  • 共通ログ処理がhookやミドルウェアに集約されているか。各ルートに重複したログ出力コードが散在していないか

そして、運用面での持続可能性も重要です。

  • ログローテーションの戦略が決まっているか。TimedRotatingFileHandlerでファイル管理をするのか、標準出力に流して基盤側に委譲するのか、環境に応じた選択がなされているか
  • ログレベルの運用ルールが定義されているか。本番ではINFO以上をデフォルトとし、環境変数で特定パッケージのみDEBUGに上げられる設計になっているか
  • 構造化ログが導入され、ログ管理基盤で検索・集計可能になっているか。request_idが全てのログに付与され、一連のリクエストをトレースできるか

Bottleの魅力は、そのシンプルさにあります。
そのシンプルさを維持したまま運用性を高める鍵が、標準ライブラリの思想を正しく理解し、設定の一元化と利用の分散、出力と付加情報の分離という原則を徹底することです。

ログ設計は、障害が起きてからでは遅いのです。
動いている今のうちに、本記事で紹介したアンチパターンを排除し、チェックリストに沿った堅牢な基盤を構築しておくことが、将来の自分自身とチームを助ける最も確実な投資になります。
ぜひ、ご自身のBottleアプリケーションのログ設計を見直すきっかけとしてください。

コメント

タイトルとURLをコピーしました