otel-declarative 0.1.2__py3-none-any.whl

otel_declarative/Config/extraction_config.py

@@ -0,0 +1,79 @@
+import os
+import yaml
+from typing import Dict, Any, Optional
+from pydantic import BaseModel, Field, ConfigDict, ValidationError
+from otel_declarative.Models.mapping_models import LayerMappingRules
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Config", "ObservabilityMappingConfig")
+
+class ObservabilityMappingConfig(BaseModel):
+    """
+    观测性映射全局配置模型
+
+    职责:
+        1、作为声明式规则的内存映射容器
+        2、聚合所有逻辑层级的数据提取规则
+        3、提供静态工厂方法, 支持从外部 YAML 文件初始化配置并进行强类型校验
+    """
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+        extra="ignore"
+    )
+
+    # 逻辑层及规则字典: 键名为业务 Layer 标识, 值为对应的提取规则集
+    layer: Dict[str, LayerMappingRules] = Field(
+        default_factory=dict,
+        description="业务层级到声明式提取规则的映射表"
+    )
+
+    @classmethod
+    def load_from_yaml(cls, file_path: str) -> "ObservabilityMappingConfig":
+        """
+        从指定路径的 YAML 文件加载并初始化配置对象
+
+        逻辑:
+            1、读取原始 YAML 文件内容
+            2、执行安全 YAML 解析
+            3、执行 Pydantic 级联校验
+
+        :param file_path: YAML 配置文件的绝对路径
+        :return: 经过校验后的 ObservabilityConfig 实例
+        """
+        # 路径合规性检查: 不抛出异常, 仅记录警告并回退
+        if not os.path.isabs(file_path):
+            logger.warning(f"映射配置文件路径不是绝对路径: {file_path}, 将回退至零规则模式")
+            return cls(layer={})
+
+        if not os.path.exists(file_path):
+            logger.warning(f"无法找到声明式映射配置文件: {file_path}, 将回退至零规则模式")
+            return cls(layer={})
+
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                raw_data: Optional[Dict[str, Any]] = yaml.safe_load(f)
+
+            if raw_data is None:
+                logger.warning(f"配置文件为空: {file_path}, 已初始化为零规则")
+                return cls(layer={})
+
+            return cls.model_validate(raw_data)
+        except (yaml.YAMLError, ValidationError):
+            logger.exception(
+                f"观测性配置校验/解析失败: {file_path}"
+                f"系统将自动回退至零规则模式"
+            )
+            return cls(layer={})
+        except Exception as e:
+            logger.exception(f"加载观测性配置时发生未预期异常, 已执行安全降级")
+            return cls(layer={})
+
+    def get_rules_for_layer(self, layer: str) -> Optional[LayerMappingRules]:
+        """
+        安全获取指定层级的提取规则集
+
+        :param layer: 逻辑层级标识符
+        :return: 对应的映射规则, 若未定义则返回 None
+        """
+        return self.layer.get(layer)

otel_declarative/Engines/Strategies/converter_strategies.py

