otel-declarative 0.1.2__py3-none-any.whl

otel_declarative/Infrastructure/async_log_engine.py

@@ -0,0 +1,164 @@
+import queue
+import logging
+import atexit
+import threading
+from logging.handlers import QueueHandler, QueueListener
+from typing import List, Optional, Dict, ClassVar
+from otel_declarative.Models.Log.context import StructuredLogSettings
+from otel_declarative.Logging.logger_factory import LoggerFactory, LogConfig
+from otel_declarative.Infrastructure.handlers import NonBlockingQueueHandler
+
+class AsyncLogInfrastructure:
+    """
+    异步日志基础设施管理器
+
+    职责:
+        1、核心队列维护: 负责初始化线程安全的高性能 Queue 对象, 缓冲业务侧高频产生的日志事件
+        2、监听器生命周期管理: 管理后台 QueueListener 线程的启动与停机, 确保资源安全回收
+        3、同步 Sink 桥接: 利用 LoggerFactory 构造底层物理输出层, 并将其封装为异步消费端
+    """
+
+    def __init__(self, settings: StructuredLogSettings, base_log_config: LogConfig):
+        """
+        :param settings: 结构化日志引擎全局配置模型
+        :param base_log_config: 基础日志配置对象
+        """
+        self._settings = settings
+        self._base_config: LogConfig = base_log_config
+        # 内部状态
+        self._queue: Optional[queue.Queue] = None
+        self._listener: Optional[QueueListener] = None
+        self._handler: Optional[QueueHandler] = None
+        self._is_active: bool = False
+
+    def build_async_handler(self) -> logging.Handler:
+        """
+        构建并启动异步日志处理流水线
+
+        逻辑:
+            1、调用 LoggerFactory 构造底层的物理输出 Handler 集合
+            2、初始化线程安全的消息队列
+            3、启动后台 QueueListener 线程执行日志的物理落盘
+            4、向系统注册 atexit 钩子, 确保进程推出前强制刷新缓冲区
+
+        :return: 配置完成的 QueueHandler 实例, 用于挂载至 stdlib logging 节点
+        """
+        # --- 1、构造物理输出层 ---
+        sink_bridge_logger: logging.Logger = LoggerFactory.setup_logger(self._base_config)
+        physical_handlers: List[logging.Handler] = sink_bridge_logger.handlers
+        if not physical_handlers:
+            # 若配置未开启任何输出, 返回 NullHandler 防止系统崩溃
+            return logging.NullHandler()
+
+        # --- 2、初始化异步队列 (队列深度由 StructureLogSettings 驱动) ---
+        self._queue = queue.Queue(maxsize=self._settings.queue_size)
+
+        # --- 3、构造并启动后台监听器 ---
+        # respect_handler_level=True 确保物理 Handler 的 Level 设置生效
+        self._listener = QueueListener(self._queue, *physical_handlers, respect_handler_level=True)
+        self._listener.start()
+        self._is_active = True
+
+        # --- 4、注册进程退出清理机制 ---
+        atexit.register(self.shutdown)
+
+        # --- 5、构造前端入队处理器
+        self._handler = NonBlockingQueueHandler(self._queue)
+
+        # [Fix 2026.01.15]
+        return self._handler
+
+    def shutdown(self) -> None:
+        """
+        停止后台监听线程并确保队列中积压的日志记录完成最终分发
+
+        Fail-safe 机制:
+            1、优先尝试正常的 stop() 发送哨兵
+            2、若队列已满导致 Full 异常, 主动执行退避策略
+                - 丢弃最旧的日志以腾出空间
+                - 再次尝试发送哨兵
+            3、确保在极端积压场景下也能优雅退出, 避免阻塞主进程
+        """
+        if not (self._listener and self._is_active):
+            return
+
+        if getattr(self._listener, "_thread", None) is None:
+            self._is_active = False
+            return
+
+        try:
+            self._listener.stop()
+        except queue.Full:
+            max_retries: int = 3
+            for _ in range(max_retries):
+                try:
+                    self._queue.get_nowait()
+                except queue.Empty:
+                    pass
+
+                try:
+                    if getattr(self._listener, "_thread", None) is None:
+                        break
+                    self._listener.stop()
+                    break
+                except queue.Full:
+                    # 依然满 (高并发写入竞争), 继续重试
+                    continue
+            else:
+                pass
+        except AttributeError:
+            # 处理 _thread 为 None 的情况
+            pass
+
+        self._is_active = False
+
+    @property
+    def is_running(self) -> bool:
+        """
+        获取当前异步基础设施的运行状态标识
+        """
+        return self._is_active
+
+class AsyncInfrastructureRegistry:
+    """
+    异步基础设施注册中心
+
+    职责:
+        1、单例控制: 确保每个 LogConfig 对应的异步管理器在全局范围内唯一
+        2、Fail-safe 访问: 提供安全的管理器获取入口, 封装初始化复杂度
+    """
+    # 全局单例注册表
+    _managers: Dict[str, AsyncLogInfrastructure] = {}
+    # 线程同步原语: 可重入锁
+    _lock: ClassVar[threading.RLock] = threading.RLock()
+
+    @classmethod
+    def get_infrastructure(cls, settings: StructuredLogSettings, log_config: LogConfig) -> AsyncLogInfrastructure:
+        """
+        根据配置标识获取或创建异步基础设施管理器
+
+        逻辑:
+            1、无锁读取
+            2、仅在实例不存在时竞争锁
+            3、获取锁后再次检查, 防止重复初始化
+            4、安全执行带有副作用的初始化逻辑
+
+        :param settings: 结构化日志设施
+        :param log_config: 基础日志配置
+        :return: 活跃且唯一的 AsyncLogInfrastructure 实例
+        """
+        # 使用服务名作为注册索引键
+        registry_key: str = log_config.service_name
+
+        if registry_key in cls._managers:
+            return cls._managers[registry_key]
+
+        with cls._lock:
+            if registry_key not in cls._managers:
+                instance = AsyncLogInfrastructure(
+                    settings=settings,
+                    base_log_config=log_config
+                )
+                cls._managers[registry_key] = instance
+
+        return cls._managers[registry_key]

