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

aury/boot/infrastructure/monitoring/__init__.py

@@ -98,15 +98,18 @@ class SlowMethodDetectorComponent(MonitorComponent):
     """慢方法检测组件。
     
     检测执行时间超过阈值的方法并记录警告。
+    支持可选的告警通知（飞书/Webhook）。
     """
     
-    def __init__(self, threshold: float) -> None:
+    def __init__(self, threshold: float, *, alert: bool = False) -> None:
         """初始化慢方法检测组件。
         
         Args:
             threshold: 慢方法阈值（秒）
+            alert: 是否发送告警通知
         """
         self._threshold = threshold
+        self._alert = alert
     
     async def process(self, context: MonitorContext) -> None:
         """检测慢方法。
@@ -119,6 +122,156 @@ class SlowMethodDetectorComponent(MonitorComponent):
                 f"慢方法检测: {context.func_name} 执行时间 {context.duration:.3f}s "
                 f"(阈值: {self._threshold}s)"
             )
+            
+            # 发送告警通知
+            if self._alert:
+                await self._emit_alert(context)
+
+
+    async def _emit_alert(self, context: MonitorContext) -> None:
+        """发送慢方法告警。"""
+        try:
+            from aury.boot.infrastructure.monitoring.alerting import (
+                AlertEventType,
+                AlertSeverity,
+                emit_alert,
+            )
+            
+            await emit_alert(
+                AlertEventType.CUSTOM,
+                f"慢方法: {context.func_name}",
+                severity=AlertSeverity.WARNING,
+                source="service",
+                duration=context.duration,
+                threshold=self._threshold,
+                service=context.service_name,
+            )
+        except ImportError:
+            pass  # alerting 模块未加载
+        except Exception as e:
+            logger.debug(f"发送慢方法告警失败: {e}")
+
+
+# =============================================================================
+# HTTP 请求监控
+# =============================================================================
+
+
+async def monitor_http_request(
+    *,
+    method: str,
+    path: str,
+    duration: float,
+    status_code: int,
+    threshold: float = 1.0,
+    alert: bool = False,
+    trace_id: str = "",
+    exception: Exception | None = None,
+) -> None:
+    """监控 HTTP 请求。
+    
+    由 middleware 调用，统一处理 HTTP 请求的慢请求检测和告警。
+    
+    Args:
+        method: HTTP 方法
+        path: 请求路径
+        duration: 执行时间（秒）
+        status_code: 响应状态码
+        threshold: 慢请求阈值（秒）
+        alert: 是否发送告警
+        trace_id: 追踪 ID
+        exception: 异常对象（如果有）
+    """
+    # 慢请求检测和告警
+    if duration >= threshold:
+        if alert:
+            await _emit_http_slow_alert(
+                method=method,
+                path=path,
+                duration=duration,
+                threshold=threshold,
+                trace_id=trace_id,
+            )
+    
+    # 异常告警
+    if exception is not None and alert:
+        await _emit_http_exception_alert(
+            method=method,
+            path=path,
+            duration=duration,
+            exception=exception,
+            trace_id=trace_id,
+        )
+
+
+async def _emit_http_slow_alert(
+    method: str,
+    path: str,
+    duration: float,
+    threshold: float,
+    trace_id: str,
+) -> None:
+    """发送 HTTP 慢请求告警。"""
+    try:
+        from aury.boot.infrastructure.monitoring.alerting import (
+            AlertEventType,
+            AlertSeverity,
+            emit_alert,
+        )
+        
+        await emit_alert(
+            AlertEventType.SLOW_REQUEST,
+            f"慢请求: {method} {path}",
+            severity=AlertSeverity.WARNING,
+            trace_id=trace_id,
+            source="api",
+            duration=duration,
+            threshold=threshold,
+            endpoint=path,
+            method=method,
+        )
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.debug(f"发送慢请求告警失败: {e}")
+
+
+async def _emit_http_exception_alert(
+    method: str,
+    path: str,
+    duration: float,
+    exception: Exception,
+    trace_id: str,
+) -> None:
+    """发送 HTTP 异常告警。"""
+    try:
+        from aury.boot.infrastructure.monitoring.alerting import (
+            AlertEventType,
+            AlertSeverity,
+            emit_alert,
+        )
+        
+        await emit_alert(
+            AlertEventType.EXCEPTION,
+            f"请求异常: {method} {path} - {type(exception).__name__}: {exception}",
+            severity=AlertSeverity.ERROR,
+            trace_id=trace_id,
+            source="api",
+            duration=duration,
+            endpoint=path,
+            method=method,
+            error_type=type(exception).__name__,
+            error_message=str(exception),
+        )
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.debug(f"发送异常告警失败: {e}")
+
+
+# =============================================================================
+# Service 方法监控组件
+# =============================================================================
 
 
 class StandardMetricsReporterComponent(MonitorComponent):
@@ -172,8 +325,17 @@ class ErrorReporterComponent(MonitorComponent):
     """错误报告组件。
     
     报告方法执行失败的错误信息。
