toms-fast 0.2.1__py3-none-any.whl

tomskit/logger/logger.py

@@ -0,0 +1,290 @@
+"""
+日志模块
+
+提供结构化的日志配置和追踪 ID 支持，支持应用日志、访问日志和 SQL 日志的分离。
+支持集中管理框架日志（uvicorn、fastapi）和第三方库日志。
+"""
+
+import os
+import logging
+from contextvars import ContextVar
+from logging.handlers import TimedRotatingFileHandler
+from typing import Optional
+from tomskit.logger.config import LoggerConfig
+
+# === Trace ID 上下文变量 ===
+# 使用 ContextVar 实现线程/协程安全的上下文变量，支持异步环境
+_trace_id_context_var: ContextVar[str] = ContextVar("app_trace_id", default="-")
+
+
+def set_app_trace_id(trace_id: str) -> None:
+    """
+    设置当前请求的追踪 ID
+    
+    该 ID 会自动添加到所有日志记录中，用于分布式追踪和问题定位。
+    通常在 FastAPI 中间件中调用，为每个请求生成唯一的追踪 ID。
+    
+    Args:
+        trace_id: 追踪 ID 字符串，通常是 UUID
+    """
+    _trace_id_context_var.set(trace_id)
+
+
+def get_app_trace_id() -> str:
+    """
+    获取当前请求的追踪 ID
+    
+    Returns:
+        追踪 ID 字符串，如果未设置则返回默认值 "-"
+    """
+    return _trace_id_context_var.get()
+
+
+class TraceIdFormatter(logging.Formatter):
+    """
+    追踪 ID 格式化器
+    
+    继承自 logging.Formatter，自动为每条日志记录注入 trace_id 和 prefix。
+    确保所有日志都包含追踪信息，便于问题定位和日志关联。
+    """
+    
+    def __init__(self, prefix: str = "", *args, **kwargs):
+        """
+        初始化格式化器
+        
+        Args:
+            prefix: 日志前缀，会添加到每条日志记录中
+            *args, **kwargs: 传递给父类的其他参数
+        """
+        self.prefix = prefix
+        super().__init__(*args, **kwargs)
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        格式化日志记录
+        
+        自动注入 trace_id 和 prefix 到日志记录中。
+        注意：LOG_FORMAT 中需要包含 %(trace_id)s 和 %(prefix)s 才能显示。
+        
+        Args:
+            record: 日志记录对象
+            
+        Returns:
+            格式化后的日志字符串
+        """
+        record.trace_id = get_app_trace_id()
+        record.prefix = self.prefix
+        return super().format(record)
+
+
+def setup_logging(settings: LoggerConfig) -> None:
+    """
+    配置日志系统
+    
+    设置应用日志、访问日志、SQL 日志和 Celery 日志的处理器和格式化器。
+    集中管理框架日志（uvicorn、fastapi、celery）和第三方库日志。
+    
+    Args:
+        settings: 日志配置对象
+        
+    Raises:
+        OSError: 当日志目录创建失败时抛出
+        PermissionError: 当没有权限创建日志文件时抛出
+    """
+    # === 基础配置 ===
+    log_level = settings.LOG_LEVEL.upper()
+    application_log_path = os.path.join(settings.LOG_DIR, f"{settings.LOG_NAME}.log")
+    access_log_path = os.path.join(settings.LOG_DIR, f"{settings.LOG_ACCESS_NAME}.log")
+    sql_log_path = os.path.join(settings.LOG_DIR, f"{settings.LOG_SQL_NAME}.log")
+    celery_log_path = os.path.join(settings.LOG_DIR, f"{settings.LOG_CELERY_NAME}.log")
+    
+    # 创建日志目录（如果不存在）
+    try:
+        os.makedirs(settings.LOG_DIR, exist_ok=True)
+    except (OSError, PermissionError) as e:
+        raise OSError(f"无法创建日志目录 {settings.LOG_DIR}: {e}")
+
+    # === 格式化器 ===
+    application_log_formatter = TraceIdFormatter(
+        prefix=settings.LOG_PREFIX,
+        fmt=settings.LOG_FORMAT,
+        datefmt=settings.LOG_DATE_FORMAT
+    )
+
+    access_log_formatter = TraceIdFormatter(
+        prefix=settings.LOG_PREFIX,
+        fmt=settings.LOG_ACCESS_FORMAT,
+        datefmt=settings.LOG_DATE_FORMAT
+    )
+
+    # === 处理器 ===
+    # 控制台处理器：输出到标准输出
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(application_log_formatter)
+
+    # 应用日志文件处理器：按天轮转
+    try:
+        application_file_handler = TimedRotatingFileHandler(
+            filename=application_log_path,
+            when=settings.LOG_ROTATE_WHEN,
+            backupCount=settings.LOG_BACKUP_COUNT,
+            encoding="utf-8",
+            utc=settings.LOG_USE_UTC,
+        )
+        application_file_handler.suffix = "%Y-%m-%d"
+        application_file_handler.setFormatter(application_log_formatter)
+    except (OSError, PermissionError) as e:
+        raise OSError(f"无法创建应用日志文件 {application_log_path}: {e}")
+
+    # 访问日志文件处理器：按天轮转
+    try:
+        access_file_handler = TimedRotatingFileHandler(
+            filename=access_log_path,
+            when=settings.LOG_ROTATE_WHEN,
+            backupCount=settings.LOG_BACKUP_COUNT,
+            encoding="utf-8",
+            utc=settings.LOG_USE_UTC,
+        )
+        access_file_handler.suffix = "%Y-%m-%d"
+        access_file_handler.setFormatter(access_log_formatter)
+    except (OSError, PermissionError) as e:
+        raise OSError(f"无法创建访问日志文件 {access_log_path}: {e}")
+
+    # SQL 日志文件处理器（可选）：按天轮转
+    sql_file_handler: Optional[TimedRotatingFileHandler] = None
+    if settings.LOG_SQL_ENABLED:
+        try:
+            sql_file_handler = TimedRotatingFileHandler(
+                filename=sql_log_path,
+                when=settings.LOG_ROTATE_WHEN,
+                backupCount=settings.LOG_BACKUP_COUNT,
+                encoding="utf-8",
+                utc=settings.LOG_USE_UTC,
+            )
+            sql_file_handler.suffix = "%Y-%m-%d"
+            sql_file_handler.setFormatter(application_log_formatter)
+        except (OSError, PermissionError) as e:
+            raise OSError(f"无法创建 SQL 日志文件 {sql_log_path}: {e}")
+
+    # Celery 日志文件处理器（可选）：按天轮转
+    celery_file_handler: Optional[TimedRotatingFileHandler] = None
+    if settings.LOG_CELERY_ENABLED:
+        try:
+            celery_file_handler = TimedRotatingFileHandler(
+                filename=celery_log_path,
+                when=settings.LOG_ROTATE_WHEN,
+                backupCount=settings.LOG_BACKUP_COUNT,
+                encoding="utf-8",
+                utc=settings.LOG_USE_UTC,
+            )
+            celery_file_handler.suffix = "%Y-%m-%d"
+            celery_file_handler.setFormatter(application_log_formatter)
+        except (OSError, PermissionError) as e:
+            raise OSError(f"无法创建 Celery 日志文件 {celery_log_path}: {e}")
+
+    # === Root Logger：所有 getLogger(__name__) 会冒泡到这里 ===
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    root_logger.handlers.clear()
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(application_file_handler)
+
+    # === 访问日志（gunicorn/uvicorn）===
+    # 访问日志单独处理，不冒泡到 root，避免重复
+    for access_logger_name in ["uvicorn.access", "gunicorn.access"]:
+        access_logger = logging.getLogger(access_logger_name)
+        access_logger.setLevel("INFO")
+        access_logger.handlers.clear()
+        access_logger.addHandler(console_handler)
+        access_logger.addHandler(access_file_handler)
+        access_logger.propagate = False  # 不冒泡到 root，避免重复
+
+    # === 框架日志（uvicorn、fastapi）===
+    # uvicorn 错误日志和主日志
+    for uvicorn_logger_name in ["uvicorn.error", "uvicorn"]:
+        uvicorn_logger = logging.getLogger(uvicorn_logger_name)
+        uvicorn_logger.setLevel(log_level)
+        uvicorn_logger.handlers.clear()
+        uvicorn_logger.addHandler(console_handler)
+        uvicorn_logger.addHandler(application_file_handler)
+        uvicorn_logger.propagate = False  # 不冒泡到 root，避免重复
+
+    # FastAPI 日志
+    fastapi_logger = logging.getLogger("fastapi")
+    fastapi_logger.setLevel(log_level)
+    fastapi_logger.handlers.clear()
+    fastapi_logger.addHandler(console_handler)
+    fastapi_logger.addHandler(application_file_handler)
+    fastapi_logger.propagate = False  # 不冒泡到 root，避免重复
+
+    # === SQLAlchemy 日志 ===
+    if settings.LOG_SQL_ENABLED and sql_file_handler:
+        # SQL 日志单独文件处理
+        for sql_logger_name in ["sqlalchemy.engine", "sqlalchemy.pool"]:
+            sql_logger = logging.getLogger(sql_logger_name)
+            sql_logger.setLevel(settings.LOG_SQL_LEVEL.upper())
+            sql_logger.handlers.clear()
+            sql_logger.addHandler(sql_file_handler)  # 只写入 SQL 日志文件
+            sql_logger.propagate = False  # 不冒泡，避免重复
+    else:
+        # SQL 日志合并到应用日志
+        for sql_logger_name in ["sqlalchemy.engine", "sqlalchemy.pool"]:
+            sql_logger = logging.getLogger(sql_logger_name)
+            sql_logger.setLevel(settings.LOG_SQL_LEVEL.upper())
+            sql_logger.handlers.clear()
+            sql_logger.addHandler(console_handler)
+            sql_logger.addHandler(application_file_handler)
+            sql_logger.propagate = False  # 不冒泡，避免重复
+
+    # === Celery 日志 ===
+    celery_logger_names = ["celery", "celery.task", "celery.worker", "celery.beat"]
+    if settings.LOG_CELERY_ENABLED and celery_file_handler:
+        # Celery 日志单独文件处理
+        for celery_logger_name in celery_logger_names:
+            celery_logger = logging.getLogger(celery_logger_name)
+            celery_logger.setLevel(settings.LOG_CELERY_LEVEL.upper())
+            celery_logger.handlers.clear()
+            celery_logger.addHandler(celery_file_handler)  # 只写入 Celery 日志文件
+            celery_logger.propagate = False  # 不冒泡，避免重复
+        
+        # Kombu 日志（消息队列）也写入 Celery 日志文件
+        kombu_logger = logging.getLogger("kombu")
+        kombu_logger.setLevel(settings.LOG_CELERY_LEVEL.upper())
+        kombu_logger.handlers.clear()
+        kombu_logger.addHandler(celery_file_handler)
+        kombu_logger.propagate = False  # 不冒泡，避免重复
+    else:
+        # Celery 日志合并到应用日志
+        for celery_logger_name in celery_logger_names:
+            celery_logger = logging.getLogger(celery_logger_name)
+            celery_logger.setLevel(settings.LOG_CELERY_LEVEL.upper())
+            celery_logger.handlers.clear()
+            celery_logger.addHandler(console_handler)
+            celery_logger.addHandler(application_file_handler)
+            celery_logger.propagate = False  # 不冒泡，避免重复
+        
+        # Kombu 日志合并到应用日志
+        kombu_logger = logging.getLogger("kombu")
+        kombu_logger.setLevel(settings.LOG_CELERY_LEVEL.upper())
+        kombu_logger.handlers.clear()
+        kombu_logger.addHandler(console_handler)
+        kombu_logger.addHandler(application_file_handler)
+        kombu_logger.propagate = False  # 不冒泡，避免重复
+
+    # === 系统日志降噪 ===
+    # asyncio 日志：只显示 WARNING 及以上级别
+    logging.getLogger("asyncio").setLevel(logging.WARNING)
+
+    # === 第三方库日志降噪 ===
+    # HTTP 客户端库
+    third_party_log_level = getattr(logging, settings.LOG_THIRD_PARTY_LEVEL.upper(), logging.WARNING)
+    for http_lib_name in ["httpx", "httpcore", "urllib3"]:
+        logging.getLogger(http_lib_name).setLevel(third_party_log_level)
+
+    # AWS SDK（如果使用）
+    for aws_lib_name in ["boto3", "botocore"]:
+        logging.getLogger(aws_lib_name).setLevel(third_party_log_level)
+
+    # 其他可能产生大量日志的库
+    logging.getLogger("PIL").setLevel(third_party_log_level)  # Pillow
+    logging.getLogger("matplotlib").setLevel(third_party_log_level)