frappe-core-logging

Frappe のログ記録とエラー追跡

3 つのログ記録メカニズム

メカニズム	保存先	用途
frappe.logger()	ファイル（ローテーション）	アプリケーションのログ記録、デバッグ情報、監査証跡
frappe.log_error()	データベース（Error Log DocType）	管理 UI で確認できるエラー、永続的な追跡
frappe.log() / frappe.errprint()	stderr / リクエストスコープ	手早いデバッグのみ（本番環境では使用しないでください）

---

判断フロー

Need to log something?
│
├─ Application logging (info, debug, warnings)?
│  └─ frappe.logger("my_module").info("message")
│     → Writes to sites/{site}/logs/my_module.log
│
├─ Error that admins should see in Desk UI?
│  └─ frappe.log_error(title="Short desc", message=traceback)
│     → Creates Error Log document (queryable, auto-cleanup)
│
├─ Quick debug during development?
│  └─ frappe.errprint(variable) — shows in console
│     → NEVER leave in production code
│
├─ Track all HTTP requests?
│  └─ Set enable_frappe_logger: true in site_config.json
│     → Logs to frappe.web.log
│
├─ Performance monitoring?
│  └─ Set monitor: true in site_config.json
│     → Logs to monitor.json.log (JSON, per-request metrics)
│
└─ External error tracking (Sentry)?
   └─ Set FRAPPE_SENTRY_DSN environment variable
      → Auto-captures unhandled exceptions

---

クイックリファレンス：frappe.logger()

# Get a logger for your module (ALWAYS specify module name)
logger = frappe.logger("my_app")

# Standard Python logging levels
logger.debug("Detailed diagnostic info")
logger.info("Normal operations: processed 50 records")
logger.warning("Something unexpected but recoverable")
logger.error("Operation failed", exc_info=True)
logger.critical("System-level failure")

# Full signature
frappe.logger(
    module=None,          # Logger name + log filename
    with_more_info=False, # Auto-log request form_dict
    allow_site=True,      # Log under site's logs/ directory
    filter=None,          # Custom logging.Filter
    max_size=100_000,     # Max bytes per log file (100KB default)
    file_count=20         # Rotated files retained (20 default)
)

ログの保存場所： sites/{site}/logs/{module}.log ローテーション： RotatingFileHandler — 1 ファイルあたり 100KB、バックアップ 20 個（ロガーあたり合計約 2MB）

デフォルトのログレベル

モード	レベル	効果
開発（_dev_server）	WARNING	Debug/info は出力されません
本番環境	ERROR	エラー以上のみ

# Change level dynamically
frappe.utils.logger.set_log_level("DEBUG")

---

クイックリファレンス：frappe.log_error()

# ALWAYS use keyword arguments (title/message can swap otherwise)
frappe.log_error(
    title="Payment gateway timeout",          # Short description (140 chars max)
    message=frappe.get_traceback(),            # Full error details
    reference_doctype="Payment Entry",        # Related DocType
    reference_name="PE-00001"                 # Related document
)

# Minimal — auto-captures current traceback
try:
    risky_operation()
except Exception:
    frappe.log_error(title="Operation failed")

Error Log のクリーンアップ： 30 日後に自動削除されます。手動で実行する場合：frappe.whitelist: clear_error_logs()

自動で捕捉される例外

未処理の例外（HTTP 500 以上）は、自動的に Error Log に記録されます。

自動捕捉の対象外：

• frappe.AuthenticationError
• frappe.CSRFTokenError
• frappe.SecurityException
• frappe.InReadOnlyMode

---

本番環境の設定

site_config.json のキー

キー	値	効果
enable_frappe_logger	true	HTTP リクエストを記録 → frappe.web.log
logging	2	すべての SQL クエリを記録（デバッグ専用です！）
monitor	true	リクエスト／ジョブのメトリクス → monitor.json.log
disable_error_snapshot	true	例外の自動捕捉を無効化

環境変数

変数	効果
FRAPPE_STREAM_LOGGING=1	ファイルの代わりに stderr に記録
FRAPPE_SENTRY_DSN=<dsn>	Sentry のエラー追跡を有効化
ENABLE_SENTRY_DB_MONITORING	Sentry で SQL クエリを追跡
SENTRY_TRACING_SAMPLE_RATE	パフォーマンス追跡率（0.0-1.0）

本番環境のログファイル

ファイル	内容
logs/web.error.log	HTTP エラー（supervisor）
logs/web.log	Gunicorn の標準出力
logs/worker.error.log	バックグラウンドジョブのエラー
logs/frappe.log	デフォルトの frappe ロガー
logs/frappe.web.log	HTTP リクエストのメタデータ
logs/monitor.json.log	パフォーマンスメトリクス（JSON）
sites/{site}/logs/*.log	サイトごとのアプリケーションログ

---

アンチパターン

絶対にしない	必ず行う	理由
print("debug info")	frappe.logger("mod").info(...)	print() は本番環境では出力されません
frappe.log_error("info msg")	frappe.logger().info(...)	log_error は Error Log ドキュメントを作成し、管理 UI が煩雑になります
frappe.logger()（モジュール指定なし）	frappe.logger("my_module")	モジュールを指定しないと、フレームワークのログと混在します
frappe.log_error(title, msg) の位置引数	frappe.log_error(title=t, message=m)	位置引数は順序が入れ替わる可能性があります（既知の問題）
パスワードやトークンを記録する	機密データをマスクする	SiteContextFilter がマスクするのは form_dict のみです
本番環境で frappe.log() を使う	frappe.logger() を使う	frappe.log() はデバッグ専用で、リクエストスコープです
本番環境で logging=2 のままにする	デバッグ中のみ使用する	すべての SQL クエリが記録され、大量の I/O が発生します

---

バージョンによる違い

機能	v14	v15+
frappe.logger()	あり	あり
frappe.log_error()	あり	+ defer_insert kwarg
Error Log の trace_id	--	追加
Error Log のメタデータ	--	JSON 形式のリクエスト／ジョブコンテキスト
エラースナップショット	ファイルベース + スケジュールされた収集	DB に直接挿入
Sentry との統合	基本機能	強化（DB モニタリング、プロファイリング）
guess_exception_source()	--	エラーの原因となったアプリを特定
FRAPPE_STREAM_LOGGING	あり	あり

---

参考ファイル

• ロガー API とパターン — frappe.logger() の高度な使い方
• エラー追跡 — Error Log、Sentry、モニタリング