otel-declarative 0.1.2__py3-none-any.whl

otel_declarative/Engines/model_registry.py

@@ -0,0 +1,90 @@
+import importlib
+import inspect
+from typing import Dict, Optional, Type, List
+from pydantic import BaseModel
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Engines", "ModelRegistry")
+
+class ModelRegistry:
+    """
+    业务观测模型注册中心
+
+    职责:
+        1、集中管理所有可用于声明式装配的 Pydantic 模型
+        2、实现从模型名称到类定义的动态检索, 支持配置驱动的对象实例化
+        3、提供自动发现机制, 减少手动注册的维护成本
+    """
+    def __init__(self):
+        self._models: Dict[str, Type[BaseModel]] = {}
+        self._manual_models: List[Type[BaseModel]] = []
+        self._is_initialized: bool = False
+
+    def register(self, model_class: Type[BaseModel]) -> None:
+        """
+        手动注册一个 Pydantic 模型类
+
+        :param model_class: 继承自 pydantic.BaseModel 的类定义
+        """
+        if not issubclass(model_class, BaseModel):
+            logger.warning(f"类 {model_class.__name__} 不是有效的 Pydantic BaseModel, 忽略注册")
+            return
+
+        model_name = model_class.__name__
+        self._models[model_name] = model_class
+
+        if model_class not in self._manual_models:
+            self._manual_models.append(model_class)
+
+        logger.debug(f"已手动注册观测模型: {model_name}")
+
+    def discover_models(self, module_paths: List[str]) -> None:
+        """
+        扫描指定模块路径下的所有 Pydantic 模型并注册
+
+        :param module_paths: 完整的 Python 模块路径列表 (例如 ['Core.Infrastructure.otel_declarative.Models'])
+        """
+        for path in module_paths:
+            try:
+                module = importlib.import_module(path)
+                for name, obj in inspect.getmembers(module, inspect.isclass):
+                    if issubclass(obj, BaseModel) and obj is not BaseModel:
+                        self._models[name] = obj
+                        logger.info(f"自动发现并注册观测模型: {name} (来自 {path})")
+            except ImportError:
+                logger.exception(f"无法导入模块执行模型自动发现: {path}")
+            except Exception:
+                logger.exception(f"模型自动发现过程中发生未预期异常")
+        self._is_initialized = True
+
+    def get_model(self, model_name: str) -> Optional[Type[BaseModel]]:
+        """
+        根据名称检索模型类定义
+
+        :param model_name: 模型类名
+        :return: Pydantic 类定义或 None
+        """
+        return self._models.get(model_name)
+
+    def list_registered_models(self) -> List[str]:
+        """
+        获取当前所有已注册模型的名称列表
+        """
+        return list(self._models.keys())
+
+    def get_manual_models(self) -> List[Type[BaseModel]]:
+        """
+        获取所有手动注册的模型类定义, 用于热重载快照
+
+        :return: 手动注册的模型类列表
+        """
+        return self._manual_models
+
+    def reset(self) -> None:
+        """
+        重置注册中心状态
+        """
+        self._models.clear()
+        self._manual_models.clear()
+        self._is_initialized = False
+        logger.info("模型注册中心已重置")

otel_declarative/Engines/object_hydrator.py

