《互联网产品的 AI 架构·平台化与治理》10.3 平台自身的 SLO 与容量

燃烧率 = (已用失败 / 错误预算) ÷ (已过时间 / 窗口长度)

// file: src/gov/platform-slo.ts
// tier: L2
// verify: node --test test/gov/platform-eng.test.ts

import { AiError } from "../core/errors.ts";

/** 平台只对三个共享部件承诺 SLO；业务链路的 SLO 由调用方自己承诺。 */
export type PlatformComponent = "gateway" | "quota" | "eval";

export interface SloTarget {
  component: PlatformComponent;
  /** 用基点表示，9995 = 99.95%；整数比较避免浮点边界。 */
  targetBps: number;
  windowMinutes: number;
}

export interface SloWindow {
  component: PlatformComponent;
  totalEvents: number;
  badEvents: number;
  /** 已过去的窗口长度；用于计算燃烧率，必须小于等于 windowMinutes。 */
  elapsedMinutes: number;
  windowMinutes: number;
}

export type SloState = "healthy" | "at-risk" | "exhausted";
export type SloAction = "normal" | "review" | "freeze";

export interface SloReport {
  component: PlatformComponent;
  targetBps: number;
  actualBps: number;
  budgetEvents: number;
  badEvents: number;
  remainingEvents: number;
  consumedRatio: number;
  burnRate: number;
  projectedBadEvents: number;
  state: SloState;
  action: SloAction;
}

/**
 * 错误预算按事件数算：预算 = 总事件 × (1 - 目标)。
 * 燃烧率 = 已用预算比例 ÷ 已过窗口比例；2 倍燃烧率进入 review，预算用尽即 freeze。
 */
export function evaluateSlo(target: SloTarget, window: SloWindow): SloReport {
  if (target.component !== window.component) {
    throw new AiError("invalid-request", "platform-slo: component mismatch");
  }
  if (!Number.isInteger(target.targetBps) || target.targetBps <= 0 || target.targetBps > 10_000) {
    throw new AiError("invalid-request", `platform-slo: bad target ${target.targetBps}`);
  }
  if (!Number.isInteger(window.totalEvents) || window.totalEvents < 0
    || !Number.isInteger(window.badEvents) || window.badEvents < 0
    || window.badEvents > window.totalEvents) {
    throw new AiError("invalid-request", "platform-slo: bad event counts");
  }
  if (!(window.elapsedMinutes >= 0) || !(window.windowMinutes > 0)
    || window.elapsedMinutes > window.windowMinutes) {
    throw new AiError("invalid-request", "platform-slo: bad window");
  }
  const budgetEvents = Math.floor((window.totalEvents * (10_000 - target.targetBps)) / 10_000);
  const remainingEvents = budgetEvents - window.badEvents;
  const actualBps = window.totalEvents === 0
    ? 10_000
    : Math.floor(((window.totalEvents - window.badEvents) * 10_000) / window.totalEvents);
  const consumedRatio = budgetEvents === 0
    ? (window.badEvents > 0 ? 1 : 0)
    : window.badEvents / budgetEvents;
  const elapsedRatio = window.elapsedMinutes / window.windowMinutes;
  const burnRate = elapsedRatio === 0 ? 0 : consumedRatio / elapsedRatio;
  const projectedBadEvents = elapsedRatio === 0
    ? window.badEvents
    : Math.round(window.badEvents / elapsedRatio);
  const exhausted = window.badEvents >= budgetEvents && (budgetEvents > 0 || window.badEvents > 0);
  const state: SloState = exhausted ? "exhausted" : burnRate >= 2 ? "at-risk" : "healthy";
  const action: SloAction = state === "exhausted" ? "freeze" : state === "at-risk" ? "review" : "normal";
  return {
    component: target.component,
    targetBps: target.targetBps,
    actualBps,
    budgetEvents,
    badEvents: window.badEvents,
    remainingEvents,
    consumedRatio,
    burnRate,
    projectedBadEvents,
    state,
    action,
  };
}