@@ -0,0 +1,120 @@
+import decimal
+import ipaddress
+import pendulum
+import humanize
+import dateparser
+from glom import glom
+from dateparser.conf import Settings
+from typing import Any, Annotated, Final, cast
+from pydantic import TypeAdapter, BeforeValidator
+
+class ConverterStrategies:
+    """
+    转换策略静态工具集
+
+    职责:
+        1、封装无状态、纯函数式的标准转换逻辑
+        2、集成 Decimal、Pendulum、IpAddress 等专业库处理边缘情况
+        3、提供宽容与精确性并存的数据清洗能力
+    """
+
+    # --- 内部验证钩子 ---
+
+    @staticmethod
+    def _tolerant_int_pre_validator(v: Any) -> Any:
+        """
+        宽容整数预处理器
+
+        策略:
+            利用 Decimal 执行高精度截断操作, 避免 float 二进制近似带来的转换误差
+
+        :param v: 任意输入值
+        :return: 预处理后的整数或原始值
+        """
+        try:
+            if isinstance(v, (float, str)):
+                return int(decimal.Decimal(str(v)).to_integral_value(rounding=decimal.ROUND_DOWN))
+        except (ValueError, TypeError, decimal.InvalidOperation):
+            pass
+        return v
+
+    TolerantInt: Final = Annotated[int, BeforeValidator(_tolerant_int_pre_validator)]
+
+    # --- 公开策略方法 ---
+
+    @staticmethod
+    def to_string(value: Any) -> str:
+        """
+        策略: 强制转换为字符串
+        """
+        return TypeAdapter(str).validate_python(value)
+
+    @staticmethod
+    def to_int(value: Any) -> str:
+        """
+        策略: 强制转换为整数 (Decimal 高精度截断)
+
+        :raises: ValidationError
+        """
+        return TypeAdapter(ConverterStrategies.TolerantInt).validate_python(value)
+
+    @staticmethod
+    def to_bool(value: Any) -> bool:
+        """
+        策略: 强制转换为布尔值
+        """
+        return TypeAdapter(bool).validate_python(value)
+
+    @staticmethod
+    def to_datetime(value: Any, timezone: str = "UTC") -> Any:
+        """
+        策略: 转换为 datetime 对象 (混合引擎)
+
+        逻辑：
+            1、优先使用 Pendulum 库尝试精确解析 (RFC 3339 / ISO 8601)
+            2、若失败, 降级至 Dateparser 执行模糊自然语言推断
+
+        :param timezone: 模板时区名称
+        """
+        try:
+            dt = pendulum.parse(str(value), tz=timezone)
+            if isinstance(dt, pendulum.DateTime):
+                return dt
+        except Exception:
+            pass
+
+        # 降级至 Dateparse 模糊解析
+        settings_obj = Settings({"TO_TIMEZONE": timezone})
+        if isinstance(value, (int, float)):
+            return dateparser.parse(str(value), settings=cast(Any, settings_obj))
+        return dateparser.parse(value, settings=cast(Any, settings_obj))
+
+    @staticmethod
+    def to_ipv4(value: Any) -> str:
+        """
+        策略: 转换为标准 IPv4 字符串
+
+        :param value: IP 字符串或整数
+        :return: 标准点分十进制字符串
+        :raises: ValueError - 当 IP 格式非法时抛出
+        """
+        try:
+            return str(ipaddress.IPv4Address(value))
+        except ipaddress.AddressValueError as e:
+            raise ValueError(f"无效的 IPv4 地址：{value}") from e
+
+    @staticmethod
+    def human_size(value: Any) -> str:
+        """
+        策略: 转换为人性化字节大小
+        """
+        return humanize.naturalsize(value)
+
+    @staticmethod
+    def glom_transform(value: Any) -> Any:
+        """
+        策略: 执行 glom 结构变换
+        """
+        if isinstance(value, tuple) and len(value) == 2:
+            return glom(value[0], value[1])
+        return value

otel_declarative/Engines/converter_registry.py

