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

aury/boot/application/config/settings.py

@@ -15,7 +15,11 @@ from dotenv import load_dotenv
 from pydantic import BaseModel, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from .multi_instance import MultiInstanceConfigLoader, MultiInstanceSettings
+from .multi_instance import (
+    MultiInstanceConfigLoader,
+    MultiInstanceSettings,
+    parse_multi_instance_env,
+)
 
 
 def _load_env_file(env_file: str | Path) -> bool:
@@ -218,6 +222,10 @@ class DatabaseSettings(BaseModel):
         default=True,
         description="是否在获取连接前进行 PING"
     )
+    slow_query_threshold: float = Field(
+        default=1.0,
+        description="慢查询阈值（秒），超过此时间的查询会记录警告日志"
+    )
 
 
 class CacheSettings(BaseModel):
@@ -407,7 +415,7 @@ class ServiceSettings(BaseModel):
     """服务配置。
 
     环境变量格式: SERVICE__{FIELD}
-    示例: SERVICE__NAME, SERVICE__TYPE
+    示例: SERVICE__NAME, SERVICE__TYPE, SERVICE__ENVIRONMENT
 
     服务类型说明：
     - api: 运行 API 服务（SCHEDULER__ENABLED 决定是否同时运行调度器）
@@ -418,7 +426,15 @@ class ServiceSettings(BaseModel):
 
     name: str = Field(
         default="app",
-        description="服务名称，用于日志目录区分"
+        description="服务名称，用于日志目录区分、链路追踪标识"
+    )
+    version: str = Field(
+        default="",
+        description="服务版本（用于链路追踪和监控）"
+    )
+    environment: str = Field(
+        default="development",
+        description="部署环境 (development/staging/production)"
     )
     service_type: str = Field(
         default="api",
@@ -555,6 +571,177 @@ class MessageQueueSettings(BaseModel):
     )
 
 
+class TelemetrySettings(BaseModel):
+    """OpenTelemetry 配置。
+    
+    环境变量格式: TELEMETRY__{FIELD}
+    示例: TELEMETRY__ENABLED, TELEMETRY__SLOW_THRESHOLD
+    
+    功能说明：
+    - 启用后自动 instrument FastAPI、SQLAlchemy、httpx
+    - get_trace_id() 会优先使用 OTel trace_id
+    - 可配置 AlertingSpanProcessor 自动检测慢请求/异常并触发告警
+    - 可选配置 OTLP 导出到 Jaeger/Tempo/Collector
+    
+    注意：service_name/version/environment 从 ServiceSettings 获取。
+    """
+    
+    enabled: bool = Field(
+        default=False,
+        description="是否启用 OpenTelemetry"
+    )
+    
+    # Instrumentation 开关
+    instrument_fastapi: bool = Field(
+        default=True,
+        description="是否自动 instrument FastAPI"
+    )
+    instrument_sqlalchemy: bool = Field(
+        default=True,
+        description="是否自动 instrument SQLAlchemy"
+    )
+    instrument_httpx: bool = Field(
+        default=True,
+        description="是否自动 instrument httpx"
+    )
+    
+    
+    # OTLP Traces 导出配置
+    traces_endpoint: str | None = Field(
+        default=None,
+        description="Traces 导出端点（如 http://jaeger:4317）"
+    )
+    traces_headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Traces 导出请求头"
+    )
+    
+    # OTLP Logs 导出配置
+    logs_endpoint: str | None = Field(
+        default=None,
+        description="Logs 导出端点（如 http://loki:3100）"
+    )
+    logs_headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Logs 导出请求头"
+    )
+    
+    # OTLP Metrics 导出配置
+    metrics_endpoint: str | None = Field(
+        default=None,
+        description="Metrics 导出端点（如 http://prometheus:9090）"
+    )
+    metrics_headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Metrics 导出请求头"
+    )
+    
+    # 采样配置
+    sampling_rate: float = Field(
+        default=1.0,
+        description="采样率 (0.0-1.0)，1.0 表示 100%"
+    )
+
+
+class AlertSettings(BaseModel):
+    """告警系统配置。
+    
+    环境变量格式: ALERT__{FIELD}
+    示例: ALERT__ENABLED, ALERT__RULES_FILE
+    
+    通知器配置（作为子配置，动态字段）：
+        ALERT__NOTIFIERS__FEISHU__TYPE=feishu
+        ALERT__NOTIFIERS__FEISHU__WEBHOOK=https://open.feishu.cn/...
+        ALERT__NOTIFIERS__FEISHU__SECRET=xxx
+        
+        ALERT__NOTIFIERS__OPS__TYPE=webhook
+        ALERT__NOTIFIERS__OPS__URL=https://my-system.com/alert
+    
+    自定义通知器通过 AlertManager.register_notifier() 注册。
+    """
+    
+    # 通知器配置缓存（动态字段）
+    _notifiers: dict[str, dict[str, Any]] | None = None
+    
+    enabled: bool = Field(
+        default=False,
+        description="是否启用告警系统"
+    )
+    rules_file: str | None = Field(
+        default=None,
+        description="告警规则文件路径（YAML 格式），如 alert_rules.yaml"
+    )
+    
+    # 慢操作阈值
+    slow_request_threshold: float = Field(
+        default=1.0,
+        description="慢请求阈值（秒）"
+    )
+    slow_sql_threshold: float = Field(
+        default=0.5,
+        description="慢 SQL 阈值（秒）"
+    )
+    
+    # 告警开关
+    alert_on_slow_request: bool = Field(
+        default=True,
+        description="是否对慢 HTTP 请求发送告警"
+    )
+    alert_on_slow_sql: bool = Field(
+        default=True,
+        description="是否对慢 SQL 发送告警"
+    )
+    alert_on_error: bool = Field(
+        default=True,
+        description="是否对异常发送告警（默认只对 5xx 告警，4xx 业务异常不告警）"
+    )
+    
+    # 默认累计触发配置
+    aggregate_window: int = Field(
+        default=10,
+        description="聚合窗口（秒）"
+    )
+    slow_request_aggregate: int = Field(
+        default=5,
+        description="慢请求触发阈值（窗口内次数）"
+    )
+    slow_sql_aggregate: int = Field(
+        default=10,
+        description="慢 SQL 触发阈值（窗口内次数）"
+    )
+    exception_aggregate: int = Field(
+        default=1,
+        description="异常触发阈值（通常为 1，立即告警）"
+    )
+    
+    # 抑制配置
+    suppress_seconds: int = Field(
+        default=10,
+        description="告警抑制时间（秒），相同告警在此时间内不重复发送"
+    )
+    
+    def get_notifiers(self) -> dict[str, dict[str, Any]]:
+        """获取所有告警通知器实例配置。
+        
+        从环境变量解析 ALERT__NOTIFIERS__{INSTANCE}__{FIELD} 格式的配置。
+        支持动态字段，不同类型通知器可有不同字段。
+        
+        Returns:
+            dict[str, dict[str, Any]]: 实例名 -> 配置字典
+            
+        示例:
+            ALERT__NOTIFIERS__FEISHU__TYPE=feishu
+            ALERT__NOTIFIERS__FEISHU__WEBHOOK=https://...
+            
+            返回: {"feishu": {"type": "feishu", "webhook": "https://..."}}
+        
+        自定义通知器通过 AlertManager.register_notifier() 注册。
+        """
+        if self._notifiers is None:
+            self._notifiers = parse_multi_instance_env("ALERT__NOTIFIERS")
+        return self._notifiers
+
+
 class MigrationSettings(BaseModel):
     """数据库迁移配置。
     