/** 三个部件的目标来自平台对业务方的承诺，不由业务团队各自解释。 */
export const PLATFORM_SLO: readonly SloTarget[] = [
  { component: "gateway", targetBps: 9995, windowMinutes: 43_200 },
  { component: "quota", targetBps: 9999, windowMinutes: 43_200 },
  { component: "eval", targetBps: 9990, windowMinutes: 43_200 },
];

// ---- 容量规划：从业务峰值推到每个部件的实例数 ----

export interface CapacityComponent {
  component: PlatformComponent;
  /** 每千次业务请求需要该部件处理的次数；配额服务是 3 次。 */
  callsPerMilleRequests: number;
  /** 单个实例在目标延迟内能承受的请求数。 */
  rpsPerUnit: number;
}

export interface CapacityPlanInput {
  currentPeakRps: number;
  /** 月增长，基点表示，300 = 3.00%。 */
  monthlyGrowthBps: number;
  /** 预留余量，3000 = 30%。 */
  headroomBps: number;
  months: number;
  components: readonly CapacityComponent[];
}

export interface CapacityMonth {
  month: number;
  peakRps: number;
}

export interface CapacityNeed {
  component: PlatformComponent;
  requiredRps: number;
  units: number;
}

export interface CapacityPlan {
  months: CapacityMonth[];
  needs: CapacityNeed[];
}

/** 按月复利外推峰值，再乘部件调用倍率与余量；实例数一律向上取整。 */
export function planCapacity(input: CapacityPlanInput): CapacityPlan {
  if (!(input.currentPeakRps > 0) || !Number.isInteger(input.months) || input.months < 1) {
    throw new AiError("invalid-request", "platform-slo: bad capacity input");
  }
  if (input.monthlyGrowthBps < 0 || input.headroomBps < 0) {
    throw new AiError("invalid-request", "platform-slo: growth and headroom must be non-negative");
  }
  const months: CapacityMonth[] = [{ month: 0, peakRps: input.currentPeakRps }];
  let peak = input.currentPeakRps;
  for (let month = 1; month <= input.months; month += 1) {
    peak = Math.round((peak * (10_000 + input.monthlyGrowthBps)) / 10_000);
    months.push({ month, peakRps: peak });
  }
  const horizon = peak;
  const needs = input.components.map((component): CapacityNeed => {
    const raw = (horizon * component.callsPerMilleRequests) / 1_000;
    const requiredRps = Math.ceil((raw * (10_000 + input.headroomBps)) / 10_000);
    return {
      component: component.component,
      requiredRps,
      units: Math.ceil(requiredRps / component.rpsPerUnit),
    };
  });
  return { months, needs };
}

// ---- 平台故障时，业务侧看到的降级行为必须事先写死 ----

export type PlatformFailure = "unavailable" | "latency" | "partial";

export interface DegradationRule {
  component: PlatformComponent;
  failure: PlatformFailure;
  businessBehavior: string;
  /** true 表示业务可继续用旧配置/旧结果，false 表示必须拒绝新请求。 */
  failOpen: boolean;
  maxStaleMs: number;
}

export const DEGRADATION_RULES: readonly DegradationRule[] = [
  {
    component: "gateway", failure: "unavailable",
    businessBehavior: "SDK 切备用区域；无备用区域时返回 503 与 Retry-After，展示兜底文案",
    failOpen: false, maxStaleMs: 0,
  },
  {
    component: "quota", failure: "unavailable",
    businessBehavior: "只放行预授权额度内的请求，超出即拒绝；不做全量放行",
    failOpen: false, maxStaleMs: 60_000,
  },
  {
    component: "eval", failure: "unavailable",
    businessBehavior: "冻结发布与配置放量，线上按现有版本继续服务",
    failOpen: true, maxStaleMs: 0,
  },
];

export function degradationFor(
  component: PlatformComponent,
  failure: PlatformFailure,
): DegradationRule | undefined {
  return DEGRADATION_RULES.find(
    (rule) => rule.component === component && rule.failure === failure,
  );
}