aury-boot 0.0.29__py3-none-any.whl → 0.0.31__py3-none-any.whl

aury/boot/infrastructure/monitoring/health/__init__.py

@@ -0,0 +1,231 @@
+"""健康检查模块（待实现）。
+
+提供可插拔的健康检查功能，支持 Kubernetes 标准探针。
+
+TODO: 实现以下功能
+"""
+
+from __future__ import annotations
+
+# =============================================================================
+# 以下为伪代码，待实现
+# =============================================================================
+
+# from abc import ABC, abstractmethod
+# from enum import Enum
+# from typing import Literal
+# import asyncio
+# from dataclasses import dataclass, field
+#
+#
+# class ProbeType(str, Enum):
+#     """探针类型。"""
+#     LIVENESS = "liveness"    # 存活检查，失败会重启
+#     READINESS = "readiness"  # 就绪检查，失败从负载均衡移除
+#     STARTUP = "startup"      # 启动检查
+#
+#
+# @dataclass
+# class HealthCheck:
+#     """健康检查项。"""
+#     name: str
+#     check_func: Callable[[], Awaitable[None]]
+#     timeout: float = 5.0
+#     critical: bool = True  # 失败是否导致整体失败
+#
+#     async def run(self) -> tuple[str, bool, str | None]:
+#         """执行检查。
+#
+#         Returns:
+#             (name, success, error_message)
+#         """
+#         try:
+#             await asyncio.wait_for(self.check_func(), timeout=self.timeout)
+#             return (self.name, True, None)
+#         except asyncio.TimeoutError:
+#             return (self.name, False, f"Timeout after {self.timeout}s")
+#         except Exception as e:
+#             return (self.name, False, str(e))
+#
+#
+# @dataclass
+# class HealthResult:
+#     """健康检查结果。"""
+#     status: Literal["healthy", "unhealthy", "degraded"]
+#     checks: dict[str, dict] = field(default_factory=dict)
+#
+#
+# class HealthManager:
+#     """可插拔健康检查管理器。"""
+#
+#     _checks: dict[str, list[HealthCheck]] = {
+#         "liveness": [],
+#         "readiness": [],
+#         "startup": [],
+#     }
+#
+#     @classmethod
+#     def register(
+#         cls,
+#         name: str,
+#         probe: Literal["liveness", "readiness", "startup"] = "readiness",
+#         timeout: float = 5.0,
+#         critical: bool = True,
+#     ):
+#         """装饰器注册检查器。
+#
+#         用法:
+#             @HealthManager.register("database", probe="readiness")
+#             async def check_db():
+#                 await db.execute("SELECT 1")
+#
+#             @HealthManager.register("redis", probe="readiness", critical=False)
+#             async def check_redis():
+#                 await redis.ping()
+#
+#             @HealthManager.register("app", probe="liveness")
+#             async def check_app():
+#                 return True
+#         """
+#         def decorator(func):
+#             cls._checks[probe].append(
+#                 HealthCheck(name, func, timeout, critical)
+#             )
+#             return func
+#         return decorator
+#
+#     @classmethod
+#     async def check(
+#         cls,
+#         probe: str,
+#         detailed: bool = False,
+#     ) -> HealthResult:
+#         """执行指定探针的所有检查（并行+超时）。
+#
+#         Args:
+#             probe: 探针类型 (liveness/readiness/startup)
+#             detailed: 是否返回详细信息
+#
+#         Returns:
+#             HealthResult: 检查结果
+#         """
+#         checks = cls._checks.get(probe, [])
+#         if not checks:
+#             return HealthResult(status="healthy")
+#
+#         # 并行执行所有检查
+#         results = await asyncio.gather(
+#             *[c.run() for c in checks],
+#             return_exceptions=True
+#         )
+#
+#         # 汇总结果
+#         all_ok = True
+#         has_degraded = False
+#         check_results = {}
+#
+#         for check, result in zip(checks, results):
+#             if isinstance(result, Exception):
+#                 name, success, error = check.name, False, str(result)
+#             else:
+#                 name, success, error = result
+#
+#             check_results[name] = {
+#                 "status": "ok" if success else "error",
+#                 "error": error,
+#             }
+#
+#             if not success:
+#                 if check.critical:
+#                     all_ok = False
+#                 else:
+#                     has_degraded = True
+#
+#         if all_ok:
+#             status = "degraded" if has_degraded else "healthy"
+#         else:
+#             status = "unhealthy"
+#
+#         return HealthResult(
+#             status=status,
+#             checks=check_results if detailed else {},
+#         )
+#
+#     @classmethod
+#     def clear(cls) -> None:
+#         """清除所有注册的检查器。"""
+#         for probe in cls._checks:
+#             cls._checks[probe] = []
+#
+#
+# # =============================================================================
+# # 内置检查器
+# # =============================================================================
+#
+#
+# def register_database_check(db_manager) -> None:
+#     """注册数据库健康检查。"""
+#     @HealthManager.register("database", probe="readiness")
+#     async def check_database():
+#         await db_manager.health_check()
+#
+#
+# def register_cache_check(cache_manager) -> None:
+#     """注册缓存健康检查。"""
+#     @HealthManager.register("cache", probe="readiness", critical=False)
+#     async def check_cache():
+#         await cache_manager.get("__health__", default=None)
+#
+#
+# def register_redis_check(redis_client) -> None:
+#     """注册 Redis 健康检查。"""
+#     @HealthManager.register("redis", probe="readiness", critical=False)
+#     async def check_redis():
+#         await redis_client.ping()
+#
+#
+# # =============================================================================
+# # 路由注册（在 FoundationApp 中调用）
+# # =============================================================================
+#
+#
+# def setup_health_routes(app) -> None:
+#     """注册健康检查路由。
+#
+#     路由:
+#         GET /health/live   -> liveness checks
+#         GET /health/ready  -> readiness checks
+#         GET /health/startup -> startup checks
+#     """
+#     from fastapi import status
+#     from fastapi.responses import JSONResponse
+#
+#     @app.get("/health/live", tags=["health"])
+#     async def liveness():
+#         result = await HealthManager.check("liveness")
+#         return JSONResponse(
+#             content={"status": result.status},
+#             status_code=status.HTTP_200_OK if result.status == "healthy"
+#                 else status.HTTP_503_SERVICE_UNAVAILABLE,
+#         )
+#
+#     @app.get("/health/ready", tags=["health"])
+#     async def readiness():
+#         result = await HealthManager.check("readiness", detailed=True)
+#         return JSONResponse(
+#             content={"status": result.status, "checks": result.checks},
+#             status_code=status.HTTP_200_OK if result.status != "unhealthy"
+#                 else status.HTTP_503_SERVICE_UNAVAILABLE,
+#         )
+#
+#     @app.get("/health/startup", tags=["health"])
+#     async def startup():
+#         result = await HealthManager.check("startup")
+#         return JSONResponse(
+#             content={"status": result.status},
+#             status_code=status.HTTP_200_OK if result.status == "healthy"
+#                 else status.HTTP_503_SERVICE_UNAVAILABLE,
+#         )
+
+
+__all__: list[str] = []