@@ -824,6 +1011,10 @@ class BaseConfig(BaseSettings):
     # RPC 服务配置（当前服务注册）
     rpc_service: RPCServiceSettings = Field(default_factory=RPCServiceSettings)
     
+    # ========== 监控告警 ==========
+    telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings)
+    alert: AlertSettings = Field(default_factory=AlertSettings)
+    
     model_config = SettingsConfigDict(
         case_sensitive=False,
         extra="ignore",
@@ -953,6 +1144,7 @@ __all__ = [
     # 配置类
     "AdminAuthSettings",
     "AdminConsoleSettings",
+    "AlertSettings",
     "BaseConfig",
     "CORSSettings",
     # 多实例配置类

aury/boot/application/constants/components.py

@@ -50,6 +50,9 @@ class ComponentName(str, Enum):
     # 管理后台（可选扩展）
     ADMIN_CONSOLE = "admin_console"
 
+    # 遍测组件 (OpenTelemetry)
+    TELEMETRY = "telemetry"
+
 
 __all__ = [
     "ComponentName",

aury/boot/application/middleware/logging.py

@@ -16,8 +16,33 @@ from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
 
-from aury.boot.application.errors import global_exception_handler
-from aury.boot.common.logging import logger, set_trace_id
+from aury.boot.application.errors.chain import global_exception_handler
+from aury.boot.common.logging import get_trace_id, logger, set_trace_id
+
+
+def _record_exception_to_span(exc: Exception) -> None:
+    """将异常记录到当前 OTEL span（使用与 loguru 一致的格式）。"""
+    try:
+        from opentelemetry import trace
+        
+        from aury.boot.common.logging.format import format_exception_compact
+        
+        span = trace.get_current_span()
+        if span and span.is_recording():
+            # 使用与 loguru 一致的堆栈格式（包含代码行和局部变量）
+            formatted_tb = format_exception_compact(
+                type(exc), exc, exc.__traceback__
+            )
+            
+            # 记录异常，并将格式化堆栈放入 attributes
+            span.record_exception(exc, attributes={
+                "exception.stacktrace": formatted_tb,
+            })
+            span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc)))
+    except ImportError:
+        pass  # OTEL 未安装
+    except Exception:
+        pass  # 忽略记录错误
 
 
 def log_request[T](func: Callable[..., T]) -> Callable[..., T]:
