aury-boot 0.0.39__tar.gz → 0.0.40__tar.gz

{aury_boot-0.0.39 → aury_boot-0.0.40}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.39
+Version: 0.0.40
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.11.0
 Requires-Dist: alembic>=1.17.2
 Requires-Dist: aury-sdk-storage[aws]>=0.0.6
 Requires-Dist: babel>=2.17.0
@@ -10,7 +11,6 @@ Requires-Dist: broadcaster[redis]>=0.3.1
 Requires-Dist: faker>=38.2.0
 Requires-Dist: fastapi>=0.122.0
 Requires-Dist: greenlet>=3.2.4
-Requires-Dist: httpx>=0.28.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic-settings>=2.12.0
 Requires-Dist: pydantic>=2.12.5
@@ -30,10 +30,13 @@ Requires-Dist: asyncpg>=0.31.0; extra == 'all'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'all'
 Requires-Dist: dramatiq>=1.18.0; extra == 'all'
 Requires-Dist: pika>=1.3.2; extra == 'all'
+Requires-Dist: psutil>=7.0.0; extra == 'all'
+Requires-Dist: pyroscope-io>=0.8.7; extra == 'all'
 Requires-Dist: redis>=7.1.0; extra == 'all'
 Provides-Extra: broadcaster
 Requires-Dist: broadcaster[redis]>=0.3.1; extra == 'broadcaster'
 Provides-Extra: dev
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
@@ -47,14 +50,17 @@ Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.3.2; extra == 'mysql'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.25.0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'otel'
 Provides-Extra: otel-exporter
 Requires-Dist: opentelemetry-exporter-otlp>=1.25.0; extra == 'otel-exporter'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
+Provides-Extra: profiling
+Requires-Dist: psutil>=7.0.0; extra == 'profiling'
+Requires-Dist: pyroscope-io>=0.8.7; extra == 'profiling'
 Provides-Extra: rabbitmq
 Requires-Dist: amqp>=5.3.1; extra == 'rabbitmq'
 Provides-Extra: recommended
@@ -64,8 +70,8 @@ Requires-Dist: asyncpg>=0.31.0; extra == 'recommended'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'recommended'
 Requires-Dist: dramatiq>=1.18.0; extra == 'recommended'
 Requires-Dist: opentelemetry-api>=1.25.0; extra == 'recommended'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'recommended'
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'recommended'
 Requires-Dist: redis>=7.1.0; extra == 'recommended'

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.39'
-__version_tuple__ = version_tuple = (0, 0, 39)
+__version__ = version = '0.0.40'
+__version_tuple__ = version_tuple = (0, 0, 40)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/application/adapter/http.py

@@ -25,10 +25,14 @@ from __future__ import annotations
 
 from typing import Any
 
-import httpx
-
 from aury.boot.common.logging import get_trace_id, logger
-from aury.boot.toolkit.http import HttpClient, RetryConfig
+from aury.boot.toolkit.http import (
+    HttpClient,
+    HttpNetworkError,
+    HttpStatusError,
+    HttpTimeoutError,
+    RetryConfig,
+)
 
 from .base import BaseAdapter
 from .config import AdapterSettings
@@ -185,7 +189,7 @@ class HttpAdapter(BaseAdapter):
             json: JSON 请求体
             data: 表单数据
             files: 上传文件
-            **kwargs: 其他 httpx 参数
+            **kwargs: 其他 aiohttp 参数
             
         Returns:
             dict: 响应 JSON
@@ -228,7 +232,7 @@ class HttpAdapter(BaseAdapter):
                     "content": response.text,
                 }
         
-        except httpx.TimeoutException as exc:
+        except HttpTimeoutError as exc:
             raise AdapterTimeoutError(
                 f"请求超时: {method} {path}",
                 adapter_name=self.name,
@@ -236,7 +240,7 @@ class HttpAdapter(BaseAdapter):
                 cause=exc,
             ) from exc
         
-        except httpx.HTTPStatusError as exc:
+        except HttpStatusError as exc:
             # HTTP 错误状态码
             response = exc.response
             try:
@@ -255,6 +259,13 @@ class HttpAdapter(BaseAdapter):
                 cause=exc,
             ) from exc
         