aury/boot/infrastructure/monitoring/tracing/__init__.py

@@ -0,0 +1,55 @@
+"""OpenTelemetry 集成模块。
+
+提供 OpenTelemetry 遍测功能的封装，包括：
+- TracerProvider 配置和初始化
+- 自定义 SpanProcessor（用于触发告警）
+- trace_id 获取函数
+- 便捷的 span API
+- 日志告警集成
+
+使用方式：
+    # 自动集成（通过 TelemetryComponent）
+    TELEMETRY__ENABLED=true
+    
+    # 手动追踪
+    from aury.boot.infrastructure.monitoring.tracing import span, trace_span
+    
+    @trace_span(kind="llm", model="gpt-4")
+    async def call_llm(prompt: str):
+        ...
+    
+    with span("tool.search", kind="tool"):
+        result = await search()
+"""
+
+from __future__ import annotations
+
+from .context import get_otel_trace_id, is_otel_available
+from .logging import setup_otel_logging
+from .processor import AlertingSpanProcessor
+from .provider import TelemetryConfig, TelemetryProvider
+from .tracing import (
+    SpanKind,
+    set_span_attribute,
+    set_span_error,
+    span,
+    trace_span,
+)
+
+__all__ = [
+    # Provider
+    "AlertingSpanProcessor",
+    "TelemetryConfig",
+    "TelemetryProvider",
+    # Context
+    "get_otel_trace_id",
+    "is_otel_available",
+    # Tracing API
+    "SpanKind",
+    "set_span_attribute",
+    "set_span_error",
+    "span",
+    "trace_span",
+    # Logging
+    "setup_otel_logging",
+]