@@ -0,0 +1,140 @@
+import dateparser
+import humanize
+from glom import glom
+from pydantic import TypeAdapter
+from typing import Any, Callable, Dict, Union, Set, Optional
+from otel_declarative.settings import ObservabilitySettings
+from otel_declarative.Enums.converter_types import StandardConverter
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Engines", "ConverterRegistry")
+
+class ConverterRegistry:
+    """
+    基于专业库集成的转换策略注册表
+
+    职责:
+        1、利用 dateparser, humanize, glom 等专业库处理复杂数据转换
+        2、利用 Pydantic TypeAdapter 实现类型强制转换与熔断
+        3、遵循 IoC 原则, 通过配置对象控制转换行为
+    """
+    def __init__(self, settings: ObservabilitySettings):
+        """
+        :param settings: 观测性全局配置对象
+        """
+        self._settings = settings
+        self._converters: Dict[str, Callable[[Any], Any]] = {}
+        # 异常指纹追踪集, 用于抑制重复的 WARNING 级日志输出
+        self._reported_errors: Set[str] = set()
+        self._setup_adapters()
+
+    def convert(self, name: str, value: Any, default: Any = None) -> Any:
+        """
+        执行受保护的声明式转换
+
+        :param name: 转换器名称 (来自 YAML 配置)
+        :param value: 原始数据
+        :param default: 失败时的回退值
+        """
+        if value is None:
+            return default
+
+        # 执行标准化匹配, 兼容 YAML 中的大小写差异
+        lookup_key = self._normalize_key(name)
+        adapter: Optional[Callable[[Any], Any]] = self._converters.get(lookup_key)
+
+        if not adapter:
+            return value
+
+        try:
+            result = adapter(value)
+            return result if result is not None else default
+        except Exception as e:
+            error_fingerprint: str = f"{lookup_key}:{type(e).__name__}"
+            if error_fingerprint not in self._reported_errors:
+                logger.warning(
+                    f"观测引擎断路器 | 转换器: {lookup_key} | "
+                    f"错误: {type(e).__name__} | 摘要: {str(e)} | "
+                    f"源数据快照: {str(value)[:100]}"
+                )
+                logger.debug(f"断路器触发堆栈 [{error_fingerprint}]", exc_info=True)
+                self._reported_errors.add(error_fingerprint)
+            return default
+
+    def _normalize_key(self, key: Union["StandardConverter", str]) -> str:
+        """
+        统一转换器标识符格式
+
+        将枚举成员或原始字符串转换为统一的查找键
+
+        :param key: 转换器标识符, 支持 StandardConverter 枚举或原始字符串
+        :return: 标准化后的字符串键
+        """
+        raw_key: str = key.value if hasattr(key, "value") else str(key)
+        return raw_key.strip().lower()
+
+    def _setup_adapters(self) -> None:
+        """
+        绑定标准转换器标识符至具体的专业库调用逻辑
+        """
+        # --- 1、基础类型适配 ---
+        self.register(StandardConverter.TO_STR, self._pydantic_adapter(str))
+        self.register(StandardConverter.TO_INT, self._pydantic_adapter(int))
+        self.register(StandardConverter.TO_BOOL, self._pydantic_adapter(bool))
+
+        # --- 2、时间处理适配 ---
+        if self._settings.enable_dateparser:
+            self.register(StandardConverter.TO_DATETIME, self._date_adapter)
+
+        # --- 3、格式化适配 ---
+        if self._settings.enable_humanize:
+            self.register(StandardConverter.HUMAN_SIZE, humanize.naturalsize)
+            self.register(StandardConverter.HUMAN_DURATION, humanize.precisedelta)
+
+        # --- 4、结构转换适配 ---
+        if self._settings.use_glom_spec:
+            self.register(StandardConverter.GLOM_TRANSFORM, self._glom_adapter)
+
+    def register(self, name: Union[StandardConverter, str], func: Callable[[Any], Any]) -> None:
+        """
+        注册转换器逻辑
+
+        :param name: 转换器标识
+        :param func: 具体的转换逻辑函数
+        """
+        if isinstance(name, StandardConverter):
+            lookup_key = self._normalize_key(name)
+        elif isinstance(name, str):
+            lookup_key = self._normalize_key(name)
+        else:
+            logger.error(f"无效的转换器名称类型：{type(name)}")
+            raise TypeError(f"无效的转换器名称类型：{type(name)}")
+
+        self._converters[lookup_key] = func
+        logger.debug(f"转换器注册成功：{lookup_key}")
+
+    # --- 专业库适配器闭包实现 ---
+
+    def _pydantic_adapter(self, target_type: type) -> Callable[[Any], Any]:
+        """
+        构造基于 Pydantic TypeAdapter 的类型强制转换内核
+        """
+        adapter = TypeAdapter(target_type)
+        return lambda v: adapter.validate_python(v)
+
+    def _date_adapter(self, value: Any) -> Any:
+        """
+        集成 dateparser 处理模糊时间字符串与时间戳
+        """
+        if isinstance(value, (int, float)):
+            return dateparser.parse(str(value), settings={'TO_TIMEZONE': self._settings.default_timezone})
+        return dateparser.parse(value, settings={'TO_TIMEZONE': self._settings.default_timezone})
+
+    def _glom_adapter(self, value: Any) -> Any:
+        """
+        利用 glom 执行声明式深层结构重塑
+        """
+        # 注意: 此处 value 预期为元组 (data) 或仅为 data
+        if isinstance(value, tuple) and len(value) == 2:
+            return glom(value[0], value[1])
+        return value

otel_declarative/Engines/generic_extractor.py