+    支持可选的告警通知（飞书/Webhook）。
     """
     
+    def __init__(self, *, alert: bool = False) -> None:
+        """初始化错误报告组件。
+        
+        Args:
+            alert: 是否发送告警通知
+        """
+        self._alert = alert
+    
     async def process(self, context: MonitorContext) -> None:
         """报告错误信息。
         
@@ -186,6 +348,34 @@ class ErrorReporterComponent(MonitorComponent):
                 f"执行时间: {context.duration:.3f}s | "
                 f"异常: {type(context.exception).__name__}: {context.exception}"
             )
+            
+            # 发送告警通知
+            if self._alert:
+                await self._emit_alert(context)
+    
+    async def _emit_alert(self, context: MonitorContext) -> None:
+        """发送异常告警。"""
+        try:
+            from aury.boot.infrastructure.monitoring.alerting import (
+                AlertEventType,
+                AlertSeverity,
+                emit_alert,
+            )
+            
+            await emit_alert(
+                AlertEventType.EXCEPTION,
+                f"方法异常: {context.func_name}",
+                severity=AlertSeverity.ERROR,
+                source="service",
+                duration=context.duration,
+                service=context.service_name,
+                exception_type=type(context.exception).__name__,
+                exception_message=str(context.exception),
+            )
+        except ImportError:
+            pass  # alerting 模块未加载
+        except Exception as e:
+            logger.debug(f"发送异常告警失败: {e}")
 
 
 class MonitorPipeline:
@@ -278,19 +468,22 @@ class MonitorPipelineBuilder:
     def with_slow_detector(
         self,
         threshold: float = 1.0,
+        *,
+        alert: bool = False,
         detector: SlowMethodDetectorComponent | None = None,
     ) -> MonitorPipelineBuilder:
         """添加慢方法检测组件。
         
         Args:
             threshold: 慢方法阈值（秒）
+            alert: 是否发送告警通知
             detector: 慢方法检测组件，如果为 None 则创建新实例
         
         Returns:
             MonitorPipelineBuilder: 构建器实例（支持链式调用）
         """
         if detector is None:
-            detector = SlowMethodDetectorComponent(threshold)
+            detector = SlowMethodDetectorComponent(threshold, alert=alert)
         self._components.append(detector)
         return self
     
@@ -318,18 +511,21 @@ class MonitorPipelineBuilder:
     
     def with_error_reporter(
         self,
+        *,
+        alert: bool = False,
         reporter: ErrorReporterComponent | None = None,
     ) -> MonitorPipelineBuilder:
         """添加错误报告组件。
         
         Args:
+            alert: 是否发送告警通知
             reporter: 错误报告组件，如果为 None 则创建新实例
         
         Returns:
             MonitorPipelineBuilder: 构建器实例（支持链式调用）
         """
         if reporter is None:
-            reporter = ErrorReporterComponent()
+            reporter = ErrorReporterComponent(alert=alert)
         self._components.append(reporter)
         return self
     