aury/boot/infrastructure/monitoring/tracing/context.py

@@ -0,0 +1,43 @@
+"""OpenTelemetry context 工具函数。
+
+提供从 OTel 获取 trace_id 的函数。
+"""
+
+from __future__ import annotations
+
+
+def is_otel_available() -> bool:
+    """检查 OpenTelemetry 是否可用。"""
+    try:
+        from opentelemetry import trace
+        return bool(trace)  # 确保引用被使用
+    except ImportError:
+        return False
+
+
+def get_otel_trace_id() -> str | None:
+    """从 OpenTelemetry 获取当前 trace_id。
+    
+    Returns:
+        str | None: 32 位十六进制 trace_id，如果不可用则返回 None
+    """
+    try:
+        from opentelemetry import trace
+        
+        span = trace.get_current_span()
+        if span and span.is_recording():
+            trace_id = span.get_span_context().trace_id
+            if trace_id:
+                return format(trace_id, "032x")
+    except ImportError:
+        pass
+    except Exception:
+        pass
+    
+    return None
+
+
+__all__ = [
+    "get_otel_trace_id",
+    "is_otel_available",
+]

aury/boot/infrastructure/monitoring/tracing/logging.py

@@ -0,0 +1,73 @@
+"""OTel Logs 集成。
+
+将 loguru 日志接入 OpenTelemetry，导出到 OTLP（Loki/Elasticsearch 等）。
+
+用法:
+    # 在 TelemetryComponent 中自动配置
+    TELEMETRY__LOGS_ENDPOINT=http://loki:3100
+    
+    # 或手动配置:
+    setup_otel_logging(endpoint="http://loki:3100")
+"""
+
+from __future__ import annotations
+
+import logging
+
+from aury.boot.common.logging import logger
+
+# OTel Logs 可选依赖
+try:
+    from opentelemetry._logs import set_logger_provider
+    from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+    from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+    from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+except ImportError:
+    OTLPLogExporter = None  # type: ignore[assignment, misc]
+
+
+def setup_otel_logging(
+    endpoint: str,
+    headers: dict[str, str] | None = None,
+) -> None:
+    """配置 OTel 日志集成。
+    
+    Args:
+        endpoint: OTLP 日志导出端点（如 http://loki:3100）
+        headers: OTLP 请求头（可选）
+    """
+    if OTLPLogExporter is None:
+        logger.debug("OTLP 日志导出器未安装")
+        return
+    
+    try:
+        # 创建 LoggerProvider
+        logger_provider = LoggerProvider()
+        set_logger_provider(logger_provider)
+        
+        # 添加 OTLP 导出器
+        exporter = OTLPLogExporter(
+            endpoint=endpoint,
+            headers=headers or None,
+        )
+        logger_provider.add_log_record_processor(
+            BatchLogRecordProcessor(exporter)
+        )
+        
+        # 添加标准 logging handler
+        logging_handler = LoggingHandler(
+            level="DEBUG",
+            logger_provider=logger_provider,
+        )
+        
+        # 配置 loguru 转发到标准 logging
+        logging.getLogger().addHandler(logging_handler)
+        
+        logger.info(f"Logs OTLP 导出器已配置: {endpoint}")
+    except Exception as e:
+        logger.warning(f"OTLP 日志导出配置失败: {e}")
+
+
+__all__ = [
+    "setup_otel_logging",
+]