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

aury/boot/infrastructure/monitoring/alerting/notifiers/feishu.py

@@ -0,0 +1,209 @@
+"""飞书通知器。
+
+通过飞书机器人 Webhook 发送告警通知。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from aury.boot.common.logging import logger
+
+from .base import AlertNotifier
+
+if TYPE_CHECKING:
+    from ..events import AlertNotification
+
+
+class FeishuNotifier(AlertNotifier):
+    """飞书机器人通知器。
+    
+    通过飞书自定义机器人 Webhook 发送告警。
+    支持签名校验（可选）。
+    
+    环境变量配置示例：
+        ALERT_NOTIFIER_FEISHU_TYPE=feishu
+        ALERT_NOTIFIER_FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
+        ALERT_NOTIFIER_FEISHU_SECRET=xxx  # 可选，签名密钥
+    """
+    
+    def __init__(self, webhook: str, secret: str | None = None) -> None:
+        """初始化飞书通知器。
+        
+        Args:
+            webhook: 飞书机器人 Webhook URL
+            secret: 签名密钥（可选）
+        """
+        self.webhook = webhook
+        self.secret = secret
+    
+    @classmethod
+    def from_config(cls, config: dict) -> "FeishuNotifier":
+        """从配置创建实例。"""
+        webhook = config.get("webhook")
+        if not webhook:
+            raise ValueError("飞书通知器配置缺少 webhook")
+        return cls(webhook=webhook, secret=config.get("secret"))
+    
+    def _generate_sign(self, timestamp: int) -> str:
+        """生成签名。
+        
+        飞书签名算法：
+        sign = base64(hmac-sha256(timestamp + "\\n" + secret, secret))
+        """
+        if not self.secret:
+            return ""
+        
+        string_to_sign = f"{timestamp}\n{self.secret}"
+        hmac_code = hmac.new(
+            string_to_sign.encode("utf-8"),
+            digestmod=hashlib.sha256,
+        ).digest()
+        return base64.b64encode(hmac_code).decode("utf-8")
+    
+    def _build_message(self, notification: "AlertNotification") -> dict[str, Any]:
+        """构建飞书消息体。
+        
+        使用 JSON 2.0 卡片格式，支持完整的 markdown 语法。
+        """
+        # 颜色映射
+        color_map = {
+            "info": "blue",
+            "warning": "yellow",
+            "error": "red",
+            "critical": "red",
+        }
+        color = color_map.get(notification.severity.value, "grey")
+        
+        # 构建详情列表
+        details = []
+        
+        # 基本信息
+        details.append(f"**服务**: {notification.service_name or '未知'}")
+        details.append(f"**来源**: {notification.source}")
+        details.append(f"**类型**: {notification.event_type.value}")
+        
+        # 时间信息
+        details.append(f"**时间**: {notification.last_timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+        
+        # 聚合信息
+        if notification.count > 1:
+            details.append(f"**触发次数**: {notification.count} 次")
+        
+        # Trace ID
+        if notification.trace_ids:
+            trace_str = ", ".join(notification.trace_ids[:3])
+            if len(notification.trace_ids) > 3:
+                trace_str += f" ... (共{len(notification.trace_ids)}个)"
+            details.append(f"**Trace ID**: {trace_str}")
+        
+        # 元数据（排除 SQL 和堆栈，它们单独处理）
+        sql_content: str | None = None
+        stacktrace_content: str | None = None
+        
+        if notification.metadata:
+            if "duration" in notification.metadata:
+                details.append(f"**耗时**: {notification.metadata['duration']:.3f}s")
+            if "endpoint" in notification.metadata:
+                details.append(f"**接口**: {notification.metadata['endpoint']}")
+            if "error_type" in notification.metadata:
+                details.append(f"**错误类型**: {notification.metadata['error_type']}")
+            if "error_message" in notification.metadata:
+                details.append(f"**错误信息**: {notification.metadata['error_message']}")
+            if "task_name" in notification.metadata:
+                details.append(f"**任务**: {notification.metadata['task_name']}")
+            # SQL 和堆栈单独处理
+            if "sql" in notification.metadata:
+                sql_content = notification.metadata["sql"]
+            if "stacktrace" in notification.metadata:
+                stacktrace_content = notification.metadata["stacktrace"]
+        
+        # 构建卡片元素
+        elements: list[dict[str, Any]] = [
+            {
+                "tag": "markdown",
+                "content": notification.message,
+            },
+            {
+                "tag": "hr",
+            },
+            {
+                "tag": "markdown",
+                "content": "\n".join(details),
+            },
+        ]
+        
+        # 添加 SQL 代码块
+        if sql_content:
+            elements.append({"tag": "hr"})
+            elements.append({
+                "tag": "markdown",
+                "content": f"**SQL**:\n```sql\n{sql_content}\n```",
+            })
+        
+        # 添加堆栈代码块
+        if stacktrace_content:
+            elements.append({"tag": "hr"})
+            elements.append({
+                "tag": "markdown",
+                "content": f"**堆栈**:\n```python\n{stacktrace_content}\n```",
+            })
+        
+        # 构建 JSON 2.0 卡片消息
+        card = {
+            "msg_type": "interactive",
+            "card": {
+                "schema": "2.0",
+                "config": {
+                    "wide_screen_mode": True,
+                },
+                "header": {
+                    "template": color,
+                    "title": {
+                        "tag": "plain_text",
+                        "content": notification.title,
+                    },
+                },
+                "body": {
+                    "elements": elements,
+                },
+            },
+        }
+        
+        return card
+    
+    async def send(self, notification: "AlertNotification") -> bool:
+        """发送飞书通知。"""
+        try:
+            # 构建消息
+            message = self._build_message(notification)
+            
+            # 添加签名（如果配置了）
+            if self.secret:
+                timestamp = int(time.time())
+                message["timestamp"] = str(timestamp)
+                message["sign"] = self._generate_sign(timestamp)
+            
+            # 发送请求
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(self.webhook, json=message)
+                result = response.json()
+                
+                if result.get("code") == 0 or result.get("StatusCode") == 0:
+                    logger.debug(f"飞书通知发送成功: {notification.title}")
+                    return True
+                else:
+                    logger.error(f"飞书通知发送失败: {result}")
+                    return False
+        except Exception as e:
+            logger.error(f"飞书通知发送异常: {e}")
+            return False
+
+
+__all__ = ["FeishuNotifier"]

aury/boot/infrastructure/monitoring/alerting/notifiers/webhook.py

@@ -0,0 +1,110 @@
+"""通用 Webhook 通知器。
+
+通过 HTTP POST 发送告警到任意 Webhook 端点。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from aury.boot.common.logging import logger
+
+from .base import AlertNotifier
+
+if TYPE_CHECKING:
+    from ..events import AlertNotification
+
+
+class WebhookNotifier(AlertNotifier):
+    """通用 Webhook 通知器。
+    
+    将告警以 JSON 格式 POST 到指定 URL。
+    支持自定义请求头。
+    
+    环境变量配置示例：
+        ALERT_NOTIFIER_MYWEBHOOK_TYPE=webhook
+        ALERT_NOTIFIER_MYWEBHOOK_URL=https://my-alert-system.com/api/alert
+        ALERT_NOTIFIER_MYWEBHOOK_HEADERS={"Authorization": "Bearer xxx"}
+    """
+    
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        timeout: int = 10,
+    ) -> None:
+        """初始化 Webhook 通知器。
+        
+        Args:
+            url: Webhook URL
+            headers: 自定义请求头
+            timeout: 请求超时时间（秒）
+        """
+        self.url = url
+        self.headers = headers or {}
+        self.timeout = timeout
+    
+    @classmethod
+    def from_config(cls, config: dict) -> "WebhookNotifier":
+        """从配置创建实例。"""
+        url = config.get("url")
+        if not url:
+            raise ValueError("Webhook 通知器配置缺少 url")
+        
+        # 解析 headers（可能是 JSON 字符串）
+        headers = config.get("headers")
+        if isinstance(headers, str):
+            import json
+            try:
+                headers = json.loads(headers)
+            except json.JSONDecodeError:
+                headers = {}
+        
+        timeout = int(config.get("timeout", 10))
+        
+        return cls(url=url, headers=headers, timeout=timeout)
+    
+    def _build_payload(self, notification: "AlertNotification") -> dict[str, Any]:
+        """构建请求体。"""
+        return {
+            "title": notification.title,
+            "message": notification.message,
+            "severity": notification.severity.value,
+            "event_type": notification.event_type.value,
+            "source": notification.source,
+            "service_name": notification.service_name,
+            "count": notification.count,
+            "first_timestamp": notification.first_timestamp.isoformat(),
+            "last_timestamp": notification.last_timestamp.isoformat(),
+            "trace_ids": notification.trace_ids,
+            "metadata": notification.metadata,
+        }
+    
+    async def send(self, notification: "AlertNotification") -> bool:
+        """发送 Webhook 通知。"""
+        try:
+            payload = self._build_payload(notification)
+            
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    self.url,
+                    json=payload,
+                    headers=self.headers,
+                )
+                
+                if response.is_success:
+                    logger.debug(f"Webhook 通知发送成功: {notification.title}")
+                    return True
+                else:
+                    logger.error(
+                        f"Webhook 通知发送失败: {response.status_code} - {response.text}"
+                    )
+                    return False
+        except Exception as e:
+            logger.error(f"Webhook 通知发送异常: {e}")
+            return False
+
+
+__all__ = ["WebhookNotifier"]

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