+        except HttpNetworkError as exc:
+            raise AdapterError(
+                f"网络错误: {method} {path} - {exc}",
+                adapter_name=self.name,
+                cause=exc,
+            ) from exc
+        
         except Exception as exc:
             raise AdapterError(
                 f"请求失败: {method} {path} - {type(exc).__name__}: {exc}",

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/application/app/base.py

@@ -313,6 +313,7 @@ class FoundationApp(FastAPI):
             enable_file_rotation=config.log.enable_file_rotation,
             enable_console=config.log.enable_console,
             logger_levels=logger_levels,
+            enqueue=config.log.enqueue,
         )
         
         # 注册 access 日志（HTTP 请求日志）

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/application/app/components.py

@@ -320,11 +320,24 @@ class SchedulerComponent(Component):
             url = scheduler_config.jobstore_url
             if url.startswith("redis://"):
                 try:
+                    from urllib.parse import urlparse
                     from apscheduler.jobstores.redis import RedisJobStore
+                    
+                    # 解析 Redis URL
+                    parsed = urlparse(url)
+                    redis_kwargs: dict = {
+                        "host": parsed.hostname or "localhost",
+                        "port": parsed.port or 6379,
+                    }
+                    if parsed.password:
+                        redis_kwargs["password"] = parsed.password
+                    if parsed.path and parsed.path != "/":
+                        redis_kwargs["db"] = int(parsed.path.lstrip("/") or 0)
+                    
                     scheduler_kwargs["jobstores"] = {
-                        "default": RedisJobStore.from_url(url)
+                        "default": RedisJobStore(**redis_kwargs)
                     }
-                    logger.info(f"调度器使用 Redis 存储: {url.split('@')[-1]}")
+                    logger.info(f"调度器使用 Redis 存储: {parsed.hostname}:{parsed.port}")
                 except ImportError:
                     logger.warning("Redis jobstore 需要安装 redis: pip install redis")
             else:
@@ -766,6 +779,70 @@ class AlertComponent(Component):
         pass
 
 
+class ProfilingComponent(Component):
+    """Profiling 组件。
+    
+    提供持续性能分析和事件循环阻塞检测：
+    - Pyroscope：持续采样生成火焰图
+    - 阻塞检测：检测同步代码阻塞事件循环
+    """
+
+    name = "profiling"
+    enabled = True
+    depends_on: ClassVar[list[str]] = ["alert"]  # 告警依赖
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """当启用 Pyroscope 或阻塞检测时启用。"""
+        return self.enabled and (
+            config.profiling.enabled or config.profiling.blocking_detector_enabled
+        )
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化 Profiling 组件。"""
+        try:
+            from aury.boot.infrastructure.monitoring.profiling import (
+                ProfilingConfig,
+                ProfilingManager,
+            )
+            
+            profiling_config = ProfilingConfig(
+                enabled=config.profiling.enabled,
+                pyroscope_endpoint=config.profiling.pyroscope_endpoint,
+                pyroscope_auth_token=config.profiling.pyroscope_auth_token,
+                service_name=config.service.name,
+                environment=config.service.environment,
+                blocking_detector_enabled=config.profiling.blocking_detector_enabled,
+                blocking_check_interval_ms=config.profiling.blocking_check_interval_ms,
+                blocking_threshold_ms=config.profiling.blocking_threshold_ms,
+                blocking_severe_threshold_ms=config.profiling.blocking_severe_threshold_ms,
+                blocking_alert_enabled=config.profiling.blocking_alert_enabled,
+                blocking_alert_cooldown_seconds=config.profiling.blocking_alert_cooldown_seconds,
+                blocking_max_history=config.profiling.blocking_max_history,
+                tags=config.profiling.pyroscope_tags,
+            )
+            
+            manager = ProfilingManager.get_instance()
+            manager.configure(profiling_config)
+            await manager.start()
+            
+            # 保存到 app.state
+            app.state.profiling_manager = manager
+            
+        except ImportError as e:
+            logger.warning(f"Profiling 依赖未安装，跳过初始化: {e}")
+        except Exception as e:
+            logger.warning(f"Profiling 初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """停止 Profiling 组件。"""
+        try:
+            manager = getattr(app.state, "profiling_manager", None)
+            if manager:
+                await manager.stop()
+        except Exception as e:
+            logger.warning(f"Profiling 关闭失败: {e}")
+
+
 class EventBusComponent(Component):
     """事件总线组件。
     
