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

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",
+]