@@ -112,22 +137,33 @@ def _should_log_body(content_type: str | None) -> bool:
 
 
 class RequestLoggingMiddleware(BaseHTTPMiddleware):
-    """请求日志中间件（支持链路追踪）。
+    """请求日志中间件（支持链路追踪和告警）。
     
     自动记录所有HTTP请求的详细信息，包括：
     - 请求方法、路径、查询参数、请求体
     - 客户端IP、User-Agent
     - 响应状态码、耗时、响应体
     - 链路追踪 ID（X-Trace-ID / X-Request-ID）
+    - 慢请求和异常告警（如果启用告警系统）
     
     注意：文件上传、二进制数据等不会记录 body 内容。
     
     使用示例:
         from aury.boot.application.middleware.logging import RequestLoggingMiddleware
         
-        app.add_middleware(RequestLoggingMiddleware)
+        app.add_middleware(RequestLoggingMiddleware, slow_request_threshold=1.0)
     """
     
+    def __init__(self, app, slow_request_threshold: float = 1.0) -> None:
+        """初始化中间件。
+        
+        Args:
+            app: ASGI 应用
+            slow_request_threshold: 慢请求阈值（秒），默认 1.0
+        """
+        super().__init__(app)
+        self.slow_request_threshold = slow_request_threshold
+    
     async def dispatch(self, request: Request, call_next) -> Response:
         """处理请求并记录日志。"""
         start_time = time.time()
@@ -193,10 +229,10 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             )
             
             # 慢请求警告
-            if duration > 1.0:
+            if duration > self.slow_request_threshold:
                 logger.warning(
                     f"慢请求: {request.method} {request.url.path} | "
-                    f"耗时: {duration:.3f}s (超过1秒) | "
+                    f"耗时: {duration:.3f}s (阈值: {self.slow_request_threshold}s) | "
                     f"Trace-ID: {trace_id}"
                 )
             
@@ -210,6 +246,9 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
                 f"耗时: {duration:.3f}s | Trace-ID: {trace_id}"
             )
             
+            # 将异常记录到当前 OTEL span（以便告警系统提取）
+            _record_exception_to_span(exc)
+            
             # 使用全局异常处理器生成响应，而不是直接抛出异常
             # BaseHTTPMiddleware 中直接 raise 会绕过 FastAPI 的异常处理器
             response = await global_exception_handler(request, exc)

aury/boot/commands/docs.py

@@ -349,6 +349,45 @@ def generate_env_example(
         raise typer.Exit(1)
 
 
+@app.command(name="alert-rules")
+def generate_alert_rules(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新 alert_rules.yaml 告警规则模板。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📢 检测到项目: {context['project_name']}[/cyan]")
+    
+    try:
+        # 使用模板文件
+        template_path = TEMPLATES_DIR / "alert_rules.example.yaml.tpl"
+        content = template_path.read_text(encoding="utf-8")
+        output_path = project_dir / "alert_rules.example.yaml"
+        _write_file(output_path, content, force=force, dry_run=dry_run)
+    except Exception as e:
+        console.print(f"[red]❌ 生成失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
 @app.command(name="all")
 def generate_all_docs(
     project_dir: Path = typer.Argument(
@@ -382,6 +421,7 @@ def generate_all_docs(
     root_docs: list[tuple[str, str, str]] = [
         ("AGENTS.md.tpl", "AGENTS.md", "AI 编程助手上下文"),
         ("env.example.tpl", ".env.example", "环境变量示例"),
+        ("alert_rules.example.yaml.tpl", "alert_rules.example.yaml", "告警规则示例"),
     ]
     
     # aury_docs/ 开发文档

aury/boot/commands/init.py

@@ -159,6 +159,7 @@ TEMPLATE_FILE_MAP = {
     "AGENTS.md": "AGENTS.md.tpl",
     "conftest.py": "conftest.py.tpl",
     "admin_console/__init__.py": "admin_console_init.py.tpl",
+    "alert_rules.example.yaml": "alert_rules.example.yaml.tpl",
 }
 
 # env 模板拼接顺序
@@ -172,6 +173,7 @@ ENV_TEMPLATE_ORDER = [
     "scheduler.tpl",
     "messaging.tpl",
     "storage.tpl",
+    "monitoring.tpl",
     "third_party.tpl",
     "rpc.tpl",
 ]

aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -112,6 +112,11 @@ mypy {package_name}/
 - **[aury_docs/14-mq.md](./aury_docs/14-mq.md)** - 消息队列
 - **[aury_docs/15-events.md](./aury_docs/15-events.md)** - 事件总线
 
+### 监控与告警
+
+- **[aury_docs/17-alerting.md](./aury_docs/17-alerting.md)** - 告警系统（慢请求/慢SQL/异常 → 飞书）
+- **[alert_rules.example.yaml](./alert_rules.example.yaml)** - 告警规则示例（复制为 alert_rules.yaml 使用）
+
 ### 第三方集成
 
 - **[aury_docs/16-adapter.md](./aury_docs/16-adapter.md)** - 第三方接口适配器（Mock/真实切换）
@@ -164,15 +169,25 @@ class User(Base): ...
 - 写操作**必须**使用 `@transactional` 装饰器
 - 只读操作可以不加事务装饰器
 - 跨 Service 调用通过共享 session 实现事务共享
+- **后台任务必须**使用 `@isolated_task` 装饰器
 
 ```python
-from aury.boot.domain.transaction import transactional
+from aury.boot.domain.transaction import transactional, isolated_task
 
 class UserService(BaseService):
     @transactional
     async def create(self, data: UserCreate) -> User:
         # 自动事务管理
         return await self.repo.create(data.model_dump())
+
+
+# 后台任务必须加 @isolated_task，否则事务不会提交
+@isolated_task
+async def background_upload(space_id: int, url: str):
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            await repo.update(...)
 ```
 
 ### Manager API 规范

aury/boot/commands/templates/project/alert_rules.example.yaml.tpl

@@ -0,0 +1,85 @@
+# 告警规则配置文件
+#
+# 使用方法：
+#   1. 在 .env 中配置 ALERT__RULES_FILE=alert_rules.yaml
+#   2. 配置通知器（见下方示例）
+#   3. 根据需要修改规则
+#
+# 简版配置（所有告警发到同一个群）：
+#   ALERT__NOTIFIERS__DEFAULT__TYPE=feishu
+#   ALERT__NOTIFIERS__DEFAULT__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
+#
+# 完整版配置（分群告警）：
+#   ALERT__NOTIFIERS__PERF_GROUP__TYPE=feishu
+#   ALERT__NOTIFIERS__PERF_GROUP__WEBHOOK=https://open.feishu.cn/.../perf-xxx
+#   ALERT__NOTIFIERS__ERROR_GROUP__TYPE=feishu
+#   ALERT__NOTIFIERS__ERROR_GROUP__WEBHOOK=https://open.feishu.cn/.../error-xxx
+#   ALERT__NOTIFIERS__OPS_GROUP__TYPE=feishu
+#   ALERT__NOTIFIERS__OPS_GROUP__WEBHOOK=https://open.feishu.cn/.../ops-xxx
+
+defaults:
+  slow_request_threshold: 1.0
+  slow_sql_threshold: 0.5
+  aggregate_window: 10
+  suppress_seconds: 300
+
+rules:
+  # ============ 简版：所有告警发到 default 群 ============
+  # 如果使用分群告警，请注释掉这部分，使用下方的完整版
+
+  - name: slow_request
+    event_types: [slow_request]
+    aggregate_threshold: 5
+    notifiers: [default]
+
+  - name: slow_sql
+    event_types: [slow_sql]
+    aggregate_threshold: 10
+    notifiers: [default]
+
+  - name: exception
+    event_types: [exception]
+    aggregate_threshold: 1
+    suppress_seconds: 60
+    notifiers: [default]
+
+  - name: task_issues
+    event_types: [task_failure, task_timeout]
+    aggregate_threshold: 1
+    notifiers: [default]
+
+  # ============ 完整版：分群告警 ============
+  # 取消注释并配置对应的通知器即可使用
+
+  # 慢请求 → 性能群
+  # - name: slow_request
+  #   event_types: [slow_request]
+  #   aggregate_threshold: 5
+  #   notifiers: [perf_group]
+
+  # 慢 SQL → 性能群
+  # - name: slow_sql
+  #   event_types: [slow_sql]
+  #   aggregate_threshold: 10
+  #   notifiers: [perf_group]
+
+  # 异常 → 错误群（立即告警）
+  # - name: exception
+  #   event_types: [exception]
+  #   aggregate_threshold: 1
+  #   suppress_seconds: 60
+  #   notifiers: [error_group]
+
+  # 任务失败/超时 → 运维群
+  # - name: task_issues
+  #   event_types: [task_failure, task_timeout]
+  #   aggregate_threshold: 1
+  #   notifiers: [ops_group]
+
+  # 关键接口更严格的阈值（示例）
+  # - name: critical_api
+  #   event_types: [slow_request]
+  #   path_pattern: "/api/v1/payments/*"
+  #   threshold: 0.5
+  #   aggregate_threshold: 1
+  #   notifiers: [error_group]

aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl

@@ -57,3 +57,6 @@ CLI 命令参考请查看 [99-cli.md](./99-cli.md)。
 - [13-channel.md](./13-channel.md) - 流式通道（SSE）
 - [14-mq.md](./14-mq.md) - 消息队列
 - [15-events.md](./15-events.md) - 事件总线
+
+### 监控与告警
+- [17-alerting.md](./17-alerting.md) - 告警系统（慢请求/慢SQL/异常 → 飞书）

aury/boot/commands/templates/project/aury_docs/03-service.md.tpl

@@ -396,3 +396,63 @@ DATABASE_ISOLATION_LEVEL=REPEATABLE READ
 - 大多数场景：`READ COMMITTED`（平衡性能和一致性）
 - 报表/统计查询：`REPEATABLE READ`（保证读取一致性）
 - 金融交易：`SERIALIZABLE`（最强一致性，性能较低）
+
+### 3.12 后台任务事务隔离（重要）
+
+在 `@transactional` 装饰的 Service 方法中 spawn 后台任务时，**必须**使用 `@isolated_task` 或 `isolated_context`，否则事务不会提交。
+
+**问题背景**：
+`asyncio.create_task()` 会继承父协程的 `contextvars`。如果父协程在 `@transactional` 中，子任务会继承事务深度标记，导致：
+- `auto_commit` 失效
+- `transactional_context` 也不会提交
+- session 关闭时数据被 rollback
+
+**解决方案 1：装饰器（推荐）**
+
+```python
+import asyncio
+from aury.boot.domain.transaction import isolated_task, transactional_context
+from aury.boot.infrastructure.database import DatabaseManager
+
+db = DatabaseManager.get_instance()
+
+
+@isolated_task
+async def upload_cover(space_id: int, cover_url: str):
+    """后台任务：上传封面。"""
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            space = await repo.get(space_id)
+            if space:
+                await repo.update(space, {{"cover": cover_url}})
+        # 现在会正常 commit
+
+
+class SpaceService(BaseService):
+    @transactional
+    async def create(self, data: SpaceCreate) -> Space:
+        space = await self.repo.create(data.model_dump())
+        
+        # spawn 后台任务
+        asyncio.create_task(upload_cover(space.id, data.cover_url))
+        
+        return space
+```
+
+**解决方案 2：上下文管理器**
+
+```python
+from aury.boot.domain.transaction import isolated_context
+
+async def background_job():
+    async with isolated_context():
+        async with db.session() as session:
+            async with transactional_context(session):
+                # 正常的事务处理
+                ...
+```
+
+**注意事项**：
+- 后台任务必须新开 session（`db.session()`），不能复用主请求的 `self.session`
+- 后台任务的事务与主请求独立，主请求回滚不影响后台任务