はじめに：なぜロギングが重要なのか？ 🤔
ソフトウェア開発において、プログラムが期待通りに動作しているかを確認したり、問題が発生した際に原因を特定したりすることは非常に重要です。多くの開発者がデバッグ目的で print() 関数を使用しますが、これは小規模なスクリプトでは手軽なものの、本格的なアプリケーション開発においてはいくつかの制限があります。
- 出力先を柔軟に指定できない（例：コンソールだけでなくファイルや外部サービスにも送りたい）
- ログの重要度（レベル）を管理できない
- ログメッセージのフォーマットを統一しにくい
- 本番環境で不要なデバッグメッセージだけを簡単に抑制できない
これらの課題を解決するのが、Pythonの標準ライブラリである logging モジュールです。logging モジュールを使えば、柔軟かつ強力なログ出力システムを構築でき、アプリケーションの運用・保守性を大幅に向上させることができます。🔧
この記事では、logging モジュールの基本的な使い方から、ロガー、ハンドラ、フォーマッタ、フィルタといった主要コンポーネントの解説、そして設定ファイルを使った高度な設定方法やベストプラクティスまで、幅広く徹底的に解説していきます。この記事を読めば、あなたも logging マスターになれるはずです！ 😉
基本の「き」：簡単なログ出力とbasicConfig ⚙️
まずは、logging モジュールの最も基本的な使い方を見ていきましょう。
loggingモジュールのインポート
何はともあれ、logging モジュールをインポートします。
import loggingログレベルについて
logging モジュールでは、ログメッセージの重要度を示す「ログレベル」が定義されています。これにより、開発中は詳細な情報を出力し、本番環境では重要なエラーのみを出力するといった制御が可能になります。主なログレベルは以下の通りです（重要度の低い順）。
| レベル | 数値 | 用途 | 出力メソッド |
|---|---|---|---|
| DEBUG | 10 | 開発中のデバッグ情報。問題の診断時に役立つ詳細情報。 | logging.debug() |
| INFO | 20 | 情報メッセージ。プログラムが正常に動作していることの確認。 | logging.info() |
| WARNING | 30 | 警告メッセージ。予期しないことが発生した、または将来問題が発生する可能性があることを示唆（例：ディスク容量不足）。デフォルトのログレベル。 | logging.warning() |
| ERROR | 40 | エラーメッセージ。重大な問題により、プログラムの一部機能が実行できなかったことを示す。 | logging.error() |
| CRITICAL | 50 | 重大なエラーメッセージ。プログラム自体が実行を継続できない可能性があることを示す。 | logging.critical() |
デフォルトのログレベルは WARNING です。つまり、設定を変更しない限り、WARNING, ERROR, CRITICAL レベルのログのみが出力されます。
basicConfigによる簡単設定
logging.basicConfig() 関数を使うと、簡単なログ設定を手軽に行えます。主な設定項目は以下の通りです。
level: 出力するログの最低レベルを指定します (例:logging.INFO)。指定されたレベル以上のログが出力されます。format: ログメッセージの出力フォーマットを指定する文字列。後述するフォーマット文字列を使用できます。filename: ログの出力先ファイル名を指定します。指定しない場合はコンソール (標準エラー出力) に出力されます。filemode:filenameを指定した場合のファイル書き込みモード (デフォルトは'a': 追記)。datefmt:formatで%(asctime)sを使用した場合の日時フォーマットを指定します (例:'%Y-%m-%d %H:%M:%S')。
注意点： basicConfig() は、ログ出力メソッド (debug(), info() など) が最初に呼び出される前に設定する必要があります。また、一度設定すると、再度呼び出しても設定は変更されません（ただし、Jupyter Notebookなどインタラクティブな環境では挙動が異なる場合があります）。通常はスクリプトの最初の方で一度だけ呼び出します。
簡単なログ出力例
実際にログを出力してみましょう。ここでは、ログレベルを INFO に設定し、フォーマットを指定してコンソールに出力します。
import logging
# basicConfig で基本的な設定を行う (INFOレベル以上を出力、フォーマット指定)
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
# 各レベルでログを出力
logging.debug('これはデバッグ情報です。 (表示されないはず)') # level=INFO なので DEBUG は表示されない
logging.info('これは情報メッセージです。')
logging.warning('これは警告メッセージです。')
logging.error('これはエラーメッセージです。')
logging.critical('これは重大なエラーメッセージです。')
# 変数を埋め込むことも可能
user_id = 12345
logging.info(f'ユーザー {user_id} がログインしました。')これを実行すると、以下のような出力が得られます（日時は実行時に依存）。
2025-04-05 08:05:00,123 - INFO - これは情報メッセージです。
2025-04-05 08:05:00,123 - WARNING - これは警告メッセージです。
2025-04-05 08:05:00,123 - ERROR - これはエラーメッセージです。
2025-04-05 08:05:00,123 - CRITICAL - これは重大なエラーメッセージです。
2025-04-05 08:05:00,123 - INFO - ユーザー 12345 がログインしました。
basicConfig() は手軽ですが、より複雑な設定（複数の出力先、モジュールごとの設定など）を行いたい場合は、次に説明するロガー、ハンドラ、フォーマッタを直接操作する方法や、設定ファイルを使う方法が適しています。
主要コンポーネント：ロガー、ハンドラ、フォーマッタ、フィルタ 🧩
logging モジュールは、以下の主要なコンポーネントから構成されています。これらを組み合わせることで、柔軟なロギングシステムを構築できます。
- ロガー (Logger): アプリケーションコードが直接やり取りするインターフェース。ログメッセージを生成します。
- ハンドラ (Handler): ロガーから受け取ったログレコードを、適切な出力先 (コンソール、ファイル、ネットワークなど) に送信します。
- フォーマッタ (Formatter): ログレコードの最終的な出力形式 (レイアウト) を指定します。
- フィルタ (Filter): どのログレコードを出力するかを、ログレベルよりもさらに細かく制御します。
ログメッセージが生成されてから出力されるまでの流れは、大まかに以下のようになります。
- アプリケーションコードが特定のロガーに対してログ出力メソッド (
info(),error()など) を呼び出す。 - ロガーが、指定されたメッセージとレベルでログレコードを作成する。
- ロガーに設定されたフィルタで、このログレコードを処理すべきか判断する。
- 処理すべきと判断された場合、ロガーに設定された各ハンドラにログレコードを渡す。
- ハンドラでも、自身のレベルやフィルタでログレコードを処理すべきか判断する。
- 処理すべきと判断された場合、ハンドラに設定されたフォーマッタを使ってログレコードを文字列に変換する。
- ハンドラが、フォーマットされた文字列を最終的な出力先 (コンソール、ファイルなど) に書き出す。
- (設定によっては) ログレコードが親ロガーに伝播される。
ロガー (Logger)
ロガーは、ログメッセージを発行するための主要なインターフェースです。ロガーは階層構造を持っており、ドット (.) 区切りで名前が付けられます (例: 'myapp', 'myapp.network', 'myapp.db')。
logging.getLogger(name) 関数でロガーインスタンスを取得します。
- 引数
nameにロガー名を指定します。通常、モジュールレベルのロガーを作成する際には__name__(現在のモジュール名) を指定するのが一般的です。これにより、自然な階層構造が形成されます。 - 引数を省略するか
Noneを指定すると、ルートロガー (root logger) を取得します。basicConfig()は、このルートロガーを設定します。 - 同じ名前で
getLogger()を呼び出すと、常に同じロガーインスタンスが返されます。
import logging
# モジュールレベルのロガーを取得 (推奨)
logger = logging.getLogger(__name__)
# 特定の名前のロガーを取得
network_logger = logging.getLogger('myapp.network')
# ルートロガーを取得 (通常は直接使わない)
root_logger = logging.getLogger()
各ロガーは独自のログレベル (logger.setLevel(level)) を持つことができます。ロガーに渡されたメッセージのレベルが、ロガー自身のレベルよりも低い場合、そのメッセージは無視されます。
ロガーには伝播 (propagate) という性質があります。デフォルトでは、あるロガーで処理されたログレコードは、その親ロガーにも伝播されます (階層を上っていく)。ルートロガーまで伝播は続きます。logger.propagate = False と設定することで、伝播を止めることができます。ライブラリ開発時など、アプリケーション側のロギング設定に影響を与えたくない場合に利用されます。
ハンドラ (Handler)
ハンドラは、ログレコードをどこに出力するかを決定します。logging モジュールや logging.handlers モジュールには、様々な種類のハンドラが用意されています。
StreamHandler: ログをストリーム (通常はsys.stdoutまたはsys.stderr) に出力します。basicConfig()でファイル名を指定しない場合のデフォルトです。FileHandler: ログをファイルに出力します。RotatingFileHandler: ログファイルが指定したサイズに達したら、ローテーション (古いログを別名で保存し、新しいファイルに書き込み開始) を行います。TimedRotatingFileHandler: 時間間隔 (日、時、分など) に基づいてログファイルをローテーションします。NullHandler: 何も出力しません。ライブラリ開発時に、デフォルトのハンドラとして設定し、「ハンドラが見つからない」という警告を防ぐためによく使われます。- その他、
HTTPHandler,SMTPHandler,SysLogHandlerなど、多様な出力先に対応するハンドラがあります。
ハンドラも独自のログレベル (handler.setLevel(level)) を持つことができます。ロガーから渡されたログレコードのレベルが、ハンドラのレベルよりも低い場合、そのハンドラでは処理されません。
ロガーには logger.addHandler(handler) メソッドでハンドラを追加できます。一つのロガーに複数のハンドラを追加することも可能です（例：コンソールとファイルの両方に出力）。
import logging
import sys
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG) # ロガーのレベルはDEBUG
# コンソール出力用ハンドラ (INFOレベル以上)
console_handler = logging.StreamHandler(sys.stdout)
console_handler.setLevel(logging.INFO)
# ファイル出力用ハンドラ (DEBUGレベル以上)
file_handler = logging.FileHandler('app.log', mode='w') # 'w'モードで新規作成
file_handler.setLevel(logging.DEBUG)
# ロガーにハンドラを追加
logger.addHandler(console_handler)
logger.addHandler(file_handler)
logger.debug('これはデバッグメッセージ (ファイルのみに出力)')
logger.info('これは情報メッセージ (コンソールとファイルに出力)')フォーマッタ (Formatter)
フォーマッタは、ログレコードを人間が読める文字列に変換する方法を定義します。logging.Formatter クラスを使用します。
コンストラクタの第一引数 fmt にフォーマット文字列を、第二引数 datefmt に日時のフォーマットを指定します。
フォーマット文字列 (fmt) では、%()s 形式のプレースホルダを使って、ログレコードの様々な属性を埋め込むことができます。よく使われる属性には以下のようなものがあります。
| 属性名 | フォーマット | 説明 |
|---|---|---|
asctime | %(asctime)s | ログレコードが作成された日時 (人間が読める形式) |
created | %(created)f | ログレコードが作成された時刻 (time.time() の返すエポック秒) |
filename | %(filename)s | ログ呼び出しが行われたソースファイル名 |
funcName | %(funcName)s | ログ呼び出しが行われた関数名 |
levelname | %(levelname)s | ログレベルのテキスト名 (‘DEBUG’, ‘INFO’ など) |
levelno | %(levelno)s | ログレベルの数値 (10, 20 など) |
lineno | %(lineno)d | ログ呼び出しが行われた行番号 |
message | %(message)s | ログメッセージ本体 (logger.info("ここ") の部分) |
module | %(module)s | ログ呼び出しが行われたモジュール名 (ファイル名の拡張子なし) |
msecs | %(msecs)d | ログレコード作成時刻のミリ秒部分 |
name | %(name)s | ロガー名 |
pathname | %(pathname)s | ログ呼び出しが行われたソースファイルのフルパス |
process | %(process)d | プロセスID (利用可能な場合) |
processName | %(processName)s | プロセス名 (利用可能な場合) |
relativeCreated | %(relativeCreated)d | loggingモジュールがロードされてからの経過時間 (ミリ秒) |
thread | %(thread)d | スレッドID (利用可能な場合) |
threadName | %(threadName)s | スレッド名 (利用可能な場合) |
作成したフォーマッタは、handler.setFormatter(formatter) メソッドでハンドラに設定します。
import logging
import sys
# フォーマッタを作成
log_format = '%(asctime)s - %(name)s - %(levelname)s - [%(filename)s:%(lineno)d] - %(message)s'
date_format = '%Y-%m-%d %H:%M:%S'
formatter = logging.Formatter(fmt=log_format, datefmt=date_format)
# ハンドラを作成し、フォーマッタを設定
console_handler = logging.StreamHandler(sys.stdout)
console_handler.setFormatter(formatter)
# ロガーを取得し、ハンドラを追加
logger = logging.getLogger('myapp.ui')
logger.setLevel(logging.INFO)
logger.addHandler(console_handler)
logger.info('ユーザーインターフェースを初期化しました。')実行結果例:
2025-04-05 08:05:00 - myapp.ui - INFO - [example.py:20] - ユーザーインターフェースを初期化しました。フィルタ (Filter)
フィルタを使うと、ログレベルだけでは実現できない、より複雑な条件でログレコードをフィルタリングできます。logging.Filter クラスを継承して独自のフィルタを作成するか、単純な名前ベースのフィルタリングなら logging.Filter(name='...') のようにインスタンス化します。
カスタムフィルタを作成する場合、filter(record) メソッドをオーバーライドします。このメソッドはログレコードを引数に取り、そのレコードを処理すべきなら真 (非ゼロ値)、処理すべきでないなら偽 (0) を返します。
作成したフィルタは、ロガー (logger.addFilter(filter)) またはハンドラ (handler.addFilter(filter)) に追加できます。
import logging
import sys
# 特定のロガー名からのログのみを許可するフィルタ
class SpecificLoggerFilter(logging.Filter):
def __init__(self, allowed_logger_name):
super().__init__()
self.allowed_logger_name = allowed_logger_name
def filter(self, record):
# record.name が許可されたロガー名で始まる場合のみ True を返す
return record.name.startswith(self.allowed_logger_name)
# ロガーとハンドラ、フォーマッタの設定 (省略)
formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(formatter)
# フィルタを作成し、ハンドラに追加
# 'myapp.network' で始まるロガーからのログのみを許可
network_filter = SpecificLoggerFilter('myapp.network')
handler.addFilter(network_filter)
# ロガーを取得 (ルートロガーを使用)
root_logger = logging.getLogger()
root_logger.setLevel(logging.INFO)
root_logger.addHandler(handler)
# 異なるロガーからログを出力
logger_network = logging.getLogger('myapp.network.client')
logger_db = logging.getLogger('myapp.db')
logger_ui = logging.getLogger('myapp.ui')
logger_network.warning('ネットワーク接続に時間がかかっています。') # 表示される
logger_db.info('データベースに接続しました。') # 表示されない
logger_ui.error('UIの描画に失敗しました。') # 表示されない
実行結果例:
myapp.network.client - WARNING - ネットワーク接続に時間がかかっています。設定方法：コード vs 設定ファイル 📝
ロギングの設定方法は、主に3つあります。
basicConfig()を使う (簡単な設定向け)- Pythonコード内でロガー、ハンドラ、フォーマッタ、フィルタを直接作成・設定する
- 設定ファイル (ini形式または辞書形式) を使い、
logging.configモジュールの関数で読み込む
basicConfig() は手軽ですが、機能が限られます。コード内で直接設定する方法は柔軟ですが、設定がコード内に散らばりやすく、変更が大変になることがあります。
より複雑なアプリケーションや、設定をコードから分離したい場合には、設定ファイルを使う方法が推奨されます。設定ファイルには、古い形式の fileConfig() (iniファイル) と、より新しく推奨される dictConfig() (辞書) があります。
コードによる設定
これは前のセクションで見てきた方法です。ロガー、ハンドラ、フォーマッタ、フィルタのオブジェクトを直接生成し、setLevel(), addHandler(), setFormatter(), addFilter() などのメソッドを使って関連付けます。
Pro: 設定を完全にプログラムで制御できます。
Con: 設定を変更するにはコードの修正が必要です。設定が複雑になるとコードが長くなりがちです。
import logging
import sys
def setup_logging_programmatically():
# ロガー取得
logger = logging.getLogger('my_app')
logger.setLevel(logging.DEBUG)
# フォーマッタ作成
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
# コンソールハンドラ作成と設定
console_handler = logging.StreamHandler(sys.stdout)
console_handler.setLevel(logging.INFO)
console_handler.setFormatter(formatter)
# ファイルハンドラ作成と設定
file_handler = logging.FileHandler('my_app.log', mode='a')
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(formatter)
# ロガーにハンドラを追加
logger.addHandler(console_handler)
logger.addHandler(file_handler)
return logger
# 設定を実行してロガーを取得
app_logger = setup_logging_programmatically()
# ログ出力
app_logger.debug('これはデバッグログ (ファイルのみ)')
app_logger.info('これは情報ログ (コンソールとファイル)')
app_logger.warning('これは警告ログ (コンソールとファイル)')設定ファイル：fileConfig (ini形式)
logging.config.fileConfig() 関数は、Windowsのiniファイルに似た形式の設定ファイルを読み込みます。この形式は古く、dictConfig ほど柔軟ではないため、現在ではあまり推奨されません。
Pro: 設定をコードから分離できます。
Con: dictConfig より機能が少なく、柔軟性に欠けます (例: カスタムフィルタの設定が難しい)。将来的な拡張は dictConfig に対して行われる予定です。キーワード引数でのハンドラ設定ができないなどの制限もあります。
設定ファイル (例: logging.ini) の例:
[loggers]
keys=root,moduleA
[handlers]
keys=consoleHandler,fileHandler
[formatters]
keys=simpleFormatter
[logger_root]
level=WARNING
handlers=consoleHandler
[logger_moduleA]
level=DEBUG
handlers=consoleHandler,fileHandler
qualname=moduleA
propagate=0
[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stdout,)
[handler_fileHandler]
class=FileHandler
level=DEBUG
formatter=simpleFormatter
args=('app.log', 'a')
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=%Y-%m-%d %H:%M:%SPythonコード側:
import logging
import logging.config
# 設定ファイルを読み込む
logging.config.fileConfig('logging.ini')
# ロガーを取得して使用
logger = logging.getLogger('moduleA')
logger.debug('fileConfigからのデバッグメッセージ')設定ファイル：dictConfig (辞書形式) – 推奨 ✅
logging.config.dictConfig() 関数は、Pythonの辞書オブジェクトを使ってロギング設定を行います。この方法は非常に柔軟で強力であり、現在最も推奨される設定方法です。設定辞書は、コード内で直接定義することも、JSONやYAMLなどのファイルから読み込むこともできます。
Pro: 非常に柔軟で強力。設定をコードから完全に分離可能 (JSON/YAML)。カスタムオブジェクト (フィルタ、ハンドラなど) の設定も容易。Python 3.2以降で利用可能。
Con: 設定ファイルの構造を理解する必要がある。
設定辞書の基本的な構造:
version: スキーマバージョン。現在は1を指定します (必須)。formatters: フォーマッタIDと設定辞書の辞書。handlers: ハンドラIDと設定辞書の辞書。loggers: ロガー名と設定辞書の辞書。ルートロガーはキー'root'で設定します。disable_existing_loggers: (オプション)Trueにすると、設定時に存在する既存のロガー (ライブラリなどが作成したものも含む) を無効にします。デフォルトはTrueなので、意図しないロガーが無効にならないようFalseに設定することが多いです。
設定辞書 (コード内定義) の例:
import logging
import logging.config
import sys
LOGGING_CONFIG = {
'version': 1,
'disable_existing_loggers': False, # 既存のロガーを無効にしない
'formatters': {
'detailed': {
'format': '%(asctime)s - %(name)s:%(lineno)d - %(levelname)s - %(message)s',
'datefmt': '%Y-%m-%d %H:%M:%S',
},
'simple': {
'format': '%(levelname)s: %(message)s',
},
},
'handlers': {
'console': {
'class': 'logging.StreamHandler',
'level': 'INFO',
'formatter': 'simple',
'stream': sys.stdout, # 標準出力へ
},
'file': {
'class': 'logging.handlers.RotatingFileHandler',
'level': 'DEBUG',
'formatter': 'detailed',
'filename': 'app_dict.log',
'maxBytes': 1048576, # 1MB
'backupCount': 3,
'encoding': 'utf-8',
},
},
'loggers': {
'my_app': { # 'my_app' という名前のロガー設定
'handlers': ['console', 'file'],
'level': 'DEBUG',
'propagate': False, # ルートロガーへの伝播を止める
},
'my_app.network': { # 'my_app.network' ロガー設定
'handlers': ['file'], # ファイルにのみ出力
'level': 'INFO',
'propagate': False,
},
# 他のライブラリ (例: requests) のログレベルを抑制する場合
'requests': {
'handlers': ['console'],
'level': 'WARNING', # WARNING以上のみ出力
'propagate': False,
},
},
'root': { # ルートロガーの設定
'handlers': ['console'],
'level': 'WARNING',
},
}
# 辞書設定を適用
logging.config.dictConfig(LOGGING_CONFIG)
# ロガーを取得して使用
app_logger = logging.getLogger('my_app')
network_logger = logging.getLogger('my_app.network')
root_logger = logging.getLogger() # ルートロガー
app_logger.debug('dictConfigからのデバッグメッセージ (ファイルのみ)')
app_logger.info('dictConfigからの情報メッセージ (コンソールとファイル)')
network_logger.info('ネットワーク関連の情報 (ファイルのみ)')
root_logger.warning('ルートロガーからの警告 (コンソールのみ)')
この辞書をJSONファイル (例: logging_config.json) やYAMLファイル (例: logging_config.yaml) に記述し、それを読み込んで dictConfig() に渡すことも一般的です。
JSONファイル (logging_config.json) の例:
{
"version": 1,
"disable_existing_loggers": false,
"formatters": {
"detailed": {
"format": "%(asctime)s - %(name)s:%(lineno)d - %(levelname)s - %(message)s",
"datefmt": "%Y-%m-%d %H:%M:%S"
},
"simple": {
"format": "%(levelname)s: %(message)s"
}
},
"handlers": {
"console": {
"class": "logging.StreamHandler",
"level": "INFO",
"formatter": "simple",
"stream": "ext://sys.stdout"
},
"file": {
"class": "logging.handlers.RotatingFileHandler",
"level": "DEBUG",
"formatter": "detailed",
"filename": "app_dict.log",
"maxBytes": 1048576,
"backupCount": 3,
"encoding": "utf-8"
}
},
"loggers": {
"my_app": {
"handlers": ["console", "file"],
"level": "DEBUG",
"propagate": false
}
},
"root": {
"handlers": ["console"],
"level": "WARNING"
}
}Pythonコード側 (JSON読み込み):
import logging
import logging.config
import json
# JSONファイルを読み込む
with open('logging_config.json', 'r') as f:
config_dict = json.load(f)
# 辞書設定を適用
logging.config.dictConfig(config_dict)
# ロガーを取得して使用
logger = logging.getLogger('my_app')
logger.info('JSON設定ファイルから読み込みました！')
YAMLを使う場合は、PyYAML ライブラリなどを利用してYAMLファイルを辞書に変換してから dictConfig() に渡します。dictConfig は非常に強力で、アプリケーションの設定を柔軟に管理するためのデファクトスタンダードと言えるでしょう。
応用テクニック 💡
例外情報のロギング
エラーハンドリング (try...except) 中に例外が発生した場合、その詳細情報 (トレースバック) をログに残したいことがよくあります。これには2つの方法があります。
- ログ出力メソッド (
error(),exception()など) のexc_info=True引数を使用する。 logging.exception()メソッドを使用する。これはlogging.error(..., exc_info=True)と同等です。
import logging
logging.basicConfig(level=logging.ERROR, format='%(asctime)s - %(levelname)s - %(message)s')
try:
result = 10 / 0
except ZeroDivisionError:
# 方法1: errorメソッドで exc_info=True を指定
logging.error("ゼロ除算エラーが発生しました。", exc_info=True)
# 方法2: exceptionメソッドを使用 (ERRORレベルで出力される)
logging.exception("別の方法でゼロ除算エラーを記録。")
# --- 実行結果例 (トレースバック情報が含まれる) ---
# 2025-04-05 08:05:00,123 - ERROR - ゼロ除算エラーが発生しました。
# Traceback (most recent call last):
# File "example.py", line 7, in <module>
# result = 10 / 0
# ZeroDivisionError: division by zero
# 2025-04-05 08:05:00,123 - ERROR - 別の方法でゼロ除算エラーを記録。
# Traceback (most recent call last):
# File "example.py", line 7, in <module>
# result = 10 / 0
# ZeroDivisionError: division by zeroスタック情報のロギング
現在のコールスタック情報をログに追加したい場合は、ログ出力メソッドの stack_info=True 引数を使用します。これは例外が発生していなくても、どの関数呼び出しを経てそのログが出力されたかを知りたい場合に役立ちます。
import logging
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
def function_a():
logging.debug("Function A 内のログ", stack_info=True)
function_b()
def function_b():
logging.info("Function B 内のログ", stack_info=True)
function_a()
# --- 実行結果例 (スタック情報が含まれる) ---
# 2025-04-05 08:05:00,123 - DEBUG - Function A 内のログ
# Stack (most recent call last):
# File "example.py", line 13, in
# function_a()
# File "example.py", line 6, in function_a
# logging.debug("Function A 内のログ", stack_info=True)
# 2025-04-05 08:05:00,123 - INFO - Function B 内のログ
# Stack (most recent call last):
# File "example.py", line 13, in
# function_a()
# File "example.py", line 7, in function_a
# function_b()
# File "example.py", line 10, in function_b
# logging.info("Function B 内のログ", stack_info=True) 非同期処理 (asyncio) との連携
asyncio を使用した非同期アプリケーションでも logging は利用できます。ただし、ログ処理自体がブロッキング操作 (特にファイルI/Oなど) を含む場合、イベントループ全体のパフォーマンスに影響を与える可能性があります。
対策としては、以下のような方法が考えられます。
- ログ処理を別スレッドや別プロセスで行うハンドラ (例:
QueueHandlerとQueueListener) を使用する。 - 非同期処理に対応したロギングライブラリ (例:
aiologger) の利用を検討する。 - ログレベルを適切に設定し、本番環境では不要なログ (特にDEBUGレベル) を抑制する。
Webフレームワーク (Flask, Django) との連携
多くのWebフレームワークは、Python標準の logging モジュールと連携する仕組みを提供しています。
- Flask: Flaskアプリケーションオブジェクト (
app) がapp.loggerという標準ロガーを持っています。これは通常のloggingロガーとして使用できます。設定はdictConfigなどで通常通り行えます。 - Django: Djangoは
settings.py内のLOGGING設定ディクショナリを通じてdictConfigを利用した詳細なロギング設定をサポートしています。これにより、Django自体のログ、アプリケーションのログ、サードパーティライブラリのログを一元管理できます。
フレームワークのドキュメントを参照し、推奨される設定方法に従うのが良いでしょう。
ライブラリ開発時の注意点 ⚠️
あなたが開発しているのがアプリケーションではなく、他の開発者に使われるライブラリの場合、ロギングの扱いに注意が必要です。
- ハンドラを追加しない: ライブラリのコード内で、取得したロガーに直接ハンドラ (
StreamHandlerやFileHandlerなど) を追加しないでください。どのハンドラを使うか、どのレベルで出力するかは、ライブラリを利用するアプリケーション側が決めるべきです。 NullHandlerの利用: ライブラリの利用者がロギング設定を行わなかった場合に「No handlers could be found for logger “…”」という警告メッセージが表示されるのを防ぐため、ライブラリのトップレベルのロガーにNullHandlerを追加することが推奨されます。NullHandlerは何も出力しないため、アプリケーション側の設定を邪魔しません。
# mylibrary/__init__.py
import logging
# ライブラリ用のロガーを取得
log = logging.getLogger(__name__)
# NullHandler を追加して警告を防ぐ
log.addHandler(logging.NullHandler())
# ライブラリ内の他のモジュールはこのロガーを使う
# from . import log
# log.info(...)
このようにすることで、ライブラリ利用者は自分のアプリケーションのロギング設定で、必要に応じてライブラリからのログ ('mylibrary' ロガー) のレベルや出力先を制御できます。
ベストプラクティス 👍
効果的なロギングを行うための推奨事項をいくつか紹介します。
-
モジュールレベルでロガーを取得する:
各モジュールでlogger = logging.getLogger(__name__)を使ってロガーを取得しましょう。これにより、ロガー名がモジュールパスに対応し、設定ファイルでの制御が容易になります。ルートロガーを直接使うのは避けましょう。 -
適切なログレベルを選択する:
メッセージの重要度に応じて、DEBUG,INFO,WARNING,ERROR,CRITICALを使い分けましょう。開発中はDEBUGを多用しても良いですが、本番環境ではINFOやWARNING以上に絞ることが一般的です。 -
意味のあるログメッセージを記述する:
ログメッセージは、何が起こったのか、どのコンテキストで起こったのかが後で理解できるように、具体的かつ明確に記述しましょう。必要に応じて関連する変数を含めます (ただし、パスワードなどの機密情報は含めないように注意！)。# 悪い例 👎 logger.error("エラーが発生しました") # 良い例 👍 user_id = 101 order_id = 555 try: # ... 処理 ... raise ValueError("在庫が不足しています") except Exception as e: logger.error(f"ユーザー {user_id} の注文 {order_id} 処理中にエラーが発生: {e}", exc_info=True) -
設定は外部化する (
dictConfig推奨):
ロギング設定 (レベル、フォーマット、出力先など) は、コード内ではなく設定ファイル (JSONやYAML) に記述し、dictConfigで読み込むのがベストです。これにより、コードを変更せずに環境ごと (開発、ステージング、本番) に設定を切り替えられます。 -
構造化ロギングを検討する:
大量のログを扱う場合や、ログ分析ツール (Elasticsearch, Splunkなど) と連携する場合は、ログメッセージをJSONなどの構造化された形式で出力することを検討しましょう (例:python-json-loggerライブラリ)。これにより、ログの検索や分析が容易になります。 -
パフォーマンスへの影響を考慮する:
ロギング処理、特にファイルへの書き込みは、パフォーマンスに影響を与える可能性があります。本番環境では、不要なログ (特にDEBUGレベル) の出力を抑制するようにレベル設定を調整しましょう。また、非常に高頻度でログを出力する必要がある場合は、非同期ロギングやサンプリングなどのテクニックを検討してください。 -
ログローテーションを利用する:
ファイルにログを出力する場合、ログファイルが際限なく大きくなるのを防ぐために、RotatingFileHandlerやTimedRotatingFileHandlerを使ってログローテーションを設定しましょう。 -
ライブラリ開発者は
NullHandlerを使う:
前述の通り、ライブラリ開発者はハンドラを追加せず、NullHandlerを設定してアプリケーション側の設定に任せましょう。
まとめ 📚
Pythonの logging モジュールは、アプリケーションの動作状況を把握し、問題発生時のトラブルシューティングを助けるための強力なツールです。print() デバッグから一歩進んで logging を活用することで、より堅牢でメンテナンス性の高いコードを書くことができます。
この記事では、以下の内容について解説しました。
loggingの基本的な使い方とbasicConfig- ログレベルの概念と種類
- ロガー、ハンドラ、フォーマッタ、フィルタの役割と使い方
- コードによる設定と、推奨される設定ファイル (
dictConfig) による設定方法 - 例外情報やスタック情報のロギング
- ライブラリ開発時の注意点
- 効果的なロギングのためのベストプラクティス
最初は少し複雑に感じるかもしれませんが、主要なコンポーネントの役割と設定方法 (特に dictConfig) を理解すれば、様々な要件に応じた柔軟なロギングシステムを構築できるようになります。ぜひ、あなたのプロジェクトで logging モジュールを積極的に活用してみてください！ 😊
コメント