@@ -0,0 +1,179 @@
+"""告警规则定义。
+
+定义告警规则数据结构和匹配逻辑。
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .events import AlertEventType, AlertSeverity
+
+if TYPE_CHECKING:
+    from .events import AlertEvent
+
+
+@dataclass
+class AlertRule:
+    """告警规则。
+    
+    定义何时触发告警、如何聚合、发送到哪些通知器。
+    
+    示例：
+        # 慢请求规则：1分钟内5次触发，5分钟抑制
+        rule = AlertRule(
+            name="slow_request",
+            event_types=[AlertEventType.SLOW_REQUEST],
+            threshold=1.0,
+            aggregate_window=60,
+            aggregate_threshold=5,
+            suppress_seconds=300,
+            notifiers=["feishu"],
+        )
+        
+        # 关键接口规则：更严格的阈值
+        rule = AlertRule(
+            name="critical_api",
+            event_types=[AlertEventType.SLOW_REQUEST],
+            path_pattern="/api/v1/payments/*",
+            threshold=0.5,
+            aggregate_threshold=1,
+            notifiers=["feishu", "sms"],
+        )
+    """
+    
+    name: str
+    event_types: list[AlertEventType]
+    
+    # 触发条件
+    threshold: float | None = None          # 慢阈值（秒），仅对 slow_* 类型有效
+    severity_min: AlertSeverity = AlertSeverity.WARNING
+    
+    # 过滤条件
+    source_filter: str | None = None        # api / task / scheduler
+    path_pattern: str | None = None         # 路径匹配（支持 * 通配符）
+    exclude_paths: list[str] | None = None  # 排除路径列表（支持 * 通配符）
+    
+    # 聚合配置
+    aggregate_window: int = 10              # 滑动窗口（秒）
+    aggregate_threshold: int = 1            # 触发阈值
+    suppress_seconds: int = 300             # 抑制时间（秒）
+    
+    # 通知配置
+    notifiers: list[str] = field(default_factory=lambda: ["default"])
+    
+    # 编译后的正则（内部使用）
+    _path_regex: re.Pattern | None = field(default=None, repr=False)
+    _exclude_regexes: list[re.Pattern] = field(default_factory=list, repr=False)
+    
+    def __post_init__(self) -> None:
+        """初始化后编译路径正则。"""
+        if self.path_pattern:
+            # 将通配符转换为正则
+            regex_pattern = fnmatch.translate(self.path_pattern)
+            self._path_regex = re.compile(regex_pattern)
+        
+        if self.exclude_paths:
+            # 编译所有排除路径的正则
+            for exclude_pattern in self.exclude_paths:
+                regex_pattern = fnmatch.translate(exclude_pattern)
+                self._exclude_regexes.append(re.compile(regex_pattern))
+    
+    def matches(self, event: "AlertEvent") -> bool:
+        """检查事件是否匹配规则。
+        
+        Args:
+            event: 告警事件
+        
+        Returns:
+            bool: 是否匹配
+        """
+        # 检查事件类型
+        if event.event_type not in self.event_types:
+            return False
+        
+        # 检查严重级别
+        severity_order = [AlertSeverity.INFO, AlertSeverity.WARNING, AlertSeverity.ERROR, AlertSeverity.CRITICAL]
+        if severity_order.index(event.severity) < severity_order.index(self.severity_min):
+            return False
+        
+        # 检查来源
+        if self.source_filter and event.source != self.source_filter:
+            return False
+        
+        # 检查路径
+        if self._path_regex:
+            endpoint = event.metadata.get("endpoint", "")
+            if not self._path_regex.match(endpoint):
+                return False
+        
+        # 检查排除路径
+        if self._exclude_regexes:
+            endpoint = event.metadata.get("endpoint", "")
+            for exclude_regex in self._exclude_regexes:
+                if exclude_regex.match(endpoint):
+                    return False  # 匹配到排除规则，不触发告警
+        
+        # 检查阈值（对于 slow_* 类型）
+        if self.threshold is not None and event.event_type in (
+            AlertEventType.SLOW_REQUEST,
+            AlertEventType.SLOW_SQL,
+        ):
+            duration = event.metadata.get("duration", 0)
+            if duration < self.threshold:
+                return False
+        
+        return True
+
+
+def load_rules_from_dict(data: dict) -> tuple[dict, list[AlertRule]]:
+    """从字典加载规则配置。
+    
+    Args:
+        data: 规则配置字典（通常从 YAML 加载）
+    
+    Returns:
+        (defaults, rules) 元组
+    """
+    defaults = data.get("defaults", {})
+    rules = []
+    
+    for rule_data in data.get("rules", []):
+        # 解析事件类型
+        event_types = []
+        for et in rule_data.get("event_types", []):
+            if isinstance(et, str):
+                event_types.append(AlertEventType(et))
+            else:
+                event_types.append(et)
+        
+        # 解析严重级别
+        severity_min = rule_data.get("severity_min", defaults.get("severity_min", "warning"))
+        if isinstance(severity_min, str):
+            severity_min = AlertSeverity(severity_min.lower())
+        
+        rule = AlertRule(
+            name=rule_data["name"],
+            event_types=event_types,
+            threshold=rule_data.get("threshold", defaults.get("threshold")),
+            severity_min=severity_min,
+            source_filter=rule_data.get("source_filter") or rule_data.get("source"),
+            path_pattern=rule_data.get("path_pattern"),
+            exclude_paths=rule_data.get("exclude_paths"),
+            aggregate_window=rule_data.get("aggregate_window", defaults.get("aggregate_window", 10)),
+            aggregate_threshold=rule_data.get("aggregate_threshold", defaults.get("aggregate_threshold", 1)),
+            suppress_seconds=rule_data.get("suppress_seconds", defaults.get("suppress_seconds", 300)),
+            notifiers=rule_data.get("notifiers", ["default"]),
+        )
+        rules.append(rule)
+    
+    return defaults, rules
+
+
+__all__ = [
+    "AlertRule",
+    "load_rules_from_dict",
+]