@@ -0,0 +1,96 @@
+from typing import Any, Dict, Optional, Type
+from otel_declarative.Interfaces.extractor import IExtractor
+from otel_declarative.Models.mapping_models import LayerMappingRules
+from otel_declarative.Models.summary_models import InputSummary, OutputSummary
+from otel_declarative.Engines.path_resolver import PathResolver
+from otel_declarative.Enums.extraction_source import ExtractionSource
+from otel_declarative.Logging.logger_factory import get_child_logger
+
+logger = get_child_logger("otel_declarative.Engines", "GenericExtractor")
+
+class GenericExtractor(IExtractor):
+    """
+    通用声明式提取器
+
+    职责:
+        1、流程编排: 按照声明式规则 (LayerMappingRules) 驱动路径解析引擎执行数据挖掘
+        2、数据归约: 将解析后的异构数据片段组装并校验为强类型的 DTO 模型
+        3、策略解耦: 自身不包含任何业务代码, 所有的提取逻辑由注入的映射规则决定
+    """
+    def __init__(self, layer: str, rules: LayerMappingRules, resolver: PathResolver):
+        """
+        :param layer: 当前提取器所属的逻辑层级标识符
+        :param rules: 存储在内存中的强类型提取规则映射表
+        :param resolver: 注入的路径解析引擎实例
+        """
+        self._layer: str = layer
+        self._rules: LayerMappingRules = rules
+        self._resolver: PathResolver = resolver
+
+    def extract_input(self, args: Any, kwargs: Any) -> InputSummary:
+        """
+        执行函数入口阶段的数据提取与模型装配
+
+        逻辑:
+            1、组装基础解析上下文
+            2、遍历 input_rules 委派 resolver 提取数据
+            3、执行属性自动补全与鲁棒性校验
+            4、生成强类型 InputSummary 实例
+
+        :param args: 业务函数的位置参数元组
+        :param kwargs: 业务函数的关键字参数字典
+        :return: 经过 Pydantic 校验的标准化输入摘要模型
+        """
+        # 1、构造统一的解析上下文命名空间
+        extraction_context: Dict[str, Any] = {
+            ExtractionSource.ARGS.value: args,
+            ExtractionSource.KWARGS.value: kwargs
+        }
+        # 2、遍历声明式规则执行数据收集
+        extracted_fields: Dict[str, Any] = {}
+        for field_name, mapping_rule in self._rules.input_rules.items():
+            # 委派解析引擎执行深度路径搜索与数据清洗
+            extracted_fields[field_name] = self._resolver.resolve(context=extraction_context, mapping=mapping_rule)
+
+        # 3、自动嗅探缺失的元数据
+        current_payload_type = extracted_fields.get("payload_type")
+        if not current_payload_type or current_payload_type == "Unknown":
+            if len(args) > 1:
+                # 按照约定, args[1] 通常为业务负载对象
+                extracted_fields["payload_type"] = type(args[1]).__name__
+            else:
+                extracted_fields["payload_type"] = "Unknown"
+
+        # 4、兜底
+        if not extracted_fields.get("pod_name"):
+            extracted_fields["pod_name"] = "unspecified-pod"
+
+        return InputSummary.model_validate(extracted_fields)
+
+    def extract_output(self, result: Any) -> OutputSummary:
+        """
+        执行函数返回阶段的数据提取与模型装配
+
+        :param result: 业务逻辑处理完成后的返回值对象
+        :return: 经过 Pydantic 校验的标准化输出摘要模型
+        """
+        # 1、构造结果阶段解析上下文
+        extraction_context: Dict[str, Any] = {
+            ExtractionSource.RESULTS.value: result
+        }
+        # 2、遍历输出映射规则, 执行数据收集
+        extracted_fields: Dict[str, Any] = {}
+        for field_name, mapping_rule in self._rules.output_rules.items():
+            extracted_fields[field_name] = self._resolver.resolve(context=extraction_context, mapping=mapping_rule)
+        # 3、执行最终模型校验
+        return OutputSummary.model_validate(extracted_fields)
+
+    def supports(self, layer: str, payload_type: Optional[Type[Any]] = None) -> bool:
+        """
+        判定当前实例是否能够支持指定的观测层级
+
+        :param layer: 装饰器传入的逻辑层级标识
+        :param payload_type: 运行时的 Payload 类型, 供动态嗅探使用
+        :return: 布尔值, 标识是否匹配
+        """
+        return self._layer == layer

otel_declarative/Engines/log_processors.py

