otel-declarative 0.1.2__py3-none-any.whl

otel_declarative/Models/Log/state.py

@@ -0,0 +1,59 @@
+from pydantic import BaseModel, ConfigDict, Field
+from otel_declarative.Models.Log.constants import LogFormat
+
+# --- 引擎状态模块 ---
+
+class ReporterEngineState(BaseModel):
+    """
+    结构化记录器引擎运行状态快照模型
+
+    职责:
+        1、状态聚合: 封装工厂在不同生命周期阶段的关键运行元数据
+        2、线程安全: 利用 frozen=True 确保快照在读取过程中不可修改
+        3、可观测性: 提供标准 __repr__ 实现, 集中暴露引擎健康度
+    """
+    model_config = ConfigDict(
+        frozen=True,
+    )
+
+    # --- 核心状态属性 ---
+    is_ready: bool = Field(
+        default=False,
+        description="就绪状态标识"
+    )
+
+    active_format: LogFormat = Field(
+        default=LogFormat.JSON,
+        description="当前日志渲染格式"
+    )
+
+    # 逻辑处理器链的长度 (可用于一致性审计)
+    processor_count: int = Field(
+        default=0,
+        description="已挂载处理器数量"
+    )
+
+    has_async_infra: bool = Field(
+        default=False,
+        description="是否开启异步写入"
+    )
+
+    def __repr__(self) -> str:
+        """
+        提供标准化的状态监测输出
+        """
+        status: str = "READY" if self.is_ready else "PENDING"
+        async_flag: str = "ASYNC" if self.has_async_infra else "SYNC"
+        return (
+            f"<ReporterEngineState status={status}, format={self.active_format.value}, mode={async_flag}, procs={self.processor_count}>"
+        )
+
+    @classmethod
+    def create_initial(cls, _format: LogFormat) -> "ReporterEngineState":
+        """
+        构造初始待命状态
+
+        :param _format: 当前系统配置中预设的日志渲染格式
+        :return: 处于未就绪状态的 ReporterEngineState 实例
+        """
+        return cls(is_ready=False, active_format=_format)

otel_declarative/Models/Log/topology.py