@@ -0,0 +1,126 @@
+import copy
+from pydantic import BaseModel, ValidationError
+from typing import Any, Optional, Type, TypeVar, Union, List, Set
+from otel_declarative.Engines.model_registry import ModelRegistry
+from otel_declarative.Models.mapping_models import FieldMapping
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Engines", "ObjectHydrator")
+
+T = TypeVar("T", bound=BaseModel)
+
+class ObjectHydrator:
+    """
+    对象装配引擎
+
+    职责:
+        1、模型检索: 根据规则从 ModelRegistry 获取类定义
+        2、结构映射: 将原始字典或列表转化为强类型 Pydantic 对象
+        3、熔断保护: 在装配失败时提供防御性降级, 确保不干扰主流程
+    """
+    def __init__(self, model_registry: ModelRegistry):
+        """
+        :param model_registry: 模型注册中心实例
+        """
+        self._model_registry = model_registry
+        self._reported_errors: Set[str] = set()
+
+    def hydrate(self, raw_data: Any, mapping: FieldMapping) -> Any:
+        """
+        执行声明式装配流
+
+        :param raw_data: 由解析内核提取出的原始数据片段
+        :param mapping: 包含装配指令的映射规则模型
+        :return: 实例化后的对象 / 列表, 或在失败时返回 mapping.default
+        """
+        # 1、前置校验: 若未声明 model_name, 则不执行装配
+        if not mapping.model_name:
+            return raw_data
+
+        # 2、检索模型类
+        model_class: Optional[Type[BaseModel]] = self._model_registry.get_model(mapping.model_name)
+        if not model_class:
+            logger.warning(f"装配异常 | 找不到已注册的模型: {mapping.model_name}")
+            return self._safe_get_default(mapping.default)
+
+        # 3、分发装配策略
+        try:
+            if mapping.is_list:
+                return self._hydrate_list(data=raw_data, model_class=model_class, default=mapping.default)
+            return self._hydrate_single(data=raw_data, model_class=model_class, default=mapping.default)
+        except Exception:
+            logger.exception(f"装配引擎执行崩溃, 出现未预期错误")
+            return self._safe_get_default(mapping.default)
+
+    def _hydrate_single(self, data: Any, model_class: Type[T], default: Any) -> Union[T, Any]:
+        """
+        执行单对象装配逻辑
+
+        :param data: 原始字典数据
+        :param model_class: 目标 Pydantic 类
+        :param default: 失败回退值
+        :return: 强类型实例
+        """
+        model_name: str = model_class.__name__
+
+        if not isinstance(data, dict):
+            logger.debug(f"装配失败 | 模型 {model_name} 需要字典, 但收到 {type(data).__name__}")
+            return self._safe_get_default(default)
+
+        try:
+            return model_class.model_validate(data)
+        except ValidationError as e:
+            fingerprint = f"{model_name}:{len(e.errors())}"
+            if fingerprint not in self._reported_errors:
+                logger.warning(f"模型校验不通过 | 模型: {model_name}", exc_info=True)
+                self._reported_errors.add(fingerprint)
+            return self._safe_get_default(default)
+
+    def _hydrate_list(self, data: Any, model_class: Type[T], default: Any) -> Union[List[T], Any]:
+        """
+        执行对象列表的循环迭代装配, 支持部分元素解析失败的容错机制
+
+        :param data: 原始列表数据
+        :param model_class: 目标 Pydantic 类
+        :param default: 回退失败值
+        :return: 强类型实例列表
+        """
+        # --- 1、前置类型守卫: 确保输出必须是列表, 否则立即执行断路回退 ---
+        if not isinstance(data, list):
+            logger.debug(f"装配失败 | 列表模式需要 list, 但收到 {type(data).__name__} | 路径已回退至默认值")
+            return self._safe_get_default(default)
+
+        # --- 2、容错迭代装配逻辑 ---
+        hydrated_list: List[T] = []
+        model_name: str = model_class.__name__
+        for index, item in enumerate(data):
+            if not isinstance(item, dict):
+                logger.warning(f"列表元素装配跳过 | 索引 {index} 处元素预期为 dict, 实际为 {type(item).__name__}")
+                continue
+
+            try:
+                # 执行 Pydantic 强类型校验与转换
+                hydrated_instance: T = model_class.model_validate(item)
+                hydrated_list.append(hydrated_instance)
+            except ValidationError as e:
+                error_count: int = len(e.errors())
+                fingerprint: str = f"{model_name}:list_err:{error_count}"
+                if fingerprint not in self._reported_errors:
+                    logger.warning(f"列表元素装配跳过 | 模型: {model_name} | 索引: {index}", exc_info=True)
+                self._reported_errors.add(fingerprint)
+
+        return hydrated_list
+
+    def _safe_get_default(self, default_value: Any) -> Any:
+        """
+        安全获取默认回退值, 针对可变对象执行深度复制以防止跨 Span 污染
+
+        :param default_value: 映射规则中定义的原始默认值
+        :return: 深度复制后的值或原始值
+        """
+        try:
+            if isinstance(default_value, (dict, list)):
+                return copy.deepcopy(default_value)
+            return default_value
+        except Exception:
+            return default_value

otel_declarative/Engines/path_resolver.py