@@ -370,6 +566,7 @@ def monitor(
     slow_threshold: float = 1.0,
     metrics: bool = True,
     prometheus_format: bool = False,
+    alert: bool = False,
     pipeline: MonitorPipeline | None = None,
     components: list[MonitorComponent] | None = None,
     pipeline_builder: Callable[[], MonitorPipeline] | None = None,
@@ -377,13 +574,14 @@ def monitor(
     """服务层性能监控装饰器。
     
     监控服务方法的执行时间和调用次数。
-    支持慢方法警告和 Prometheus 格式导出。
+    支持慢方法警告、Prometheus 格式导出和告警通知。
     支持自定义监控管道和组件。
     
     Args:
         slow_threshold: 慢方法阈值（秒），默认 1.0 秒
         metrics: 是否记录指标（执行时间、调用次数），默认 True
         prometheus_format: 是否使用 Prometheus 格式记录指标，默认 False
+        alert: 是否发送告警通知（飞书/Webhook），默认 False
         pipeline: 自定义监控管道，如果提供则忽略其他参数
         components: 自定义组件列表，如果提供则使用这些组件构建管道
         pipeline_builder: 自定义管道构建函数，如果提供则使用此函数构建管道
@@ -395,6 +593,12 @@ def monitor(
             async def create_user(self, data: dict):
                 return await self.user_repo.create(data)
         
+        # 启用告警通知
+        class PaymentService(BaseService):
+            @monitor(slow_threshold=0.5, alert=True)
+            async def process_payment(self, order_id: str):
+                ...
+        
         # 使用自定义组件
         custom_component = MyCustomMonitorComponent()
         @monitor(components=[custom_component])
@@ -441,12 +645,12 @@ def monitor(
         if metrics:
             builder.with_call_counter()
         
-        builder.with_slow_detector(threshold=slow_threshold)
+        builder.with_slow_detector(threshold=slow_threshold, alert=alert)
         
         if metrics:
             builder.with_metrics_reporter(prometheus_format=prometheus_format)
         
-        builder.with_error_reporter()
+        builder.with_error_reporter(alert=alert)
         
         monitor_pipeline = builder.build()
     

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

@@ -0,0 +1,50 @@
+"""告警系统模块。
+
+提供企业级告警通知功能：
+- 慢请求、慢SQL、异常自动告警
+- 累计触发和抑制机制
+- 可扩展的通知渠道（内置飞书、Webhook）
+
+快速开始：
+    1. 配置环境变量
+        ALERT_ENABLED=true
+        ALERT_NOTIFIER_FEISHU_WEBHOOK=https://open.feishu.cn/...
+    
+    2. 在应用启动时初始化（FoundationApp 自动处理）
+    
+    3. 可选：添加规则文件 alert_rules.yaml
+
+使用便捷函数发送自定义告警：
+    from aury.boot.infrastructure.monitoring.alerting import emit_alert, AlertEventType
+    
+    await emit_alert(
+        AlertEventType.CUSTOM,
+        "自定义告警消息",
+        severity=AlertSeverity.WARNING,
+        my_data="xxx",
+    )
+"""
+
+from .aggregator import AlertAggregator
+from .events import AlertEvent, AlertEventType, AlertNotification, AlertSeverity
+from .manager import AlertManager, emit_alert
+from .notifiers import AlertNotifier, FeishuNotifier, WebhookNotifier
+from .rules import AlertRule, load_rules_from_dict
+
+__all__ = [
+    # 核心类
+    "AlertAggregator",
+    "AlertEvent",
+    "AlertEventType",
+    "AlertManager",
+    "AlertNotification",
+    "AlertRule",
+    "AlertSeverity",
+    # 通知器
+    "AlertNotifier",
+    "FeishuNotifier",
+    "WebhookNotifier",
+    # 便捷函数
+    "emit_alert",
+    "load_rules_from_dict",
+]

aury/boot/infrastructure/monitoring/alerting/aggregator.py

@@ -0,0 +1,193 @@
+"""告警聚合器。
+
+实现累计触发和抑制逻辑：
+- 滑动窗口计数：在窗口时间内达到阈值才触发
+- 抑制机制：相同告警在抑制时间内不重复发送
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .events import AlertEvent
+
+
+@dataclass
+class AggregationState:
+    """单个指纹的聚合状态。"""
+    
+    fingerprint: str
+    
+    # 滑动窗口内的事件时间戳
+    event_timestamps: deque[datetime] = field(default_factory=deque)
+    
+    # 最后一次发送告警的时间
+    last_alert_time: datetime | None = None
+    
+    # 聚合的 trace_id 列表（最多保留 5 个）
+    trace_ids: deque[str] = field(default_factory=lambda: deque(maxlen=5))
+    
+    # 窗口内事件总数（用于通知）
+    window_count: int = 0
+
+
+class AlertAggregator:
+    """告警聚合器。
+    
+    实现两层控制：
+    1. 累计触发：窗口时间内达到阈值才触发告警
+    2. 抑制机制：触发后的抑制时间内不重复发送
+    
+    示例：
+        aggregator = AlertAggregator(
+            window_seconds=60,      # 1 分钟窗口
+            threshold=5,            # 5 次触发
+            suppress_seconds=300,   # 5 分钟抑制
+        )
+        
+        if aggregator.should_alert(event):
+            # 发送告警
+            ...
+    """
+    
+    def __init__(
+        self,
+        window_seconds: int = 60,
+        threshold: int = 1,
+        suppress_seconds: int = 300,
+    ) -> None:
+        """初始化聚合器。
+        
+        Args:
+            window_seconds: 滑动窗口大小（秒）
+            threshold: 窗口内触发阈值
+            suppress_seconds: 告警抑制时间（秒）
+        """
+        self.window_seconds = window_seconds
+        self.threshold = threshold
+        self.suppress_seconds = suppress_seconds
+        
+        self._states: dict[str, AggregationState] = {}
+        self._lock = threading.Lock()
+    
+    def should_alert(self, event: "AlertEvent") -> bool:
+        """判断是否应该触发告警。
+        
+        Args:
+            event: 告警事件
+        
+        Returns:
+            bool: 是否应该发送告警
+        """
+        fingerprint = event.fingerprint
+        now = event.timestamp
+        
+        with self._lock:
+            # 获取或创建状态
+            if fingerprint not in self._states:
+                self._states[fingerprint] = AggregationState(fingerprint=fingerprint)
+            
+            state = self._states[fingerprint]
+            
+            # 清理过期的时间戳
+            window_start = now - timedelta(seconds=self.window_seconds)
+            while state.event_timestamps and state.event_timestamps[0] < window_start:
+                state.event_timestamps.popleft()
+            
+            # 添加当前事件
+            state.event_timestamps.append(now)
+            state.trace_ids.append(event.trace_id)
+            state.window_count = len(state.event_timestamps)
+            
+            # 检查是否达到阈值
+            if state.window_count < self.threshold:
+                return False
+            
+            # 检查是否在抑制期内
+            if state.last_alert_time:
+                suppress_until = state.last_alert_time + timedelta(seconds=self.suppress_seconds)
+                if now < suppress_until:
+                    return False
+            
+            # 触发告警，更新最后告警时间
+            state.last_alert_time = now
+            return True
+    
+    def get_state(self, fingerprint: str) -> AggregationState | None:
+        """获取指纹的聚合状态。
+        
+        Args:
+            fingerprint: 事件指纹
+        
+        Returns:
+            聚合状态，如果不存在返回 None
+        """
+        with self._lock:
+            return self._states.get(fingerprint)
+    
+    def get_aggregation_info(self, event: "AlertEvent") -> dict:
+        """获取聚合信息（用于告警通知）。
+        
+        Args:
+            event: 告警事件
+        
+        Returns:
+            包含聚合信息的字典
+        """
+        state = self.get_state(event.fingerprint)
+        if not state:
+            return {
+                "count": 1,
+                "trace_ids": [event.trace_id],
+            }
+        
+        return {
+            "count": state.window_count,
+            "trace_ids": list(state.trace_ids),
+        }
+    
+    def reset(self, fingerprint: str | None = None) -> None:
+        """重置聚合状态。
+        
+        Args:
+            fingerprint: 指定指纹，如果为 None 则重置所有
+        """
+        with self._lock:
+            if fingerprint:
+                self._states.pop(fingerprint, None)
+            else:
+                self._states.clear()
+    
+    def cleanup_expired(self) -> int:
+        """清理过期的状态。
+        
+        返回清理的状态数量。
+        """
+        now = datetime.now()
+        expire_time = now - timedelta(seconds=self.window_seconds + self.suppress_seconds)
+        
+        cleaned = 0
+        with self._lock:
+            to_remove = []
+            for fp, state in self._states.items():
+                # 如果窗口为空且已过抑制期，可以清理
+                if not state.event_timestamps:
+                    if not state.last_alert_time or state.last_alert_time < expire_time:
+                        to_remove.append(fp)
+            
+            for fp in to_remove:
+                del self._states[fp]
+                cleaned += 1
+        
+        return cleaned
+
+
+__all__ = [
+    "AggregationState",
+    "AlertAggregator",
+]

aury/boot/infrastructure/monitoring/alerting/events.py

@@ -0,0 +1,141 @@
+"""告警事件定义。
+
+定义告警事件类型、严重级别和事件数据结构。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+import hashlib
+
+
+class AlertEventType(str, Enum):
+    """告警事件类型。"""
+    
+    SLOW_REQUEST = "slow_request"       # 慢请求
+    SLOW_SQL = "slow_sql"               # 慢 SQL
+    EXCEPTION = "exception"             # 异常
+    TASK_FAILURE = "task_failure"       # 任务失败
+    TASK_TIMEOUT = "task_timeout"       # 任务超时
+    CUSTOM = "custom"                   # 自定义
+
+
+class AlertSeverity(str, Enum):
+    """告警严重级别。"""
+    
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class AlertEvent:
+    """告警事件。
+    
+    包含告警的所有上下文信息。
+    """
+    
+    event_type: AlertEventType
+    severity: AlertSeverity
+    message: str
+    trace_id: str
+    
+    source: str = "unknown"           # api / scheduler / task
+    service_name: str = ""            # 服务名
+    timestamp: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    # 用于聚合/去重的指纹（相同指纹的事件会被聚合）
+    _fingerprint: str | None = field(default=None, repr=False)
+    
+    @property
+    def fingerprint(self) -> str:
+        """获取事件指纹。
+        
+        相同指纹的事件会被聚合处理。
+        """
+        if self._fingerprint:
+            return self._fingerprint
+        
+        # 默认指纹：类型 + 来源 + 关键元数据
+        key_parts = [
+            self.event_type.value,
+            self.source,
+            self.metadata.get("endpoint", ""),
+            self.metadata.get("task_name", ""),
+            self.metadata.get("error_type", ""),
+        ]
+        key_str = ":".join(str(p) for p in key_parts if p)
+        return hashlib.md5(key_str.encode()).hexdigest()[:16]
+    
+    @fingerprint.setter
+    def fingerprint(self, value: str) -> None:
+        self._fingerprint = value
+    
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典。"""
+        return {
+            "event_type": self.event_type.value,
+            "severity": self.severity.value,
+            "message": self.message,
+            "trace_id": self.trace_id,
+            "source": self.source,
+            "service_name": self.service_name,
+            "timestamp": self.timestamp.isoformat(),
+            "metadata": self.metadata,
+            "fingerprint": self.fingerprint,
+        }
+
+
+@dataclass
+class AlertNotification:
+    """告警通知（发送给 Notifier 的数据）。
+    
+    包含聚合后的告警信息。
+    """
+    
+    title: str
+    message: str
+    severity: AlertSeverity
+    event_type: AlertEventType
+    source: str
+    service_name: str
+    
+    # 聚合信息
+    count: int = 1                    # 聚合的事件数量
+    first_timestamp: datetime = field(default_factory=datetime.now)
+    last_timestamp: datetime = field(default_factory=datetime.now)
+    
+    # 关联的 trace_id 列表（最多保留最近几个）
+    trace_ids: list[str] = field(default_factory=list)
+    
+    # 额外元数据
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典。"""
+        return {
+            "title": self.title,
+            "message": self.message,
+            "severity": self.severity.value,
+            "event_type": self.event_type.value,
+            "source": self.source,
+            "service_name": self.service_name,
+            "count": self.count,
+            "first_timestamp": self.first_timestamp.isoformat(),
+            "last_timestamp": self.last_timestamp.isoformat(),
+            "trace_ids": self.trace_ids,
+            "metadata": self.metadata,
+        }
+
+
+__all__ = [
+    "AlertEvent",
+    "AlertEventType",
+    "AlertNotification",
+    "AlertSeverity",
+]