@@ -0,0 +1,202 @@
+import structlog.contextvars
+from typing import Dict, Any, List, Callable
+from pydantic import BaseModel, Field, ConfigDict
+from otel_declarative.Models.Log.constants import ILogProcessor
+
+#  --- 处理器拓扑模块 ---
+
+class InjectionLayer(BaseModel):
+    """
+    上下文注入层容器模型
+
+    职责:
+        1、聚合封装: 包含所有负责向日志事件中产生新数据的处理器 (TraceID、ServiceMetadata 等)
+        2、语义明确: 明确标识该层级仅负责数据增补, 不涉及键名修改或格式化
+        3、接口隔离: 仅接受符合 InjectionLayer 协议的可调用对象
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True, # 允许 Pydantic 校验 Protocol 类型
+    )
+
+    processors: List[ILogProcessor] = Field(
+        default_factory=list,
+        description="负责产生新元数据的处理器序列"
+    )
+
+    def as_list(self) -> List[ILogProcessor]:
+        """
+        获取原始处理器列表以供 structlog 配置使用
+
+        :return: 符合 structlog 协议的处理器列表
+        """
+        return self.processors
+
+class RenamingLayer(BaseModel):
+    """
+    字段重命名层容器模型
+
+    职责:
+        1、单一封装: 包含负责最终 Schema 映射的处理器
+        2、末端约束: 明确标识该层级应位于处理链的末端 (但在渲染之前)
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True, # 允许 Pydantic 校验 Protocol 类型
+    )
+
+    processor: ILogProcessor = Field(
+        ...,
+        description="负责执行 Schema 映射的处理器"
+    )
+
+    def as_list(self) -> List[ILogProcessor]:
+        """
+        获取包装为列表的处理器, 便于链式拼接
+
+        :return: 包含单个处理器的列表
+        """
+        return [self.processor]
+
+class BaseLayer(BaseModel):
+    """
+    基础处理层容器模型
+
+    职责:
+        1、预置标准库: 封装 structlog 核心的基础处理器 (Context, Timestamp, Level)
+        2、顺序固化: 确保基础元数据的生成顺序不被干扰
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True,
+    )
+
+    # 使用私有属性存储实际处理器列表, 避免 Pydantic 序列化 lambda 或复杂对象时的潜在问题
+    _processors: List[Callable] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+    ]
+
+    def as_list(self) -> List[Callable]:
+        """
+        获取基础处理器序列
+
+        :return: 不可变的基础处理器列表
+        """
+        return list(self._processors)
+
+class NormalizationLayer(BaseModel):
+    """
+    内容标准化层容器模型
+
+    职责:
+        1、格式统一: 将异常、位置参数等非结构化数据转化为标准字典键
+        2、编码安全: 确保所有内容通过 Unicode 解码
+        3、前置约束: 必须位于 RenamingLayer 前执行
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True
+    )
+
+    _processors: List[Callable] = [
+        structlog.processors.format_exc_info,
+        structlog.processors.EventRenamer("event"),
+        structlog.processors.UnicodeDecoder()
+    ]
+
+    def as_list(self) -> List[Callable]:
+        """
+        获取标准化处理器序列
+
+        :return: 不可变的标准化处理器列表
+        """
+        return list(self._processors)
+
+class ProcessorTopology(BaseModel):
+    """
+    日志处理器拓扑结构模型
+
+    职责:
+        1、全链路编排: 将松散的处理器容器重构为具有严格时序语义的强类型拓扑对象
+        2、层级隔离: 明确划分基础层、注入层、标准化层与重命名层的边界
+        3、链条组装: 提供标准化的 to_chain() 方法生成最终执行序列
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True, # 允许 Pydantic 校验 Protocol 类型
+    )
+
+    # --- 基础层 (组合关系, 强拥有, 自动初始化) ---
+    base_layer: BaseLayer = Field(
+        default_factory=BaseLayer,
+        description="产生时间戳与日志等级的基础层"
+    )
+
+    # --- 注入层 (聚合关系, 外部注入) ---
+    injection_layer: InjectionLayer = Field(
+        ...,
+        description="负责注入 TraceID 与服务元数据的注入层"
+    )
+
+    # --- 标准化层 (组合关系, 强拥有, 自动初始化) ---
+    normalization_layer: NormalizationLayer = Field(
+        default_factory=NormalizationLayer,
+        description="负责内容清洗与标准化的中间层"
+    )
+
+    # --- 重命名层 (聚合关系, 外部注入) ---
+    renaming_layer: RenamingLayer = Field(
+        ...,
+        description="负责最终 Schema 映射的重命名层"
+    )
+
+    def to_chain(self) -> "ProcessorChain":
+        """
+        生成符合 structlog 协议的完整处理器链容器
+
+        执行顺序 (Strict Order):
+            1、Base: 准备上下文与元数据 (Time, Level)
+            2、Injection: 注入业务追踪信息 (TraceID, Service)
+            3、Normalization: 生成 event / exception 标准键
+            4、Renaming: 执行最终字段映射
+
+        :return: 封装后的 ProcessorChain 对象
+        """
+        chain: List[Callable[[Any, str, Dict[str, Any]], Dict[str, Any]]] = []
+
+        # 按严格拓扑顺序拼接
+        chain.extend(self.base_layer.as_list())
+        chain.extend(self.injection_layer.as_list())
+        chain.extend(self.normalization_layer.as_list())
+        chain.extend(self.renaming_layer.as_list())
+
+        return ProcessorChain(processors=chain)
+
+class ProcessorChain(BaseModel):
+    """
+    处理器链最终产物容器模型
+
+    职责:
+        1、终态封装: 承载已完成所有拓扑排序与校验、可直接交付给 structlog 的处理器序列
+        2、不可变契约: 确保交付给 structlog.configure 的是一个不可被后续逻辑篡改的原子对象
+        3、类型安全: 明确标识该对象内包含的是符合 Callable[[...], Dict] 协议的处理器列表
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True
+    )
+
+    processors: List[Callable[[Any, str, Dict[str, Any]], Dict[str, Any]]] = Field(
+        ...,
+        description="已排序的处理器 Callable 列表",
+    )
+
+    def unwrap(self) -> List[Callable]:
+        """
+        解包获取原始处理器列表
+
+        :return: structlog 原生处理器列表
+        """
+        return self.processors

otel_declarative/Models/engine_states.py

