日志配置

框架集成了强大的日志系统，基于 loguru 提供高性能、易用的日志记录功能。

核心特性

高性能：基于 loguru，支持异步日志写入
灵活配置：支持配置文件和代码两种配置方式
自动管理：支持日志轮转、压缩和自动清理
丰富格式：支持彩色输出和自定义格式
异常追踪：详细的异常信息和调用栈记录

功能概览

功能特性	描述	优势
配置文件集成	通过 YAML 配置文件管理日志	便于维护和部署
多级别日志	DEBUG、INFO、WARNING、ERROR、CRITICAL	精确控制日志输出
自动轮转	按大小或时间自动切割日志	避免单个文件过大
压缩存储	支持多种压缩格式	节省存储空间
异步写入	非阻塞日志写入	提升应用性能
格式定制	灵活的日志格式配置	满足不同需求

快速开始

基础使用

SDK 默认使用 loguru 作为日志记录库：

from loguru import logger

# 基础日志记录
logger.debug("调试信息")
logger.info("普通信息")
logger.warning("警告信息")
logger.error("错误信息")
logger.critical("严重错误")

基于配置文件的日志配置（推荐方式）

在服务初始化时，推荐通过配置文件统一管理日志参数，便于维护和部署。

完整应用示例

# main.py
import asyncio
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify

sock_path = "/xxx/app.sock"
config_path = "/xxx/config.yaml"

# 初始化时加载配置文件，自动配置 loguru 日志
app = ServerApplication(socket_path=sock_path, config_path=config_path)

@app.route(name="hello")
async def hello():
    return jsonify(data="hello world!", msg="OK")

if __name__ == "__main__":
    asyncio.run(app.run())

配置文件详解（config.yaml）

# 日志配置（必填）
logger:
  sink: app.log              # 日志输出位置（必填项）
  level: DEBUG               # 日志级别
  diagnose: false            # 是否输出调试信息（如局部变量）
  enqueue: true              # 是否异步写入日志（推荐开启）
  rotation: "500 MB"         # 日志切割条件
  retention: "1 months"      # 日志保留期限
  compression: tar           # 压缩格式（tar/zip等）
  format: "<green>{time:YYYYMMDD HH:mm:ss}</green> | \
{process.name} | {thread.name} | \
<cyan>{module}</cyan>.<cyan>{function}</cyan>:<cyan>{line}</cyan> | \
<level>{level}</level>: <level>{message}</level>"

配置参数详解

参数	类型	必需	默认值	说明
`sink`	string	✅	-	日志输出目标，支持文件路径、控制台(stdout/stderr)
`level`	string	❌	INFO	日志级别：TRACE、DEBUG、INFO、SUCCESS、WARNING、ERROR、CRITICAL
`diagnose`	boolean	❌	false	是否输出详细调试信息（局部变量等）
`enqueue`	boolean	❌	false	是否异步写入日志，提升性能
`rotation`	string	❌	-	日志轮转规则："500 MB"、"1 day"、"weekly"
`retention`	string	❌	-	日志保留时间："30 days"、"1 week"
`compression`	string	❌	-	压缩格式：tar、gz、zip、bz2、xz
`format`	string	❌	默认格式	自定义日志格式模板

实际应用场景

异常处理日志记录

以下示例展示如何在各种异常情况下记录详细的日志信息：

import asyncio
from loguru import logger
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify

sock_path = "/xxx/app.sock"
config_path = "/xxx/config.yaml"

app = ServerApplication(socket_path=sock_path, config_path=config_path)

@app.route(name="get_config_info")
async def get_config_info():
    """ 获取配置信息 """
    data = ""
    try:
        with open("config.ini", mode="r", encoding="utf-8") as f:
            data = f.read()
    except Exception as e:
        logger.error(f"读取配置失败，错误信息：{e}")
    return jsonify(data=data, msg="OK")

if __name__ == "__main__":
    asyncio.run(app.run())

开发最佳实践

日志级别使用指南

# 日志级别使用建议
from loguru import logger

# TRACE: 最详细的调试信息（通常不在生产环境使用）
logger.trace("变量值: x={}, y={}", x, y)

# DEBUG: 调试信息，帮助开发者理解程序流程
logger.debug("开始处理用户请求: {}", request_id)

# INFO: 一般信息，记录重要的业务流程
logger.info("用户 {} 登录成功", username)

# SUCCESS: 成功操作（loguru 特有）
logger.success("数据备份完成，文件大小: {} MB", file_size)

# WARNING: 警告信息，需要注意但不影响正常运行
logger.warning("API 调用频率过高，用户: {}", user_id)

# ERROR: 错误信息，影响功能但不会导致程序崩溃
logger.error("数据库连接失败，尝试重连中...")

# CRITICAL: 严重错误，可能导致程序无法继续运行
logger.critical("系统内存不足，即将关闭服务")

性能优化提示

生产环境建议使用 enqueue=True 启用异步写入
合理设置日志级别，避免过多的 DEBUG 日志
使用日志轮转和压缩，控制磁盘使用
避免在高频调用的函数中记录详细日志
考虑使用结构化日志便于后续分析

安全注意事项

永远不要记录密码、API密钥等敏感信息
对个人信息进行脱敏处理
确保日志文件的访问权限设置正确
定期清理过期的日志文件
在生产环境中关闭 diagnose 选项

总结

良好的日志系统是应用监控和问题排查的基础。通过合理配置和使用日志，您可以：

快速定位问题：详细的错误日志和调用栈信息
监控应用性能：记录关键操作的耗时和频率
增强系统安全：记录安全相关事件和异常行为
支持业务分析：通过结构化日志支持数据分析
提升开发效率：清晰的日志帮助快速理解程序行为

记住：好的日志不仅要记录发生了什么，还要记录为什么发生，以及发生的上下文信息。