frappe-core-logging

Frappe 日志记录与错误跟踪

三种日志记录机制

机制	存储位置	用途
frappe.logger()	文件（轮转）	应用日志、调试信息、审计记录
frappe.log_error()	数据库（Error Log DocType）	在管理界面中查看错误，持久化跟踪
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——每个文件 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 文档，导致管理界面杂乱
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 请求/作业上下文
错误快照	基于文件 + 定时收集	直接插入数据库
Sentry 集成	基础	增强（数据库监控、性能分析）
guess_exception_source()	--	识别导致错误的应用
FRAPPE_STREAM_LOGGING	是	是

---

参考文件

• Logger API 与模式 — frappe.logger() 高级用法
• 错误跟踪 — Error Log、Sentry、监控