@@ -0,0 +1,135 @@
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+from otel_declarative.Interfaces.extractor import IExtractor
+from otel_declarative.Engines.model_registry import ModelRegistry
+from otel_declarative.Engines.path_resolver import PathResolver
+from otel_declarative.Engines.object_hydrator import ObjectHydrator
+
+@dataclass(frozen=True)
+class ObservabilityEngineState:
+    """
+    观测引擎状态快照容器
+
+    职责:
+        1、聚合强耦合组件: 将模型注册中心、解析引擎、装配引擎和提取器实例打包为单一原子单元
+        2、支持无锁切换: 利用 python 的引用赋值原子性, 通过替换该容器实例实现无锁热重载
+        3、保证数据一致性: 确保在任何时刻提取逻辑所使用的模型定义与路径解析逻辑是完全匹配的
+    """
+    # --- 核心引擎组件 ---
+    model_registry: ModelRegistry = field(
+        metadata={"description": "负责 DTO 模型类定义的动态检索与管理"}
+    )
+
+    object_hydrator: ObjectHydrator = field(
+        metadata={"description": "负责将解析出的原始数据递归装配为强类型的 Pydantic 对象"}
+    )
+
+    path_resolver: PathResolver = field(
+        metadata={"description": "负责基于 JMESPath 表达式在业务上下文中检索并转换数据"}
+    )
+
+    # --- 策略分发容器 ---
+    extractors: Dict[str, IExtractor] = field(
+        default_factory=dict,
+        metadata={"description": "逻辑层级到具体提取器实例的映射表"}
+    )
+
+    # --- 运行状态标识 ---
+    is_ready: bool = field(
+        default=False,
+        metadata={"description": "标识当前状态快照是否已完成初始化并可投入生产使用"}
+    )
+
+    def get_extractor_for_layer(self, layer: str) -> Optional[IExtractor]:
+        """
+        [读操作] 从当前快照中安全获取指定层级的提取器
+
+        :param layer: 业务层级标识符
+        :return: 对应的提取器实例
+        """
+        if not self.is_ready:
+            return None
+
+        return self.extractors.get(layer)
+
+    @classmethod
+    def create_empty(cls) -> 'ObservabilityEngineState':
+        """
+        构造一个处于未就绪状态的初始占位状态对象
+
+        职责:
+            1、为 ExtractorFactory 提供系统引导初期的 Null-Object 实例
+            2、采样延迟导入方式加载引擎组件, 避免循环导入
+            3、使用空对象实例填充必填字段, 确保系统在未就绪状态下调用属性时不触发 AttributeError
+            4、锁定 is_ready = False, 令 get_extractor_for_layer 能够正常执行 fail-safe 拦截
+
+        :return: 处于未就绪状态的 ObservabilityEngineState 实例
+        """
+        from otel_declarative.Engines.model_registry import ModelRegistry
+        from otel_declarative.Engines.object_hydrator import ObjectHydrator
+        from otel_declarative.Engines.path_resolver import PathResolver
+        from otel_declarative.Engines.converter_registry import ConverterRegistry
+        from otel_declarative.settings import ObservabilitySettings
+
+        # 1、构造基础配置环境
+        default_settings: ObservabilitySettings = ObservabilitySettings()
+        # 2、构造底层空对象内核
+        empty_model_reg: ModelRegistry = ModelRegistry()
+        empty_conv_reg: ConverterRegistry = ConverterRegistry(default_settings)
+        empty_hydrator: ObjectHydrator = ObjectHydrator(empty_model_reg)
+        # 3、构造路径解析器占位符
+        empty_resolver: PathResolver = PathResolver(
+            converter_registry=empty_conv_reg,
+            object_hydrator=empty_hydrator,
+        )
+        return cls(
+            model_registry=empty_model_reg,
+            object_hydrator=empty_hydrator,
+            path_resolver=empty_resolver,
+            extractors={},
+            is_ready=False,
+        )
+
+    def __repr__(self) -> str:
+        """
+        提供可观测的调试信息
+
+        :return: 描述当前快照状态的字符串
+        """
+        status: str = "READY" if self.is_ready else "NOT_READY"
+        layers: list[str] = list(self.extractors.keys())
+        return f"<ObservabilityEngineState status={status} active_layers={layers}>"
+
+    def __post_init__(self) -> None:
+        """
+        数据一致性后验逻辑, 在 dataclass 实例化完成后自动触发 (由 PEP 557 定义)
+
+        职责:
+            1、验证核心引擎组件是否已注入
+            2、在构造函数执行到最后一行, 即将返回实例时, 强制执行组件连通性检查
+
+        :raises:
+            TypeError - 当核心引擎组件类型不匹配时抛出
+            ValueError - 当系统处于就绪状态单关键依赖缺失时抛出
+        """
+        required_components: list = [
+            ("model_registry", self.model_registry),
+            ("object_hydrator", self.object_hydrator),
+            ("path_resolver", self.path_resolver),
+        ]
+        for name, component in required_components:
+            if component is None:
+                raise ValueError(f"ObservabilityEngineState 初始化失败: 核心组件 '{name}' 为空")
+
+        if self.is_ready:
+            if not isinstance(self.extractors, dict):
+                raise TypeError("ObservabilityEngineState 就绪状态校验失败: 'extractors' 必须是 Dict 类型")
+
+            if not self.extractors:
+                from otel_declarative.Logging.logger_factory import get_child_logger
+                _audit_logger = get_child_logger("otel_declarative.Audit", "EngineState")
+                _audit_logger.warning(
+                    f"[otel_declarative Audit] 观测引擎快照已就绪, 但 'extractors' 规则映射表为空"
+                    f"系统将进入 '基础追踪模式'"
+                    f"仅会产生标准 OpenTelemetry Span，将无法动态提取和注入业务相关的 Attributes"
+                )