otel_declarative/Infrastructure/handlers.py

@@ -0,0 +1,39 @@
+import queue
+import logging
+from typing import cast
+from logging.handlers import QueueHandler
+
+class NonBlockingQueueHandler(QueueHandler):
+    """
+    非阻塞式异步队列处理器
+
+    职责:
+        1、扩展标准库 QueueHandler, 重写核心入队逻辑
+        2、实现 '队列满时自动丢弃最旧日志' 策略, 确保新日志优先
+        3、消除 queue.Full 异常的抛出, 保证 stderr 的清洁与业务线程的零阻塞
+    """
+    def enqueue(self, record: logging.LogRecord) -> None:
+        """
+        执行非阻塞入队操作
+
+        逻辑:
+            1、立即尝试入队
+            2、若队列已满:
+                a、尝试从队列头部移除一个最旧元素以腾出空间
+                b、再次尝试将当前新记录入队
+            3、若在极端并发竞争下第二次入队依然失败, 则静默丢弃当前记录, 不抛出任何错误
+
+        :param record: 待处理的日志记录对象
+        """
+        try:
+            self.queue.put_nowait(record)
+        except queue.Full:
+            try:
+                cast(queue.Queue, self.queue).get_nowait()
+            except (queue.Empty, AttributeError):
+                pass
+
+            try:
+                self.queue.put_nowait(record)
+            except queue.Full:
+                pass

otel_declarative/Interfaces/extractor.py

@@ -0,0 +1,50 @@
+from typing import Any, Protocol, Type, Optional, runtime_checkable
+from otel_declarative.Models.summary_models import InputSummary, OutputSummary
+
+@runtime_checkable
+class IExtractor(Protocol):
+    """
+    元数据提取器接口协议
+
+    定义从原始业务载体中提取标准化观测摘要的标准行为
+    """
+    def extract_input(self, args: Any, kwargs: Any) -> InputSummary:
+        """
+        从被装饰函数的原始调用参数中提取标准化输入摘要
+
+        职责:
+            1、识别并解析 args / kwargs 中的业务载体
+            2、负责防御性参数校验, 确保提取逻辑不会感染主业务流程
+            3、构造并返回 InputSummary 强类型对象
+
+        :param args: 函数位置参数元组
+        :param kwargs: 函数关键字参数字典
+        :return: 填充后的标准化输入摘要模型实例
+        """
+        ...
+
+    def extract_output(self, result: Any) -> OutputSummary:
+        """
+        从被装饰函数的执行结果中提取标准化输出摘要
+
+        职责:
+            1、解析业务返回值
+            2、提取跨系统追踪的关键标识符
+            3、评估业务执行的逻辑结果简述
+
+        :param result: 被装饰函数执行后的返回值对象
+        :return: 填充后的标准化输出摘要模型实例
+        """
+        ...
+
+    def supports(self, layer: str, payload_type: Optional[Type[Any]] = None) -> bool:
+        """
+        策略自发现标识: 判定当前提取器是否能够处理指定的逻辑层级或数据载体类型
+
+        用于 ExtractorFactory 在运行时根据上下文动态选择合适的策略类
+
+        :param layer:
+        :param payload_type:
+        :return:
+        """
+        ...