@@ -0,0 +1,111 @@
+import os
+import jmespath
+from jmespath import exceptions
+from typing import Any, Dict
+from otel_declarative.Enums.extraction_source import ExtractionSource
+from otel_declarative.Models.mapping_models import FieldMapping
+from otel_declarative.Engines.converter_registry import ConverterRegistry
+from otel_declarative.Engines.object_hydrator import ObjectHydrator
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Engines", "PathResolver")
+
+class PathResolver:
+    """
+    路径解析引擎
+
+    职责:
+        1、基于 JMESPath 标准在业务上下文中定位原始数据
+        2、协调 ConverterRegistry 执行声明式的数据清洗与格式化
+        3、提供全链路熔断保护, 确保解析失败时安全回退至默认值
+    """
+
+    def __init__(self, converter_registry: ConverterRegistry, object_hydrator: ObjectHydrator):
+        """
+        :param converter_registry: 注入的转换器注册表实例
+        :param object_hydrator: 对象装配引擎
+        """
+        self._converter_registry = converter_registry
+        self._object_hydrator = object_hydrator
+        self._env_snapshot = dict(os.environ)
+        self._compiled_expressions: Dict[str, Any] = {}
+
+    def resolve(self, context: Dict[str, Any], mapping: FieldMapping) -> Any:
+        """
+        根据映射规则从执行上下文中解析目标值
+
+        :param context: 包含执行现场数据的字典
+        :param mapping: 强类型的字段映射规则模型
+        :return: 最终解析并转换后的值
+        """
+        try:
+            # 1、构造统一解析上下文
+            search_context: Dict[str, Any] = self._build_search_context(context)
+            # 2、调用 JMESPath 执行全量搜索
+            current_val: Any = self._apply_jmes_search(search_context, mapping.path)
+            if current_val is None:
+                return mapping.default
+
+            # 3、执行声明式转换与熔断保护
+            if mapping.converter:
+                current_val = self._converter_registry.convert(
+                    name=mapping.converter,
+                    value=current_val,
+                    default=mapping.default,
+                )
+            # 4、执行递归装配逻辑
+            if mapping.model_name and current_val is not None:
+                return self._object_hydrator.hydrate(
+                    raw_data=current_val,
+                    mapping=mapping
+                )
+            return current_val if current_val is not None else mapping.default
+        except Exception:
+            logger.exception(f"路径解析失败 | 路径: {mapping.path}")
+            return mapping.default
+
+    def _build_search_context(self, raw_context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        将零散的执行现场组装为统一的观测命名空间
+
+        :param raw_context: 装饰器捕获的原始上下文
+        :return: 扁平化的全量检索字典
+        """
+        # 预先提取位置参数以优化类型嗅探性能
+        args_raw: tuple = raw_context.get(ExtractionSource.ARGS.value, ())
+        args: list = list(args_raw) if args_raw is not None else []
+
+        return {
+            # 位置参数源
+            ExtractionSource.ARGS.value: args,
+            # 关键字参数源
+            ExtractionSource.KWARGS.value: raw_context.get(ExtractionSource.KWARGS.value, {}),
+            # 执行结果源
+            ExtractionSource.RESULTS.value: raw_context.get(ExtractionSource.RESULTS.value),
+            # 环境变量源
+            ExtractionSource.ENV.value: self._env_snapshot,
+            # 动态类型源
+            ExtractionSource.TYPE.value: {
+                "args": [type(a).__name__ for a in args] if args else [],
+            }
+        }
+
+    def _apply_jmes_search(self, root_obj: Any, expression: str) -> Any:
+        """
+        调用 JMESPath 库执行路径检索
+
+        :param root_obj: 搜索起始对象
+        :param expression: JMESPath 表达式
+        :return: 检索到的原始数据
+        """
+        if not expression:
+            return root_obj
+
+        try:
+            if expression not in self._compiled_expressions:
+                self._compiled_expressions[expression] = jmespath.compile(expression)
+            compiled_program = self._compiled_expressions[expression]
+            return compiled_program.search(root_obj)
+        except (exceptions.JMESPathError, Exception):
+            logger.exception(f"JMESPath 语法错误 | 表达式: {expression}")
+            return None

otel_declarative/Enums/converter_types.py

@@ -0,0 +1,42 @@
+from enum import Enum, unique
+
+@unique
+class ConverterCategory(str, Enum):
+    """
+    转换器逻辑分类
+    """
+    # 基础类型
+    PRIMITIVE = "primitive"
+    # 时间处理
+    TEMPORAL = "temporal"
+    # 格式化
+    FORMAT = "format"
+    # 结构重塑
+    STRUCTURAL = "structural"
+    # 语义校验
+    SEMANTIC = "semantic"
+
+@unique
+class StandardConverter(str, Enum):
+    """
+    标准转换器标识符
+    """
+    # Primitive
+    TO_STR = "to_str"
+    TO_INT = "to_int"
+    TO_BOOL = "to_bool"
+
+    # Temporal
+    TO_DATETIME = "to_datetime"
+    TO_TIMESTAMP = "to_timestamp"
+
+    # Format
+    HUMAN_SIZE = "human_size"
+    HUMAN_DURATION = "human_duration"
+
+    # Structural
+    GLOM_TRANSFORM = "glom_transform"
+
+    # Semantic
+    TO_IP = "to_ip"
+    TO_UUID = "to_uuid"

otel_declarative/Enums/extraction_source.py

@@ -0,0 +1,19 @@
+from enum import Enum, unique
+
+@unique
+class ExtractionSource(str, Enum):
+    """
+    提取来源枚举
+
+    定义路径解析引擎 (PathResolver) 可访问的顶级命名空间
+    """
+    # 函数位置参数列表 (元组)
+    ARGS = "args"
+    # 函数关键字参数字典
+    KWARGS = "kwargs"
+    # 业务函数执行后的返回值
+    RESULTS = "results"
+    # 系统环境变量 (os.environ)
+    ENV = "env"
+    # 对象的 Python 类型信息 (用于类型嗅探)
+    TYPE = "type"

otel_declarative/Factories/extractor_factory.py

@@ -0,0 +1,156 @@
+from typing import Any, Dict, Optional, List, Type
+from otel_declarative.Models.summary_models import BaseModel
+from otel_declarative.Models.engine_states import ObservabilityEngineState
+from otel_declarative.settings import ObservabilitySettings
+from otel_declarative.Config.extraction_config import ObservabilityMappingConfig
+from otel_declarative.Interfaces.extractor import IExtractor
+from otel_declarative.Engines.generic_extractor import GenericExtractor
+from otel_declarative.Engines.path_resolver import PathResolver
+from otel_declarative.Engines.converter_registry import ConverterRegistry
+from otel_declarative.Engines.model_registry import ModelRegistry
+from otel_declarative.Engines.object_hydrator import ObjectHydrator
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Factories", "ExtractorFactory")
+
+class ExtractorFactory:
+    """
+    元数据提取器策略工厂
+
+    职责:
+        1、依赖编排: 负责初始化并注入观测基础设施的所有依赖
+        2、策略管理: 实现基于逻辑层级的 GenericExtractor 实例生命周期维护
+        3、声明式驱动: 启动时加载 YAML 配置并预热所有层级的提取规则
+        4、零开销分发: 提供毫秒级的单例策略分发能力
+    """
+    def __init__(self, settings: ObservabilitySettings):
+        """
+        :param settings: 观测性全局配置对象
+        """
+        self._settings: ObservabilitySettings = settings
+        self._converter_registry: ConverterRegistry = ConverterRegistry(settings)
+        self._state: ObservabilityEngineState = ObservabilityEngineState.create_empty()
+        self._bootstrap_strategies()
+
+    def _bootstrap_strategies(self) -> None:
+        """
+        执行观测系统的启动引导流
+
+        职责:
+            1、扫描业务模型并预热注册中心
+            2、加载 YAML 映射配置
+            3、执行 Fail-safe 策略: 即使引导失败也不抛出异常, 确保主业务可用
+        """
+        try:
+            logger.info(f"正在引导观测性提取引擎策略")
+
+            # 构造影子组件
+            model_registry: ModelRegistry = ModelRegistry()
+            model_registry.discover_models(self._settings.model_scan_paths)
+            mapping_config: ObservabilityMappingConfig = ObservabilityMappingConfig.load_from_yaml(self._settings.mapping_config_path)
+            hydrator: ObjectHydrator = ObjectHydrator(model_registry)
+            resolver: PathResolver = PathResolver(converter_registry=self._converter_registry, object_hydrator=hydrator)
+
+            # 预热提取器实例映射
+            extractors: Dict[str, IExtractor] = {
+                layer_name: GenericExtractor(layer=layer_name, rules=rules, resolver=resolver)
+                for layer_name, rules in mapping_config.layer.items()
+            }
+
+            # 原子切换至就绪状态
+            self._state = ObservabilityEngineState(
+                model_registry=model_registry,
+                object_hydrator=hydrator,
+                path_resolver=resolver,
+                extractors=extractors,
+                is_ready=True
+            )
+            logger.info(f"观测性策略工厂引导完成，已就绪层级: {list(extractors.keys())}")
+        except Exception as e:
+            self._state = ObservabilityEngineState.create_empty()
+            logger.exception(
+                f"观测性策略工厂引导失败 | 错误原因: {str(e)} | 系统将进入 '零观测' 模式运行"
+            )
+
+    def get_extractor(self, layer: str, payload: Optional[Any] = None) -> Optional[IExtractor]:
+        """
+        [核心入口] 根据上下文获取匹配的提取器
+
+        :param layer: 装饰器声明的逻辑层级标识
+        :param payload: (可选) 运行时业务载体, 用于未来的动态启发式匹配
+        :return: 配置化的提取器实例, 若层级未定义则返回 None
+        """
+        current_snapshot: ObservabilityEngineState = self._state
+        return current_snapshot.get_extractor_for_layer(layer)
+
+    def reload(self) -> None:
+        """
+        执行观测策略的热重载逻辑
+
+        逻辑:
+            1、构造局部影子容器, 隔离重载过程中的中间状态
+            2、在影子容器中执行全量引导流 (模型发现 > 配置加载 > 实例预热)
+            3、校验成功后执行原子引用替换
+            4、若任何环节失败, 丢弃影子容器并保留原始引用, 确保旧策略完整
+        """
+        logger.info(f"观测性策略工厂正在尝试热重载")
+
+        old_state: ObservabilityEngineState = self._state
+        manual_models: List[Type[BaseModel]] = old_state.model_registry.get_manual_models()
+
+        try:
+            # --- 1、构造影子内核 ---
+            temp_model_registry: ModelRegistry = ModelRegistry()
+            temp_model_registry.discover_models(self._settings.model_scan_paths)
+            # 恢复手动注册的模型
+            for model_cls in manual_models:
+                temp_model_registry.register(model_cls)
+
+            # --- 2、加载并校验 YAML 规则 ---
+            mapping_config: ObservabilityMappingConfig = ObservabilityMappingConfig.load_from_yaml(
+                self._settings.mapping_config_path
+            )
+
+            # --- 3、组装影子解析链路 ---
+            temp_hydrator: ObjectHydrator = ObjectHydrator(temp_model_registry)
+            temp_resolver: PathResolver = PathResolver(converter_registry=self._converter_registry, object_hydrator=temp_hydrator)
+
+            # --- 4、预实例化所有提取器 ---
+            temp_extractors: Dict[str, IExtractor] = {
+                layer_name: GenericExtractor(layer=layer_name, rules=rules, resolver=temp_resolver)
+                for layer_name, rules in mapping_config.layer.items()
+            }
+
+            self._state = ObservabilityEngineState(
+                model_registry=temp_model_registry,
+                object_hydrator=temp_hydrator,
+                path_resolver=temp_resolver,
+                extractors=temp_extractors,
+                is_ready=True
+            )
+            logger.info(
+                f"观测性策略热重载成功，已动态更新层级: {list(temp_extractors.keys())}"
+                f"已注册模型数: {len(temp_model_registry.list_registered_models())}"
+            )
+        except Exception:
+            logger.exception(
+                f"观测性策略热重载失败 | "
+                f"操作建议: 请检查 YAML 语法或 Pydantic 模型定义 | 已执行 Fail-back，保留旧策略运行"
+            )
+
+    @property
+    def is_healthy(self) -> bool:
+        """
+        暴露工厂的运行健康状态
+        """
+        current_snapshot: ObservabilityEngineState = self._state
+        return current_snapshot.is_ready and len(current_snapshot.extractors) > 0
+
+    @property
+    def model_registry(self) -> ModelRegistry:
+        """
+        暴露当前活跃的模型注册中心引用
+
+        :return: 当前活跃的 ModelRegistry 实例
+        """
+        return self._state.model_registry