otel_declarative/Models/mapping_models.py

@@ -0,0 +1,111 @@
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field, ConfigDict, field_validator
+
+class FieldMapping(BaseModel):
+    """
+    单字段提取映射规则模型
+
+    职责:
+        1、定义数据提取的路径契约
+        2、定义路径失效时的回退机制
+        3、声明可选的数据清洗逻辑
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+        extra="ignore"
+    )
+
+    # --- 基础路径提取配置 ---
+    path: str = Field(
+        ...,
+        description="基于 JMESPath 标准的数据提取路径, 以 ExtractionSource 为起始点",
+        examples=["args.1.stream_id", "env.POD_NAME"]
+    )
+    default: Any = Field(
+        default=None,
+        description="路径解析失效时的默认回退值"
+    )
+
+    # --- 数据转换配置 ---
+    converter: Optional[str] = Field(
+        default=None,
+        description="关联在 ConverterRegistry 中的转换器标识符 (例如: 'to_int', 'to_upper', 'to_bool')"
+    )
+
+    # --- 递归装配配置 ---
+    model_name: Optional[str] = Field(
+        default=None,
+        description="关联在 ModelRegistry 中的自定义 Pydantic 模型类名, 若指定, 解析引擎将执行对象装配逻辑"
+    )
+
+    is_list: bool = Field(
+        default=False,
+        description="声明提取结果是否为对象列表, 若为 True, 引擎将对列表中的每个字典元素执行模型装配"
+    )
+
+    @field_validator("path")
+    @classmethod
+    def validate_path_syntax(cls, v: str) -> str:
+        """
+        验证器: 确保提取路径不为空且符合基础语法要求
+
+        :param v: 路径字符串
+        :return: 验证后的路径
+        :raises: ValueError - 当路径格式非法时抛出
+        """
+        if not v or not v.strip():
+            raise ValueError("提取路径 (path) 不能为空")
+
+        # TODO: 此处未来可扩展 JMESPath 语法的静态合规性预检查
+        return v.strip()
+
+    def __repr__(self) -> str:
+        """
+        提供更具可读性的调试输出格式
+        """
+        hydration_info = f" -> {self.model_name}" if self.model_name else ""
+        list_suffix = "[]" if self.is_list else ""
+        return f"<FieldMapping path='{self.path}'{hydration_info}{list_suffix} default={self.default}>"
+
+class LayerMappingRules(BaseModel):
+    """
+    分层提取规则聚合模型
+
+    职责:
+        1、聚合特定业务层级在全生命周期内的观测规则
+        2、分别定义输入阶段和输出阶段的提取契约
+        3、为 ExtractorFactory 提供标准化的配置输入
+    """
+    model_config = ConfigDict(frozen=True)
+
+    # 输入规则映射: 键名为 InputSummary 模型中的字段名, 值对应提取规则
+    input_rules: Dict[str, FieldMapping] = Field(
+        default_factory=dict,
+        description="InputSummary 的字段映射配置"
+    )
+    # 输出规则映射: 键名为 OutputSummary 模型中的字段名, 值位对应的提取规则
+    output_rules: Dict[str, FieldMapping] = Field(
+        default_factory=dict,
+        description="OutputSummary 的字段映射配置"
+    )
+
+    def __repr__(self) -> str:
+        """
+        提供更清晰的调试信息
+        """
+        return f"<LayerMappingRules input_fields={list(self.input_rules.keys())} output_fields={list(self.output_rules.keys())}>"
+
+    @property
+    def has_input_rules(self) -> bool:
+        """
+        判定是否存在输入提取定义
+        """
+        return len(self.input_rules) > 0
+
+    @property
+    def has_output_rules(self) -> bool:
+        """
+        判定是否存在输出提取定义
+        """
+        return len(self.output_rules) > 0

otel_declarative/Models/summary_models.py

@@ -0,0 +1,104 @@
+from typing import Optional, Any, Dict
+from pydantic import BaseModel, Field, ConfigDict
+
+class BaseSummary(BaseModel):
+    """
+    观测摘要基础模型
+
+    职责:
+        1、为所有派生的摘要 DTO 提供统一的 Pydantic 配置
+        2、强制执行不可变性, 确保观测数据在传递过程中不被篡改
+        3、支持别名映射和前向兼容性
+    """
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore", # 忽略解析过程中可能多出的冗余字段
+        frozen=True
+    )
+
+    def to_otel_attributes(self, prefix: str) -> Dict[str, Any]:
+        """
+        将模型数据转换为符合 OpenTelemetry 规范的扁平化属性字典
+
+        逻辑:
+            1、将模型序列化为原始字典
+            2、过滤所有 None 值, 避免在 Span 中产生空属性
+            3、为所有键名增加标准化的命名空间前缀
+
+        :param prefix: 属性命名空间前缀
+        :return: 经过前缀化处理的扁平化字典
+        """
+        raw_data = self.model_dump(exclude_none=True)
+        return {f"{prefix}{k}": v for k, v in raw_data.items()}
+
+class InputSummary(BaseSummary):
+    """
+    输入载体标准化摘要模型
+
+    职责:
+        1、承载从业务函数入口提取出的关键上下文
+        2、对应 OTel Span 的初始属性集
+    """
+    # 业务协议标识
+    command: Optional[str] = Field(
+        default=None,
+        description="业务通信协议定义的标准命令字"
+    )
+    # 业务唯一标识
+    stream_id: Optional[str] = Field(
+        default=None,
+        description="跨系统流转的唯一业务流标识符"
+    )
+    # 来源节点标识
+    pod_name: str = Field(
+        ...,
+        description="产生该观测数据的 K8s 计算节点名称",
+        min_length=1
+    )
+    # 数据载体名称
+    payload_type: str = Field(
+        default="Unknown",
+        description="运行时探测到的数据负载 Python 类型名称"
+    )
+
+    def to_otel_attributes(self, prefix: str = "input.") -> Dict[str, Any]:
+        """
+        重写父类方法, 锁定 'input.' 前缀语义
+
+        :param prefix: 默认为 'input.'
+        :return: 符合 OTel 规范的输入属性集
+        """
+        return super().to_otel_attributes(prefix)
+
+class OutputSummary(BaseSummary):
+    """
+    输出结果标准化摘要模型
+
+    职责:
+        1、承载业务逻辑处理完成后的反馈元数据
+        2、对应 OTel Span 结束前的状态补充属性
+    """
+    # 消息追踪锚点
+    message_sha: Optional[str] = Field(
+        default=None,
+        description="由边车生成的全局唯一消息哈希, 用于全链路 ID 锚定"
+    )
+    # 处理结果简述
+    result_brief: str = Field(
+        default="No detail provided",
+        description="处理结果的简要描述性信息"
+    )
+    # 转发状态标识
+    is_forwarded: bool = Field(
+        default=False,
+        description="标识该业务消息是否已成功转发至下游服务"
+    )
+
+    def to_otel_attributes(self, prefix: str = "output.") -> Dict[str, Any]:
+        """
+        重写父类方法, 锁定 'output.' 前缀语义
+
+        :param prefix: 默认为 'output.'
+        :return: 符合 OTel 规范的输出属性集
+        """
+        return super().to_otel_attributes(prefix)