@@ -0,0 +1,191 @@
+import os
+from typing import Any, Dict, List, Optional
+from opentelemetry import trace
+from otel_declarative.Models.Log.topology import InjectionLayer, RenamingLayer
+from otel_declarative.Models.Log.context import LogContext
+from otel_declarative.Models.Log.mapping import LogFieldMapping
+from otel_declarative.Models.Log.constants import FieldContract, ILogProcessor
+
+
+class OtelTraceContextProcessor:
+    """
+    OpenTelemetry 追踪上下文处理器
+
+    职责:
+        1、运行时提取: 从 OTel 全局上下文中动态挖取当前协程 / 线程活跃 Span 的 TraceID 与 SpanID
+        2、结构化注入: 按照配置对象定义的 Key 名将追踪标识注入日志字典
+        3、状态感知: 仅在存在有效活跃 Span 时执行注入, 否则保持事件字典完整性
+    """
+    def __init__(self, field_mapping: LogFieldMapping):
+        """
+        :param field_mapping: 字段重映射配置对象, 定义输出字典中的键名
+        """
+        self._mapping: LogFieldMapping = field_mapping
+
+    def __call__(self, logger: Any, method_name: str, event_dict: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        structlog 处理器核心入口
+
+        :param logger: 记录器实例
+        :param method_name: 日志级别方法名
+        :param event_dict: 当前待处理的日志事件字典
+        :return: 注入了 Trace 上下文后的事件字典
+        """
+        span = trace.get_current_span()
+
+        if span and span.get_span_context().is_valid:
+            span_context = span.get_span_context()
+            # 将 TraceID 和 SpanID 转换为标准 16 进制字符串
+            '''
+            1、在 OpenTelemetry Python SDK 的内部实现中, span_context.trace_id 和 span_context.span_id 是以 原始整数 (int) 形式存储的
+            TraceID 是一个 128 位的整数, SpanID 是一个 64 位的整数
+            如果直接将这些整数写入日志, 可观测性后端 (如 Jaeger, ELK, Grafana) 无法识别这种十进制格式，导致 '链路-日志' 关联失效
+            2、根据 W3C Trace Context 规范和 OpenTelemetry 标准: Trace ID 必须表示为 32 个字符的十六进制字符串 (小写), Span ID 必须表示为 16 个字符的十六进制字符串 (小写)
+            3、如果在此处将 TraceID 直接以 int 格式写入 JSON 日志, 在解析时会发生精度丢失, 导致日志中的 ID 变成一个近似值，从而彻底无法与追踪系统匹配
+            '''
+            event_dict.setdefault(self._mapping.trace_id, format(span_context.trace_id, "032x"))
+            event_dict.setdefault(self._mapping.span_id, format(span_context.span_id, "016x"))
+        return event_dict
+
+class ServiceMetadataProcessor:
+    """
+    服务身份元数据处理器
+
+    职责:
+        1、注入静态标识: 将服务名、运行环境等核心标识注入每行日志, 实现分布式环境下的身份溯源
+        2、K8S 现场捕获: 自动探测宿主 Pod 名称, 实现物理机与集群逻辑节点的关联
+        3、强类型一致: 使用 LogContext 模型作为注入数据的契约
+    """
+    def __init__(self, log_context: LogContext, field_mapping: LogFieldMapping):
+        """
+        :param log_context: 包含服务身份信息的强类型上下文模型
+        """
+        self._context: LogContext = log_context
+        self._mapping: LogFieldMapping = field_mapping
+        self._pod_name: str = getattr(self._context, "node_name", None) or os.getenv("HOSTNAME") or "unknown-node"
+
+    def __call__(self, logger: Any, method_name: str, event_dict: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        执行 structlog 的事件字典的元数据注入流水线
+
+        依据 structlog 处理器协议, 本方法在日志事件被渲染 / 输出前自动触发
+
+        负载将该服务实例的身份信息注入到事件上下文
+
+        :param logger: 当前活跃的结构化记录器实例
+        :param method_name: 触发日志生产的逻辑方法名称
+        :param event_dict: 当前待处理的结构化事件字典
+        :return: 经过元数据增强后的事件字典, 供流水线下游处理器继续处理
+        """
+        event_dict.setdefault(self._mapping.service, self._context.service_name)
+        event_dict.setdefault(self._mapping.environment, self._context.environment)
+        if self._pod_name:
+            event_dict.setdefault(self._mapping.pod_name, self._pod_name)
+
+        return event_dict
+
+class LogFieldRenamer:
+    """
+    日志标准字段重命名处理器
+
+    职责:
+        1、动态 Schema 映射: 基于配置模型定义的字段字段执行键名转换, 实现系统内部 Schema 与外部存储 Schema 的解耦
+        2、消除逻辑硬编码: 通过模型内省字段发现迁移目标
+        3、零配置扩展性: 当 LogFieldMapping 模型新增字段定义时, 该处理器无需修改代码即可自动支持新字段的重命名
+    """
+    def __init__(self, field_mapping: LogFieldMapping):
+        """
+        :param field_mapping: 字段重映射配置对象
+        """
+        self._mapping: LogFieldMapping = field_mapping
+        # 预计算动态迁移矩阵
+        # 格式: {'原始库输出键名': '用户定义输出键名'}  
+        self._migration_matrix: Dict[str, str] = {}
+        # [Fix 2026.01.17]: PydanticDeprecatedSince211: Accessing the 'model_fields' attribute on the instance is deprecated.
+        # 修复过时的 Pydantic v2 API 的使用方式
+        # 原代码: for field_name, field_info in self._mapping.model_fields.items():
+        for field_name, field_info in type(self._mapping).model_fields.items():
+            # 查找该字段关联的 FieldContract 契约对象
+            contract: Optional[FieldContract] = self._find_contract(field_info.metadata)
+            # 仅处理明确声明了可重命名契约的字段
+            if contract and contract.is_renamable and contract.source_key:
+                target_key: str = getattr(self._mapping, field_name)
+                if contract.source_key != target_key:
+                    self._migration_matrix[contract.source_key] = target_key
+
+    def __call__(self, logger: Any, method_name: str, event_dict: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        执行结构化日志字段的动态重命名映射
+
+        逻辑:
+            1、迭代预计算的迁移矩阵
+            2、安全检查: 判定当前事件字典是否包含待迁移的源键
+            3、原子操作: 利用 dict.pop 确保数据从旧键迁移到新键的过程不发生丢失
+
+        :param logger: structlog 记录器实例
+        :param method_name: 日志级别方法名
+        :param event_dict: 待处理的结构化日志事件字典
+        :return: 经过 Schema 映射转换后的事件字典
+        """
+        if not self._migration_matrix:
+            return event_dict
+
+        for source_key, target_key in self._migration_matrix.items():
+            if source_key in event_dict:
+                event_dict[target_key] = event_dict.pop(source_key)
+
+        return event_dict
+
+    def __repr__(self) -> str:
+        """
+        提供可调试的状态摘要
+        """
+        return f"<LogFieldRenamer matrix_size={len(self._migration_matrix)}>"
+
+    def _find_contract(self, metadata: List[Any]) -> Optional[FieldContract]:
+        """
+        从 Pydantic 字段元数据列表中检索 FieldContract 实例
+
+        :param metadata: Pydantic 字段的元数据列表
+        :return: 找到的契约对象
+        """
+        for item in metadata:
+            if isinstance(item, FieldContract):
+                return item
+        return None
+
+def get_otel_context_injectors(field_mapping: LogFieldMapping, log_context: LogContext) -> InjectionLayer:
+    """
+    获取 OTel 上下文注入处理器链
+
+    职责:
+        1、构建仅负责生产数据的处理器链 (Trace Context、Service Metadata)
+        2、作为 structlog 处理流水线的上游组件, 确保所有元数据在渲染前被注入
+        3、依赖注入: 将强类型的映射配置与上下文契约注入具体的处理器实例
+        4、利用 InjectionLayer 容器封装, 增强类型语义
+
+    :param field_mapping: 定义输出字段键名的映射配置对象
+    :param log_context: 包含服务身份信息的强类型上下文模型
+    :return: 包含处理器序列的注入层容器对象
+    """
+    processors: List[ILogProcessor] = [
+        OtelTraceContextProcessor(field_mapping=field_mapping),
+        ServiceMetadataProcessor(log_context=log_context, field_mapping=field_mapping),
+    ]
+    return InjectionLayer(processors=processors)
+
+def get_field_renamer_processor(field_mapping: LogFieldMapping) -> RenamingLayer:
+    """
+    获取字段重命名处理器工厂方法
+
+    职责:
+        1、构建仅负责修改键名的处理器
+        2、作为 structlog 处理流水线的末端组件, 确保在 EventRenamer 与 ExceptionFormatter 之后执行
+        3、隔离性: 独立于注入逻辑, 允许灵活调整其在处理器链中的拓扑位置
+        4、利用 RenamingLayer 容器封装, 增强类型语义
+
+    :param field_mapping: 包含 FieldContract 元数据契约的字段映射配置
+    :return: 符合 structlog Processor 协议的字段重命名处理器实例
+    """
+    processor = LogFieldRenamer(field_mapping=field_mapping)
+    return RenamingLayer(processor=processor)