otel_declarative/Logging/logger_factory.py

@@ -0,0 +1,185 @@
+import os
+import logging
+import sys
+from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler
+from enum import Enum
+from typing import Optional
+from dataclasses import dataclass
+
+class LogLevel(Enum):
+    """
+    日志级别枚举
+    """
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+    def to_logging_level(self) -> int:
+        return logging.getLevelName(self.value)
+
+class RotationType(str, Enum):
+    """
+    日志轮转策略枚举
+    """
+    # 不输出到文件
+    NONE = "none"
+    # 按文件大小轮转
+    SIZE = "size"
+    # 按时间间隔轮转
+    TIME = "time"
+
+@dataclass
+class LogConfig:
+    """
+    日志系统配置类
+    """
+    # --- 基础标识 ---
+    service_name: str
+
+    # --- 输出控制 ---
+    level: LogLevel = LogLevel.INFO
+    # 是否输出到标准输出
+    enable_console: bool = True
+    # 是否输出到文件
+    enable_file: bool = True
+
+    # --- 文件路径配置 (仅当 enable_file = True 时生效)
+    log_dir: str = "/var/log/app"
+    file_name: Optional[str] = None
+
+    # --- 轮转策略配置 ---
+    rotation_type: RotationType = RotationType.NONE
+
+    # Size 策略参数
+    max_bytes: int = 10 * 1024 * 1024
+    backup_count: int = 5
+
+    # Time 策略参数
+    # S: Seconds, M: Minutes, H: Hours, D: Days, midnight: roll over at midnight
+    when: str = "midnight"
+    interval: int = 1
+    # 是否使用 UTC 时间
+    utc: bool = False
+
+    # --- 格式配置 ---
+    # 默认格式串，可由配置文件覆盖
+    format_string: str = (
+        "%(asctime)s | %(levelname)-8s | %(name)s | "
+        "thread:%(thread)d | %(filename)s:%(lineno)d | %(message)s"
+    )
+
+    def get_log_file_path(self) -> str:
+        """
+        计算完整的日志文件绝对路径
+        """
+        fname = self.file_name or f"{self.service_name}.log"
+        return os.path.join(self.log_dir, fname)
+
+class LoggerFactory:
+    """
+    日志工厂类
+    负责根据传入的配置对象构建和组装标准化的 Logger 实例
+    """
+    @staticmethod
+    def setup_logger(config: LogConfig) -> logging.Logger:
+        """
+        根据配置文件初始化并获得 Logger 实例
+
+        :param config: 完整的日志配置对象
+        :return: 配置完成的 Logger
+        """
+        # --- 1、获取 Logger 对象 ---
+        logger = logging.getLogger(config.service_name)
+        logger.setLevel(config.level.to_logging_level())
+
+        # 屏蔽第三方库的底层详细日志
+        silenced_loggers = [
+            "httpcore", "httpx", "hpack", "anyio",
+            "httpcore._trace", "httpcore._client"
+        ]
+        for logger_name in silenced_loggers:
+            logging.getLogger(logger_name).setLevel(logging.WARNING)
+
+        # 清除已有的处理器
+        if logger.handlers:
+            logger.handlers.clear()
+
+        # 防止日志传播到根记录器导致双重打印
+        logger.propagate = False
+
+        # --- 2、创建统一格式化器 ---
+        formatter = logging.Formatter(config.format_string)
+
+        # --- 3、配置控制太处理器 ---
+        if config.enable_console:
+            console_handler = logging.StreamHandler(sys.stdout)
+            console_handler.setFormatter(formatter)
+            logger.addHandler(console_handler)
+
+        # --- 4、配置从文件处理器 ---
+        if config.enable_file and config.rotation_type != RotationType.NONE:
+            file_handler = LoggerFactory._create_file_handler(config)
+            if file_handler:
+                file_handler.setFormatter(formatter)
+                logger.addHandler(file_handler)
+
+        return logger
+
+    @staticmethod
+    def _create_file_handler(config: LogConfig) -> Optional[logging.Handler]:
+        """
+        根据 RotationType 创建相应的文件处理器
+
+        :param config: 日志系统配置对象
+        """
+        # --- 1、前置检查: 确保目录存在 ---
+        if not os.path.exists(config.log_dir):
+            try:
+                os.makedirs(config.log_dir, exist_ok=True)
+            except OSError as e:
+                sys.stderr.write(f"CRITICAL: Logger 创建日志目录 {config.log_dir} 失败: {e}\n")
+                return None
+
+        file_path = config.get_log_file_path()
+
+        try:
+            handler: logging.Handler
+
+            if config.rotation_type == RotationType.SIZE:
+                # 按大小切割
+                handler = RotatingFileHandler(
+                    filename=file_path,
+                    mode="a",
+                    maxBytes=config.max_bytes,
+                    backupCount=config.backup_count,
+                    encoding="utf-8",
+                    delay=True # 延迟打开文件, 直到第一条日志写入
+                )
+            elif config.rotation_type == RotationType.TIME:
+                # 按时间切割
+                handler = TimedRotatingFileHandler(
+                    filename=file_path,
+                    when=config.when,
+                    interval=config.interval,
+                    backupCount=config.backup_count,
+                    encoding="utf-8",
+                    utc=config.utc,
+                    delay=True
+                )
+            else:
+                return None
+        except Exception as e:
+            sys.stderr.write(f"CRICTL: 初始化文件 {file_path} 的文件句柄失败: {e}\n")
+            return None
+
+def get_child_logger(parent_logger_name: str, child_suffix: str) -> logging.Logger:
+    """
+    获取子模块 Logger 的辅助函数
+
+    :param parent_logger_name: 父 Logger 名称 (例如 backfill)
+    :param child_suffix: 子模块后缀 (例如 controllers.job)
+    :return: 名称为 backfill.controllers.job 的 Logger
+    """
+    return logging.getLogger(f"{parent_logger_name}.{child_suffix}")

