3. 异常事件基础：异常事件的分类与采集标记

在 Requests Limits 观测策略 体系中，异常事件是触发限流、熔断、降级等控制动作的直接信号。只有对异常事件进行精确分类、高效采集与标准化标记，才能构建可靠的代码资源配额模型。本章从异常事件的四种基本类型出发，逐步深入到采集与标记的工程实践。

3.1 异常事件的四大分类

根据异常对系统行为的影响模式，我们将异常事件划分为以下四类：

3.2 异常事件的生命周期与状态转换

下图展示了四种异常事件在请求处理管道中的典型触发位置与状态转换关系：

3.3 异常事件的采集策略

异常事件的采集需要覆盖三个关键维度：时间维度、空间维度 和 上下文维度。以下表格总结了各维度的采集要点：

3.4 异常事件的标记规范

标准化标记是异常事件可观测性的基础。我们推荐使用 结构化事件标记 方案，每个异常事件包含以下核心字段：

{
  "event_type": "timeout|rate_limited|circuit_broken|degraded",
  "event_id": "uuid-v4",
  "timestamp": "2025-03-15T10:30:00.123Z",
  "service": "payment-service",
  "instance": "pod-abc-123",
  "request_id": "req-456-def",
  "quota_key": "user:98765:api:v2",
  "duration_ms": 2500,
  "threshold_ms": 2000,
  "error_code": "TIMEOUT_READ",
  "severity": "warning|error|critical"
}

3.5 代码示例：异常事件的采集与标记

以下 Python 示例展示了如何在请求处理管道中采集超时和限流事件，并生成标准化标记：

import time
import uuid
import logging
from dataclasses import dataclass, asdict
from typing import Optional

logger = logging.getLogger("requests_limits.observer")

@dataclass
class AnomalyEvent:
    event_type: str
    event_id: str
    timestamp: str
    service: str
    instance: str
    request_id: str
    quota_key: str
    duration_ms: float
    threshold_ms: Optional[float] = None
    error_code: str = ""
    severity: str = "warning"

def collect_timeout_event(request, duration_ms, threshold_ms):
    """采集超时事件并标记"""
    event = AnomalyEvent(
        event_type="timeout",
        event_id=str(uuid.uuid4()),
        timestamp=time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
        service=request.service_name,
        instance=request.instance_id,
        request_id=request.request_id,
        quota_key=request.quota_key,
        duration_ms=duration_ms,
        threshold_ms=threshold_ms,
        error_code="TIMEOUT_READ",
        severity="error" if duration_ms > threshold_ms * 2 else "warning"
    )
    # 输出结构化日志
    logger.warning("anomaly_event", extra=asdict(event))
    return event

def collect_rate_limited_event(request, current_rate, limit_rate):
    """采集限流事件并标记"""
    event = AnomalyEvent(
        event_type="rate_limited",
        event_id=str(uuid.uuid4()),
        timestamp=time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
        service=request.service_name,
        instance=request.instance_id,
        request_id=request.request_id,
        quota_key=request.quota_key,
        duration_ms=0.0,
        threshold_ms=float(limit_rate),
        error_code="RATE_LIMIT_EXCEEDED",
        severity="warning"
    )
    logger.warning("anomaly_event", extra=asdict(event))
    return event

3.6 异常事件与配额模型的关联

在代码资源配额模型中，异常事件不仅是观测信号，更是 配额调整的输入。下表总结了四类异常事件如何影响配额决策：