@@ -815,6 +892,7 @@ FoundationApp.plugins = [
 # 设置默认组件
 FoundationApp.components = [
     AlertComponent,  # 最先初始化告警管理器
+    ProfilingComponent,  # Profiling 依赖告警
     DatabaseComponent,
     MigrationComponent,
     AdminConsoleComponent,
@@ -837,6 +915,7 @@ __all__ = [
     "EventBusComponent",
     "MessageQueueComponent",
     "MigrationComponent",
+    "ProfilingComponent",
     "SchedulerComponent",
     "StorageComponent",
     "TaskComponent",

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/application/config/settings.py

@@ -401,6 +401,14 @@ class LogSettings(BaseModel):
         default=False,
         description="是否记录 WebSocket 消息内容（注意性能和敏感数据）"
     )
+    enqueue: bool = Field(
+        default=False,
+        description=(
+            "是否启用多进程安全队列。"
+            "启用后日志通过 multiprocessing.Queue 传输，"
+            "可能导致事件循环阻塞。建议在 asyncio 应用中保持 False"
+        )
+    )
 
 
 class ServiceSettings(BaseModel):
@@ -741,6 +749,70 @@ class AlertSettings(BaseModel):
         return self._notifiers
 
 
+class ProfilingSettings(BaseModel):
+    """Profiling 配置。
+    
+    环境变量格式: PROFILING__{FIELD}
+    示例: PROFILING__ENABLED, PROFILING__PYROSCOPE_ENDPOINT
+    
+    功能说明：
+    - Pyroscope：持续采样生成火焰图（需安装 pyroscope-io）
+    - 阻塞检测：检测同步代码阻塞事件循环（需安装 psutil）
+    """
+    
+    # Pyroscope 持续 Profiling
+    enabled: bool = Field(
+        default=False,
+        description="是否启用 Pyroscope 持续 profiling"
+    )
+    pyroscope_endpoint: str | None = Field(
+        default=None,
+        description="Pyroscope 服务端点（如 http://pyroscope:4040）"
+    )
+    pyroscope_auth_token: str | None = Field(
+        default=None,
+        description="Pyroscope 认证 token（可选）"
+    )
+    pyroscope_sample_rate: int = Field(
+        default=100,
+        description="Pyroscope 采样率 (Hz)，降低可减少开销"
+    )
+    pyroscope_tags: dict[str, str] = Field(
+        default_factory=dict,
+        description="Pyroscope 自定义标签"
+    )
+    
+    # 事件循环阻塞检测
+    blocking_detector_enabled: bool = Field(
+        default=False,
+        description="是否启用事件循环阻塞检测"
+    )
+    blocking_check_interval_ms: float = Field(
+        default=100,
+        description="阻塞检测间隔 (ms)"
+    )
+    blocking_threshold_ms: float = Field(
+        default=100,
+        description="阻塞阈值 (ms)，超过此时间记录阻塞事件"
+    )
+    blocking_severe_threshold_ms: float = Field(
+        default=500,
+        description="严重阻塞阈值 (ms)，超过此时间触发严重告警"
+    )
+    blocking_alert_enabled: bool = Field(
+        default=True,
+        description="检测到阻塞时是否发送告警"
+    )
+    blocking_alert_cooldown_seconds: float = Field(
+        default=60,
+        description="阻塞告警冷却时间 (秒)，避免告警风暴"
+    )
+    blocking_max_history: int = Field(
+        default=50,
+        description="保留的阻塞事件历史数量"
+    )
+
+
 class MigrationSettings(BaseModel):
     """数据库迁移配置。
     
@@ -1014,6 +1086,7 @@ class BaseConfig(BaseSettings):
     # ========== 监控告警 ==========
     telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings)
     alert: AlertSettings = Field(default_factory=AlertSettings)
+    profiling: ProfilingSettings = Field(default_factory=ProfilingSettings)
     
     model_config = SettingsConfigDict(
         case_sensitive=False,

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/commands/init.py

@@ -542,6 +542,18 @@ def _collect_interactive_config() -> dict:
 
     config["features"] = features
 
+    # 5.5 监控配置
+    console.print()
+    console.print("[bold]📊 监控配置[/bold]")
+    config["with_otel"] = Confirm.ask(
+        "  启用 OpenTelemetry 链路追踪",
+        default=True,
+    )
+    config["with_profiling"] = Confirm.ask(
+        "  启用 Profiling (火焰图/阻塞检测)",
+        default=False,
+    )
+
     # 6. 开发工具
     console.print()
     config["with_dev"] = Confirm.ask(
@@ -589,6 +601,12 @@ def _build_dependency_list(config: dict) -> list[str]:
     if config.get("with_admin_console", True):
         extras.add("admin")
 
+    # 监控
+    if config.get("with_otel", True):
+        extras.add("otel")
+    if config.get("with_profiling", False):
+        extras.add("profiling")
+
     # 开发工具
     if config.get("with_dev"):
         extras.add("dev")
@@ -616,6 +634,8 @@ def _show_config_summary(config: dict) -> None:
         ("服务模式", config.get("service_mode", "api")),
         ("管理后台", "是" if config.get("with_admin_console", True) else "否"),
         ("可选功能", ", ".join(config.get("features", [])) or "无"),
+        ("OpenTelemetry", "是" if config.get("with_otel", True) else "否"),
+        ("Profiling", "是" if config.get("with_profiling", False) else "否"),
         ("开发工具", "是" if config.get("with_dev") else "否"),
         ("Docker", "是" if config.get("with_docker") else "否"),
     ]

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/commands/pkg.py

@@ -45,6 +45,7 @@ class Category(str, Enum):
     SCHEDULER = "scheduler"
     ADMIN = "admin"
     STORAGE = "storage"
+    MONITORING = "monitoring"
     ECOSYSTEM = "ecosystem"
 
 
@@ -132,6 +133,29 @@ MODULES: dict[str, ModuleInfo] = {
         category=Category.STORAGE,
         deps=["aury-sdk-storage[aws]"],
     ),
+    # 监控
+    "otel": ModuleInfo(
+        name="otel",
+        desc="OpenTelemetry 链路追踪",
+        usage="启用 TELEMETRY__ENABLED 自动 instrument FastAPI/SQLAlchemy/httpx",
+        category=Category.MONITORING,
+        deps=["opentelemetry-api", "opentelemetry-sdk", "opentelemetry-instrumentation-fastapi",
+              "opentelemetry-instrumentation-sqlalchemy", "opentelemetry-instrumentation-httpx"],
+    ),
+    "otel-exporter": ModuleInfo(
+        name="otel-exporter",
+        desc="OpenTelemetry OTLP 导出器",
+        usage="导出 Traces/Metrics/Logs 到 Jaeger/Prometheus/Loki",
+        category=Category.MONITORING,
+        deps=["opentelemetry-exporter-otlp"],
+    ),
+    "profiling": ModuleInfo(
+        name="profiling",
+        desc="Profiling 性能分析",
+        usage="Pyroscope 火焰图 + 事件循环阻塞检测",
+        category=Category.MONITORING,
+        deps=["pyroscope-io", "psutil"],
+    ),
     # 生态包
     "storage-aws": ModuleInfo(
         name="storage-aws",
@@ -182,7 +206,12 @@ PRESETS: dict[str, PresetInfo] = {
     "full": PresetInfo(
         name="full",
         desc="完整功能（所有模块）",
-        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler", "admin", "storage-cos"],
+        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler", "admin", "storage-cos", "otel", "profiling"],
+    ),
+    "monitoring": PresetInfo(
+        name="monitoring",
+        desc="完整监控（OTel + Profiling）",
+        modules=["otel", "otel-exporter", "profiling"],
     ),
 }
 
@@ -195,6 +224,7 @@ CATEGORY_NAMES: dict[Category, str] = {
     Category.SCHEDULER: "📦 定时调度",
     Category.ADMIN: "📦 管理后台",
     Category.STORAGE: "📦 对象存储",
+    Category.MONITORING: "📊 监控分析",
     Category.ECOSYSTEM: "🌐 生态包",
 }
 

{aury_boot-0.0.39 → aury_boot-0.0.40}/aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl

@@ -60,3 +60,4 @@ CLI 命令参考请查看 [99-cli.md](./99-cli.md)。
 
 ### 监控与告警
 - [17-alerting.md](./17-alerting.md) - 告警系统（慢请求/慢SQL/异常 → 飞书）
+- [18-monitoring-profiling.md](./18-monitoring-profiling.md) - 监控与 Profiling（火焰图/阻塞检测）

aury_boot-0.0.40/aury/boot/commands/templates/project/aury_docs/18-monitoring-profiling.md.tpl

@@ -0,0 +1,239 @@
+# 监控与 Profiling
+
+本文档介绍 {project_name} 项目中的监控和性能分析配置。
+
+## 监控能力概览
+
+| 功能 | 用途 | 建议环境 |
+|------|------|----------|
+| OpenTelemetry | 链路追踪、慢请求检测 | 所有环境 |
+| 告警系统 | 异常/慢请求通知 | 所有环境 |
+| Pyroscope | 持续 Profiling、火焰图 | 测试/灰度 |
+| 阻塞检测 | 检测同步代码阻塞协程 | 测试/按需 |
+
+---
+
+## 不同环境的最佳实践
+
+### 开发环境
+
+```bash
+# .env.development
+TELEMETRY__ENABLED=false
+ALERT__ENABLED=false
+PROFILING__ENABLED=false
+PROFILING__BLOCKING_DETECTOR_ENABLED=true  # 开发时检测阻塞问题
+```
+
+### 测试/灰度环境
+
+```bash
+# .env.staging
+TELEMETRY__ENABLED=true
+TELEMETRY__TRACES_ENDPOINT=http://jaeger:4317
+
+ALERT__ENABLED=true
+ALERT__NOTIFIERS__DEFAULT__TYPE=feishu
+ALERT__NOTIFIERS__DEFAULT__WEBHOOK=https://...
+
+# 开启 Profiling 排查性能问题
+PROFILING__ENABLED=true
+PROFILING__PYROSCOPE_ENDPOINT=http://pyroscope:4040
+
+PROFILING__BLOCKING_DETECTOR_ENABLED=true
+```
+
+### 生产环境
+
+```bash
+# .env.production
+# 链路追踪 - 必开
+TELEMETRY__ENABLED=true
+TELEMETRY__TRACES_ENDPOINT=http://jaeger:4317
+TELEMETRY__SAMPLING_RATE=0.1  # 采样 10% 减少开销
+
+# 告警 - 必开
+ALERT__ENABLED=true
+ALERT__NOTIFIERS__DEFAULT__TYPE=feishu
+ALERT__NOTIFIERS__DEFAULT__WEBHOOK=https://...
+
+# Profiling - 按需（有约 2-5% CPU 开销）
+PROFILING__ENABLED=false  # 出问题时临时开启
+# PROFILING__PYROSCOPE_ENDPOINT=http://pyroscope:4040
+# PROFILING__PYROSCOPE_SAMPLE_RATE=10  # 降低采样率减少开销
+
+# 阻塞检测 - 按需
+PROFILING__BLOCKING_DETECTOR_ENABLED=false  # 出问题时临时开启
+```
+
+---
+
+## OpenTelemetry
+
+自动 instrument：
+- FastAPI 请求
+- SQLAlchemy SQL 查询
+- httpx 外部调用
+
+### 配置
+
+```bash
+TELEMETRY__ENABLED=true
+TELEMETRY__TRACES_ENDPOINT=http://jaeger:4317  # 可选
+TELEMETRY__SAMPLING_RATE=1.0  # 采样率，1.0=100%
+```
+
+### 手动 Span
+
+```python
+from aury.boot.infrastructure.monitoring.tracing import span, trace_span
+
+# 装饰器方式
+@trace_span(name="call_external_api")
+async def call_api():
+    ...
+
+# 上下文管理器
+async def process():
+    with span("step_1"):
+        await do_step_1()
+    with span("step_2"):
+        await do_step_2()
+```
+
+---
+
+## Pyroscope 持续 Profiling
+
+生成 CPU 火焰图，定位性能瓶颈。
+
+### 安装
+
+```bash
+pip install pyroscope-io
+```
+
+### 配置
+
+```bash
+PROFILING__ENABLED=true
+PROFILING__PYROSCOPE_ENDPOINT=http://pyroscope:4040
+PROFILING__PYROSCOPE_SAMPLE_RATE=100  # 采样率 Hz
+```
+
+### 部署 Pyroscope
+
+```yaml
+# docker-compose.yml
+services:
+  pyroscope:
+    image: grafana/pyroscope:latest
+    ports:
+      - "4040:4040"
+```
+
+访问 http://localhost:4040 查看火焰图。
+
+---
+
+## 事件循环阻塞检测
+
+检测同步代码阻塞 asyncio 事件循环的问题。
+
+### 安装
+
+```bash
+pip install psutil
+```
+
+### 配置
+
+```bash
+PROFILING__BLOCKING_DETECTOR_ENABLED=true
+PROFILING__BLOCKING_THRESHOLD_MS=100       # 阻塞阈值
+PROFILING__BLOCKING_SEVERE_THRESHOLD_MS=500  # 严重阈值
+PROFILING__BLOCKING_ALERT_ENABLED=true     # 阻塞时发送告警
+PROFILING__BLOCKING_ALERT_COOLDOWN_SECONDS=60  # 告警冷却
+```
+
+### 工作原理
+
+1. 后台线程每 100ms 向事件循环投递空任务
+2. 如果响应延迟 > 阈值，说明事件循环被阻塞
+3. 自动捕获主线程调用栈 + 进程状态
+4. 发送告警（含阻塞代码位置）
+
+### 告警示例
+
+```
+事件循环阻塞(严重): 520ms
+
+调用栈:
+  app/services/sync_io.py:42 in read_file
+    > data = open(path).read()  # 同步 IO！
+  
+进程状态:
+  cpu: 95%, memory: 256MB, threads: 12
+```
+
+### 常见阻塞原因
+
+- `time.sleep()` 应使用 `asyncio.sleep()`
+- `open().read()` 应使用 `aiofiles`
+- `requests.get()` 应使用 `httpx` 或 `aiohttp`
+- CPU 密集计算 应使用 `run_in_executor()`
+
+---
+
+## 环境变量参考
+
+### Telemetry
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `TELEMETRY__ENABLED` | 是否启用 | `false` |
+| `TELEMETRY__TRACES_ENDPOINT` | Traces 导出端点 | - |
+| `TELEMETRY__LOGS_ENDPOINT` | Logs 导出端点 | - |
+| `TELEMETRY__METRICS_ENDPOINT` | Metrics 导出端点 | - |
+| `TELEMETRY__SAMPLING_RATE` | 采样率 | `1.0` |
+
+### Profiling
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `PROFILING__ENABLED` | 是否启用 Pyroscope | `false` |
+| `PROFILING__PYROSCOPE_ENDPOINT` | Pyroscope 端点 | - |
+| `PROFILING__PYROSCOPE_SAMPLE_RATE` | 采样率 (Hz) | `100` |
+| `PROFILING__BLOCKING_DETECTOR_ENABLED` | 阻塞检测 | `false` |
+| `PROFILING__BLOCKING_THRESHOLD_MS` | 阻塞阈值 | `100` |
+| `PROFILING__BLOCKING_SEVERE_THRESHOLD_MS` | 严重阈值 | `500` |
+| `PROFILING__BLOCKING_ALERT_ENABLED` | 阻塞告警 | `true` |
+| `PROFILING__BLOCKING_ALERT_COOLDOWN_SECONDS` | 告警冷却 | `60` |
+
+---
+
+## 推荐的监控栈
+
+### 开源方案
+
+```
+OpenTelemetry → Jaeger (Traces)
+             → Grafana Loki (Logs)
+             → Prometheus (Metrics)
+             
+Pyroscope → 火焰图
+```
+
+### 云服务方案
+
+- **阿里云 ARMS** - APM + 告警
+- **腾讯云 APM** - 类似
+- **Datadog** - 全功能 APM
+- **Sentry** - 错误监控
+
+---
+
+## 相关文档
+
+- [17-alerting.md](./17-alerting.md) - 告警系统详细配置
+- [11-logging.md](./11-logging.md) - 日志配置