otel_declarative/Models/Log/constants.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+from enum import unique, Enum
+from typing import runtime_checkable, Protocol, Any, Dict
+
+# --- 基础契约模块 ---
+
+@dataclass(frozen=True)
+class FieldContract:
+    """
+    定义字段的观测协议元数据
+    """
+    source_key: str = ""
+    is_renamable: bool = False
+
+
+@unique
+class LogFormat(str, Enum):
+    """
+    结构化日志输出格式枚举
+
+    职责:
+        1、定义渲染器的策略标识
+        2、区分面向人类阅读的控制台模式与面向机器处理的 JSON 模式
+    """
+    # 适合开发环境, 带有颜色与缩进
+    CONSOLE = "console"
+    # 适合生产环境, 标准 JSON 行格式
+    JSON = "json"
+
+
+@runtime_checkable
+class ILogProcessor(Protocol):
+    """
+    结构化日志处理器接口协议
+
+    职责: 定义标准 structlog 中间件必须遵循的函数签名契约
+    """
+    def __call__(self, logger: Any, method_name: str, event_dict: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        执行日志事件处理逻辑
+
+        :param logger: 当前绑定的 Logger 实例 (BindableLogger、stdlib Logger 等)
+        :param method_name: 触发日志的方法名
+        :param event_dict: 当前上下文累积的日志数据字典
+        :return: 处理或增强后的新事件字典
+        """
+        ...

otel_declarative/Models/Log/context.py

@@ -0,0 +1,105 @@
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, ConfigDict, Field
+from otel_declarative.Models.Log.constants import LogFormat
+from otel_declarative.Models.Log.mapping import LogFieldMapping
+
+# --- 上下文与设置模块 ---
+
+class LogContext(BaseModel):
+    """
+    结构化日志强制上下文模型
+
+    职责:
+        1、定义每一行日志必须携带的 '全链路追踪' 核心字段
+        2、作为 OtelTraceContextProcessor 注入数据的强类型契约
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+    )
+
+    trace_id: Optional[str] = Field(
+        default=None,
+        alias="trace_id",
+        description="OpenTelemetry 全局追踪标识符",
+    )
+
+    span_id: Optional[str] = Field(
+        default=None,
+        alias="span_id",
+        description="OpenTelemetry 当前跨度标识符"
+    )
+
+    service_name: str = Field(
+        ...,
+        alias="service",
+        description="产生日志的服务 / 应用的唯一名称"
+    )
+
+    environment: str = Field(
+        default="production",
+        description="部署环境标识 (例如: development, production)"
+    )
+
+    node_name: Optional[str] = Field(
+        default=None,
+        description="逻辑节点或 Pod 名称"
+    )
+
+
+class StructuredLogSettings(BaseModel):
+    """
+    结构化日志引擎全局设置模型
+
+    职责:
+        1、封装所有影响 structlog 初始化与运行行为的参数
+        2、解耦日志逻辑与底层 I/O 基础设施
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        extra="ignore"
+    )
+
+    # --- 渲染控制 ---
+    log_format: LogFormat = Field(
+        default=LogFormat.JSON,
+        description="日志渲染格式策略选择"
+    )
+
+    # --- 异步性能控制 ---
+    enable_async: bool = Field(
+        default=True,
+        description="是否启用基于 QueueHandler 的异步写入引擎"
+    )
+
+    queue_size: int = Field(
+        default=1000,
+        ge=100,
+        description="异步日志缓冲区队列容量上限"
+    )
+
+    # --- 上下文注入控制 ---
+    inject_otel_context: bool = Field(
+        default=True,
+        description="是否自动调用处理器注入 TraceID 与 SpanID"
+    )
+
+    # --- 字段映射控制 ---
+    # 允许在不修改代码的情况下, 动态映射 structlog 默认字段名
+    # 例如: 将 'event' 映射为 'message' 以适配特定 ELK 索引
+    field_mapping: LogFieldMapping = Field(
+        default_factory=LogFieldMapping,
+        description="结构化字段名重映射配置对象, 支持嵌套校验"
+    )
+
+    def to_structlog_processors_config(self) -> Dict[str, Any]:
+        """
+        将模型转换为 structlog 配置所需的字典快照
+
+        :return: 包含关键开关的字典
+        """
+        return {
+            "format": self.log_format.value,
+            "async_enabled": self.enable_async,
+            "mapping": self.field_mapping
+        }

otel_declarative/Models/Log/mapping.py

@@ -0,0 +1,94 @@
+from typing import Annotated, Dict, Any, Set
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from otel_declarative.Models.Log.constants import FieldContract
+
+# --- 映射规则模块 ---
+
+class LogFieldMapping(BaseModel):
+    """
+    日志标准字段重映射模型
+
+    职责:
+        1、契约定义: 利用 Annotated 语法将业务配置与底层 FieldContract 观测契约进行原子化绑定
+        2、静态校验: 强制执行输出键名的唯一性检查, 防止日志数据覆盖
+        3、引擎导航: 为 LogFieldRenamer 提供高性能的迁移矩阵预计算基础
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+    )
+
+    # --- 基础字段 ---
+    event: Annotated[
+        str,
+        Field(default="event", description="业务事件消息的输出键名"),
+        FieldContract(source_key="event", is_renamable=True),
+    ]
+
+    timestamp: Annotated[
+        str,
+        Field(default="@timestamp", description="日志产生时间的输出键名"),
+        FieldContract(source_key="timestamp", is_renamable=True),
+    ]
+
+    level: Annotated[
+        str,
+        Field(default="level", description="日志级别的输出键名"),
+        FieldContract(source_key="level", is_renamable=True),
+    ]
+
+    logger: Annotated[
+        str,
+        Field(default="logger", description="日志记录器名称的输出键名"),
+        FieldContract(source_key="logger", is_renamable=True)
+    ]
+
+    # --- OTel 追踪字段 ---
+    trace_id: Annotated[
+        str,
+        Field(default="trace_id", description="注入的 OTel TraceID 输出键名"),
+        FieldContract(is_renamable=False)
+    ]
+
+    span_id: Annotated[
+        str,
+        Field(default="span_id", description="注入的 OTel SpanID 输出键名"),
+        FieldContract(is_renamable=False)
+    ]
+
+    # --- 服务元数据字段 ---
+    service: Annotated[str,
+    Field(default="service", description="服务唯一名称的输出键名"),
+    FieldContract(is_renamable=False)
+    ]
+
+    environment: Annotated[str,
+    Field(default="environment", description="运行环境标识的输出键名"),
+    FieldContract(is_renamable=False)
+    ]
+
+    pod_name: Annotated[str,
+    Field(default="pod_name", description="K8S Pod/节点名称的输出键名"),
+    FieldContract(is_renamable=False)
+    ]
+
+    @model_validator(mode="after")
+    def validate_no_target_key_collision(self) -> "LogFieldMapping":
+        """
+        后验校验: 确保所有的目标键名在日志 Schema 中具有唯一性
+
+        职责: 防止用户在 YAML 配置中错误的将两个不同的字段映射到同一个 Key, 导致日志数据覆盖
+
+        :return: 校验后的实例
+        :raises: ValueError - 当检测到键名冲突时抛出
+        """
+        target_keys: Dict[str, Any] = self.model_dump()
+        seen_keys: Set[str] = set()
+        for attr_name, target_key in target_keys.items():
+            if target_key in seen_keys:
+                raise ValueError(
+                    f"日志字段映射冲突: 多个配置项指向了同一个目标键名 '{target_key}'"
+                    f"请检查模型属性 '{attr_name}' 的配置"
+                )
+            seen_keys.add(target_key)
+        return self