配套代码 on Dorkytiger 的小屋

配套代码：A/B/A' 对照编排与环境漂移检测

Mon, 01 Jan 0001 00:00:00 +0000

5.1 配套代码：A/B/A’ 对照编排与环境漂移检测

对应小节：5.1 单变量与对照组核心：回滚验证（A→B→A’） 能把「环境漂移」和「真实的优化效果」区分开。

一、A/B/A’ 实验编排脚本

#!/usr/bin/env bash
# tools/run-aba-experiment.sh <EXP_ID> <VARIANT_A_REF> <VARIANT_B_REF>
#
# 执行 A → B → A' 三轮对照实验。
# A  = 基线
# B  = 优化后的版本
# A' = 回滚到基线（用于检测环境漂移）
#
# 用法示例：
#   tools/run-aba-experiment.sh E06-index-opt main feature/add-index
set -euo pipefail

EXP_ID="${1:?usage: run-aba-experiment.sh <EXP_ID> <ref_A> <ref_B>}"
REF_A="${2:?}"
REF_B="${3:?}"
DIR="docs/experiments/${EXP_ID}"
ROUNDS="${ROUNDS:-3}"          # 每个变体跑几轮

mkdir -p "$DIR/results"

echo "═══ A/B/A' 对照实验：$EXP_ID ═══"
echo "  A  = $REF_A"
echo "  B  = $REF_B"
echo "  A' = $REF_A（回滚）"
echo "  每个变体 $ROUNDS 轮"
echo

# ① 环境元数据（只记录一次，因为环境应该不变）
tools/collect-env.sh "$EXP_ID"
tools/check-environment.sh "$EXP_ID"

run_variant() {
  local variant="$1"      # A / B / A2
  local ref="$2"

  echo "───────── 变体 $variant（$ref）─────────"

  # 切换到对应版本
  git checkout "$ref" -- . 2>/dev/null || {
    echo "❌ 无法切换到 $ref，请确认分支/commit 存在且工作区干净"
    exit 1
  }
  echo "当前 commit: $(git rev-parse --short HEAD)"

  # 构建
  ./gradlew build -q

  for i in $(seq 1 "$ROUNDS"); do
    echo "  [轮 $i/$ROUNDS]"
    # 重启服务（确保同一初始状态）
    scripts/restart-app.sh "$DIR/results/gc-$variant-$i.log"
    sleep 5
    # 独立预热
    BASE_URL=http://127.0.0.1:8080 k6 run --quiet --vus 20 --duration 60s \
      loadtest/profile-constant.js > /dev/null
    # 正式测量
    BASE_URL=http://127.0.0.1:8080 RATE=500 DURATION=5m \
    k6 run --summary-export="$DIR/results/$variant-round-$i.json" \
           loadtest/profile-constant.js > /dev/null
    echo "    ✅ 完成"
  done
}

run_variant "A"  "$REF_A"
run_variant "B"  "$REF_B"
run_variant "A2" "$REF_A"

echo
echo "═══ 三轮完成，开始分析 ═══"
python3 tools/analyze-aba.py "$DIR/results"

二、A/B/A’ 结果分析（检测环境漂移）

# tools/analyze-aba.py <results_dir>
"""
分析 A/B/A' 三轮实验：
  - 计算每个变体的指标中位数
  - 检测环境漂移（A 与 A' 的差异）
  - 用 A 与 A' 的漂移幅度校正 B 的效应

判据：
  漂移 = |A' - A| / A
  如果 漂移 < 5%     → 环境稳定，B 的效应可信
  如果 漂移 5% ~ 15% → 环境有轻微漂移，B 的效应需要打折看待
  如果 漂移 > 15%    → 环境不稳定，实验需要重做
"""
import json
import pathlib
import statistics as st
import sys


def load_variant(results_dir, variant):
    """加载某个变体的所有轮次"""
    files = sorted(pathlib.Path(results_dir).glob(f"{variant}-round-*.json"))
    rounds = []
    for f in files:
        m = json.loads(f.read_text())["metrics"]
        d = m["http_req_duration"]
        rounds.append({
            "qps": m["http_reqs"]["rate"],
            "p50": d.get("med", 0),
            "p95": d.get("p(95)", 0),
            "p99": d.get("p(99)", 0),
            "err": m["http_req_failed"]["rate"],
        })
    return rounds


def summarize(rounds, key):
    vals = [r[key] for r in rounds]
    return {
        "values": vals,
        "median": st.median(vals),
        "stdev": st.stdev(vals) if len(vals) > 1 else 0.0,
        "cv": (st.stdev(vals) / st.median(vals) * 100) if len(vals) > 1 and st.median(vals) else 0.0,
    }


def main(results_dir):
    A = load_variant(results_dir, "A")
    B = load_variant(results_dir, "B")
    A2 = load_variant(results_dir, "A2")

    if not (A and B and A2):
        print(f"❌ 数据不全：A={len(A)} B={len(B)} A'={len(A2)} 轮")
        print("   请确认文件名格式为 A-round-1.json / B-round-1.json / A2-round-1.json")
        return

    print("═" * 72)
    print("A/B/A' 对照实验分析")
    print("═" * 72)
    print()

    for key, label in [("qps", "QPS"), ("p50", "P50(ms)"), ("p95", "P95(ms)"), ("p99", "P99(ms)")]:
        sa, sb, sa2 = summarize(A, key), summarize(B, key), summarize(A2, key)

        print(f"【{label}】")
        print(f"  A  : {sa['median']:8.2f}  轮间CV {sa['cv']:5.1f}%   值={[round(v,1) for v in sa['values']]}")
        print(f"  B  : {sb['median']:8.2f}  轮间CV {sb['cv']:5.1f}%   值={[round(v,1) for v in sb['values']]}")
        print(f"  A' : {sa2['median']:8.2f}  轮间CV {sa2['cv']:5.1f}%   值={[round(v,1) for v in sa2['values']]}")

        # 环境漂移
        drift = abs(sa2["median"] - sa["median"]) / sa["median"] * 100 if sa["median"] else 0
        # B 的效应
        effect = (sb["median"] - sa["median"]) / sa["median"] * 100 if sa["median"] else 0
        # 用漂移校正后的效应（取 A 和 A' 的平均作为"真实基线"）
        true_baseline = (sa["median"] + sa2["median"]) / 2
        corrected = (sb["median"] - true_baseline) / true_baseline * 100 if true_baseline else 0

        print(f"  环境漂移 |A' - A| / A = {drift:5.1f}%")
        print(f"  B 的原始效应            = {effect:+6.1f}%")
        print(f"  用漂移校正后的效应       = {corrected:+6.1f}%")

        if drift < 5:
            print("  ✅ 环境稳定，B 的效应可信")
        elif drift < 15:
            print("  ⚠️  环境有轻微漂移，建议以【校正后的效应】作为结论")
        else:
            print("  ❌ 环境不稳定（漂移 > 15%），实验需要重做")

        # 与噪声底线的对比提示
        max_cv = max(sa["cv"], sb["cv"], sa2["cv"])
        if max_cv > 10:
            print(f"  ⚠️  轮间 CV 最大 {max_cv:.1f}% > 10%，环境噪声偏大（第 7 节）")
        print()

    print("═" * 72)
    print("结论怎么写（模板）：")
    print()
    print("  变体 A（基线）P99 中位数 = ___ ms（轮间 CV ___%）")
    print("  变体 B（优化）P99 中位数 = ___ ms")
    print("  变体 A'（回滚）P99 中位数 = ___ ms")
    print()
    print("  环境漂移 = ___%（< 5% 说明环境稳定）")
    print("  优化效应 = ___%（校正后 ___%）")
    print("  与噪声底线（___%）对比：☐ 大于 ☐ 小于")
    print("  统计检验：Mann-Whitney U, p = ___")
    print("  结论：☐ 优化有效且可信 ☐ 无法确认 ☐ 环境不稳定需重做")
    print("═" * 72)


if __name__ == "__main__":
    main(sys.argv[1] if len(sys.argv) > 1 else "docs/experiments/E06/results")

三、预期输出

════════════════════════════════════════════════════════════════════════
A/B/A' 对照实验分析
════════════════════════════════════════════════════════════════════════

【P99(ms)】
  A  :   210.30  轮间CV   2.1%   值=[207.5, 210.3, 213.1]
  B  :    95.20  轮间CV   3.1%   值=[93.2, 95.2, 96.1]
  A' :   208.70  轮间CV   1.8%   值=[206.9, 208.7, 211.4]
  环境漂移 |A' - A| / A =   0.8%
  B 的原始效应            = -54.7%
  用漂移校正后的效应       = -54.4%
  ✅ 环境稳定，B 的效应可信

这份结论的完整表述：

配套代码：k6 进阶用法与压测机自查

Mon, 01 Jan 0001 00:00:00 +0000

4.1 配套代码：k6 进阶用法与压测机自查

对应小节：4.1 负载生成器基础的三种曲线在第 3 章 code 04，这里只给本章新增的部分。

一、多场景组合（一个脚本测多种流量）

// loadtest/multi-scenario.js
import http from 'k6/http';
import { check } from 'k6';
import { Trend, Rate, Counter } from 'k6/metrics';

// 自定义指标（对应第 1 章的四层指标）
const readLatency = new Trend('read_latency_ms', true);
const writeLatency = new Trend('write_latency_ms', true);
const businessErrors = new Counter('business_errors');
const okRate = new Rate('ok_rate');

export const options = {
  scenarios: {
    // 读路径：占 90% 流量，开环恒定
    read_path: {
      executor: 'constant-arrival-rate',
      rate: 450, timeUnit: '1s', duration: '10m',
      preAllocatedVUs: 500, maxVUs: 3000,
      exec: 'readScenario',
      tags: { path: 'read' },
    },
    // 写路径：占 10% 流量，开环较低速率
    write_path: {
      executor: 'constant-arrival-rate',
      rate: 50, timeUnit: '1s', duration: '10m',
      preAllocatedVUs: 200, maxVUs: 1000,
      exec: 'writeScenario',
      startTime: '30s',              // 错开启动，避免冷启动叠加
      tags: { path: 'write' },
    },
  },
  thresholds: {
    'http_req_failed{path:read}': ['rate<0.01'],
    'http_req_duration{path:read}': ['p(99)<200'],
    'read_latency_ms': ['p(99)<200'],
    'write_latency_ms': ['p(99)<500'],
    ok_rate: ['rate>0.99'],
    business_errors: ['count<100'],
  },
  discardResponseBodies: true,
  summaryTrendStats: ['avg', 'min', 'med', 'p(90)', 'p(95)', 'p(99)', 'p(99.9)', 'max'],
};

function zipf(max) {
  return Math.max(1, Math.floor(max * Math.pow(Math.random(), 3)) + 1);
}

export function readScenario() {
  const res = http.get(`${__ENV.BASE_URL}/orders/${zipf(1_000_000)}`, {
    tags: { name: 'GET /orders/{id}' },      // ⚠️ 路由模板，不是具体 URL
  });
  readLatency.add(res.timings.duration);
  const ok = check(res, { 'read ok': (r) => r.status === 200 });
  okRate.add(ok);
  if (!ok) businessErrors.add(1);
}

export function writeScenario() {
  const payload = JSON.stringify({ userId: Math.floor(Math.random() * 1000) + 1, amount: 100 });
  const res = http.post(`${__ENV.BASE_URL}/orders`, payload, {
    headers: { 'Content-Type': 'application/json', 'X-Load-Test': 'true' },
    tags: { name: 'POST /orders' },
  });
  writeLatency.add(res.timings.duration);
  const ok = check(res, { 'write ok': (r) => r.status === 201 });
  okRate.add(ok);
  if (!ok) businessErrors.add(1);
}

两个值得注意的写法：

配套代码：从延迟分解到优先级排序

Mon, 01 Jan 0001 00:00:00 +0000

7.1 配套代码：从延迟分解到优先级排序

对应小节：7.1 优先级金字塔把「延迟分解的结果」自动映射到「该从哪一级开始优化」。

一、延迟分解 → 层级映射

# tools/prioritize.py
"""
从延迟分解结果推导优化优先级。

输入：各段的占比（可从第 6.2 节的 decompose-latency.py 得到）
输出：按层级排序的优化建议
"""
import sys

# 延迟分解的段 → 对应的金字塔层级与典型动作
SEGMENT_TO_LEVEL = {
    "client_queue": {
        "label": "网络 + 客户端排队",
        "level": 1,
        "level_name": "① 先问要不要做",
        "actions": [
            "减少返回字段（少传数据 → 省 CPU/内存/网络）",
            "启用响应压缩（大响应体）",
            "就近部署（CDN / 同可用区）",
            "检查压测客户端是否与被测服务同机",
        ],
    },
    "service_queue": {
        "label": "服务排队（进 handler 之前）",
        "level": 3,
        "level_name": "③ 架构与并发",
        "actions": [
            "查连接池 pending（第 6.5 节）",
            "查线程池队列深度",
            "检查 RUNNABLE 线程数 vs CPU 核数（调度器污染）",
            "检查容器 CPU 节流（第 4.8 节）",
            "检查是否有阻塞调用在 Dispatchers.Default 上",
        ],
    },
    "app_self": {
        "label": "应用自身（序列化、业务逻辑）",
        "level": 5,
        "level_name": "⑤ 微观常数",
        "actions": [
            "采 CPU 火焰图找热点（第 6.3 节）",
            "检查是否重复序列化（JSON → Map → JSON）",
            "检查热路径日志",
            "检查装箱/对象拷贝（收益通常是个位数 %）",
        ],
    },
    "postgres": {
        "label": "PostgreSQL",
        "level": 2,
        "level_name": "② 算法与数据访问",
        "actions": [
            "查 pg_stat_statements 的 calls（N+1）与 mean（慢查询）",
            "EXPLAIN (ANALYZE, BUFFERS) 检查执行计划",
            "检查缺失的索引",
            "检查事务范围是否过大",
        ],
    },
    "redis": {
        "label": "Redis",
        "level": 2,
        "level_name": "② 算法与数据访问",
        "actions": [
            "检查大 key / 热 key",
            "检查是否有 O(N) 命令（KEYS/HGETALL 大集合）",
            "检查是否重复查询同一个 key",
        ],
    },
    "downstream": {
        "label": "下游 HTTP",
        "level": 3,
        "level_name": "③ 架构与并发",
        "actions": [
            "检查是否串行调用多个独立下游（可并行化）",
            "检查下游本身的健康度",
            "加隔板（为每个下游分配独立资源）",
            "加熔断（下游持续失败时快速失败）",
        ],
    },
}


def prioritize(segments):
    """segments: [(key, 占比%)]，按占比排序并给出层级建议"""
    print("═" * 78)
    print("优化优先级：从延迟分解推导")
    print("═" * 78)
    print()

    # 按占比排序
    ranked = sorted(segments, key=lambda x: -x[1])

    print(f"{'段':<30}{'占比':>8}{'金字塔层级':<20}{'优先级'}")
    print("-" * 78)
    for i, (key, pct) in enumerate(ranked, 1):
        info = SEGMENT_TO_LEVEL.get(key)
        if not info:
            print(f"{key:<30}{pct:>7.1f}%  {'（未知）':<20}")
            continue
        print(f"{info['label']:<30}{pct:>7.1f}%  {info['level_name']:<20}第 {i}")

    print()
    print("═" * 78)
    print("详细建议（按优先级）")
    print("═" * 78)

    for i, (key, pct) in enumerate(ranked, 1):
        info = SEGMENT_TO_LEVEL.get(key)
        if not info:
            continue
        print()
        print(f"【优先级 {i}】{info['label']} —— {pct:.1f}%")
        print(f"  层级：{info['level_name']}")
        print(f"  优化收益上限：{pct:.1f}%（即使降为 0）")
        print(f"  建议动作：")
        for a in info["actions"]:
            print(f"    - {a}")

    print()
    print("═" * 78)
    print("三个提醒：")
    print("  ① 从占比最大的一段开始 —— 它的收益上限最高")
    print("  ② 不要跳过「① 先问要不要做」—— 有时最好的优化是少做一件事")
    print("  ③ 低级优化可能是高级优化的前提（例如先简化结构再加缓存），")
    print("     但这是「为了达成更大的目标」，不是为了顺手做")
    print("═" * 78)


if __name__ == "__main__":
    # 示例：从第 6.2 节的分解结果
    example_segments = [
        ("client_queue", 5.0),
        ("service_queue", 72.0),
        ("app_self", 3.25),
        ("postgres", 16.25),
        ("redis", 1.0),
        ("downstream", 2.0),
    ]
    prioritize(example_segments)

二、候选优化的排序器

# tools/rank-optimizations.py <optimizations.json>
"""
对候选优化排序：按「收益/成本比 + 金字塔层级」综合排序。

输入格式：
[
  {
    "name": "消除 N+1（批量查询）",
    "level": 2,
    "expected_benefit_pct": 70,
    "cost": "低",
    "risk": "低",
    "effort_days": 0.5
  },
  ...
]
"""
import json
import sys

LEVEL_WEIGHT = {1: 5.0, 2: 4.0, 3: 3.5, 4: 2.0, 5: 1.0, 6: 0.5}
COST_SCORE = {"低": 3.0, "中": 1.5, "高": 0.5}
RISK_SCORE = {"低": 3.0, "中": 1.5, "高": 0.5}


def score(opt):
    """
    综合得分 = 预期收益 × 层级权重 × 成本分 × 风险分 / 投入天数^0.5

    设计意图：
      - 层级越高（数字越小）权重越大
      - 成本/风险越高，得分越低
      - 投入天数开根号（避免低估快速见效的优化）
    """
    benefit = opt["expected_benefit_pct"]
    lv = LEVEL_WEIGHT.get(opt["level"], 1.0)
    cost = COST_SCORE.get(opt["cost"], 1.0)
    risk = RISK_SCORE.get(opt["risk"], 1.0)
    days = max(opt.get("effort_days", 1.0), 0.1)
    return benefit * lv * cost * risk / (days ** 0.5)


def main(path):
    opts = json.loads(open(path).read())
    ranked = sorted(opts, key=score, reverse=True)

    print("═" * 92)
    print("候选优化排序（综合：收益 × 层级 × 成本 × 风险 / 投入）")
    print("═" * 92)
    print()
    print(f"{'#':<4}{'优化':<34}{'层级':>5}{'收益%':>8}{'成本':>6}{'风险':>6}{'天数':>7}{'得分':>9}")
    print("-" * 92)
    for i, o in enumerate(ranked, 1):
        print(f"{i:<4}{o['name'][:32]:<34}{o['level']:>5}{o['expected_benefit_pct']:>8.0f}"
              f"{o['cost']:>6}{o['risk']:>6}{o.get('effort_days', 1):>7.1f}{score(o):>9.1f}")

    print()
    print("═" * 92)
    print("建议的执行顺序（前 3 项）：")
    for i, o in enumerate(ranked[:3], 1):
        print(f"  {i}. {o['name']}")
        print(f"     层级 {o['level']}，预期收益 {o['expected_benefit_pct']}%，"
              f"成本 {o['cost']}，风险 {o['risk']}，约 {o.get('effort_days', 1)} 天")
    print()
    print("注意：")
    print("  ⚠️  最后 2 项（通常是 JVM 调优与微观常数）建议【暂缓】——")
    print("      除非前面的优化已经做完且仍不达标")
    print("═" * 92)


if __name__ == "__main__":
    if len(sys.argv) < 2:
        # 用示例数据演示
        import tempfile, os
        demo = [
            {"name": "消除 N+1（批量查询）", "level": 2, "expected_benefit_pct": 70,
             "cost": "低", "risk": "低", "effort_days": 0.5},
            {"name": "把正则提到顶层", "level": 2, "expected_benefit_pct": 40,
             "cost": "低", "risk": "低", "effort_days": 0.2},
            {"name": "阻塞调用切到 Dispatchers.IO", "level": 3, "expected_benefit_pct": 60,
             "cost": "低", "risk": "中", "effort_days": 0.5},
            {"name": "加 Redis 缓存", "level": 4, "expected_benefit_pct": 50,
             "cost": "中", "risk": "高", "effort_days": 3.0},
            {"name": "换 ZGC", "level": 6, "expected_benefit_pct": 5,
             "cost": "高", "risk": "高", "effort_days": 5.0},
            {"name": "减少装箱", "level": 5, "expected_benefit_pct": 3,
             "cost": "中", "risk": "低", "effort_days": 2.0},
        ]
        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as f:
            json.dump(demo, f, ensure_ascii=False)
            path = f.name
        main(path)
        os.unlink(path)
    else:
        main(sys.argv[1])

预期输出（示例数据）：

配套代码：分析工作流与假设台账

Mon, 01 Jan 0001 00:00:00 +0000

6.1 配套代码：分析工作流与假设台账

对应小节：6.1 分析流程五步法两个工具：① 现象量化表模板；② 假设台账管理（让每个假设都有验证状态）。

一、现象量化表模板

<!-- docs/experiments/E07-incident-xxx/README.md 的「现象量化」章节 -->

## 现象量化

### 基本信息
| 维度 | 观测值 |
| --- | --- |
| 发现时间 | YYYY-MM-DD HH:MM |
| 报告人 | |
| 影响 | 用户投诉 / 监控告警 / 例行检查发现 |

### 谁慢
| 维度 | 观测值 |
| --- | --- |
| 接口 | |
| 实例范围 | 全部 / 部分（哪几台） |
| 请求范围 | 全部 / 特定参数 / 特定用户 |
| 依赖范围 | 是否与某个下游相关 |

### 多慢
| 指标 | 基线 | 当前 | 变化 |
| --- | --- | --- | --- |
| P50 | | | |
| P95 | | | |
| P99 | | | |
| 错误率 | | | |
| 超时率 | | | |
| QPS | | | |

### 从何时开始
| 问题 | 答案 |
| --- | --- |
| 突变还是渐变？ | |
| 与某次发布吻合？ | （版本号 + 时间） |
| 与数据量增长吻合？ | |
| 与外部事件吻合？ | （大促、其他服务上线） |

### 资源与饱和度（用于排除）
| 指标 | 基线 | 当前 | 是否异常 |
| --- | --- | --- | --- |
| CPU（user） | | | |
| CPU（sys） | | | |
| 内存 / 堆 | | | |
| GC 停顿 P99 | | | |
| 线程数 | | | |
| 连接池 pending | | | |
| 队列深度 | | | |
| 容器节流比例 | | | |

### 初步推论（由上面的数据排除/指向什么）
- QPS 未变 + CPU 未变 → 排除「过载」
- 只在特定参数上慢 → 指向数据访问路径
- 与发布吻合 → 高度怀疑该变更

为什么这张表这么重要：它把「接口慢了」这个模糊现象变成了一组可以排除假设的事实。填完它，假设空间通常能缩小到 2–3 个。

配套代码：台阶式提升与 PrintCompilation 解读

Mon, 01 Jan 0001 00:00:00 +0000

2.1 配套代码：台阶式提升与 PrintCompilation 解读

对应小节：2.1 四种执行形态要验证的结论：同一份代码在不同调用次数下的性能是台阶式变化的，不是渐变的。

一、实验：在不同调用次数下测量同一个方法

// src/main/kotlin/lesson02/ExecutionTiers.kt
package lesson02

import kotlin.random.Random

private var sink = 0L                     // 防止死代码消除

fun work(data: IntArray): Long {
    var s = 0L
    for (v in data) s += v
    return s
}

/**
 * 用「累计调用次数」作为横轴，观察性能台阶。
 * 每一档：先跑 total 次让 JIT 有机会编译，再测 measure 次的平均耗时。
 */
fun measureAt(totalInvocations: Int, measure: Int, data: IntArray): Double {
    repeat(totalInvocations) { sink += work(data) }        // 累积热度
    val t0 = System.nanoTime()
    repeat(measure) { sink += work(data) }
    val t1 = System.nanoTime()
    return (t1 - t0).toDouble() / measure
}

fun main() {
    val rnd = Random(42)
    val data = IntArray(4096) { rnd.nextInt() }

    println("累计调用次数        单次耗时(ns/op)")
    println("-".repeat(40))
    // 每一档都从一个"新进程的视角"重新累积是不现实的，
    // 所以这里用【单调递增】的累积次数：观察曲线是否台阶式下降
    for (total in listOf(10, 100, 500, 1_000, 5_000, 20_000, 100_000, 500_000)) {
        val ns = measureAt(total, 2_000, data)
        println("%,10d        %8.1f".format(total, ns))
    }
    println()
    println("sink = $sink   （确保计算没被优化掉）")
    println()
    println("预期形态：")
    println("  10 ~ 500      : 上千 ns（解释执行 / C1）")
    println("  1e3 ~ 2e4     : 快速下降（C2 介入）")
    println("  1e5 以后      : 平台（稳态）")
    println()
    println("注意：平台【不是突然到达】的，是渐近的 —— 这正是第 4 节要讲的稳态判定问题。")
}

二、预期输出形态

累计调用次数        单次耗时(ns/op)
----------------------------------------
        10            1312.4
       100             604.8
       500             391.2
     1,000             312.7
     5,000             261.4
    20,000             240.8
   100,000             231.2
   500,000             230.4

三、观察编译事件

java -XX:+PrintCompilation \
     -cp build/classes/kotlin/main lesson02.ExecutionTiersKt

输出形如：

配套代码：同一个函数，为什么测出三个不同的数字

Mon, 01 Jan 0001 00:00:00 +0000

0.1 配套代码：同一个函数，为什么测出三个不同的数字

对应小节：0.1 三类问题必须分开处理要验证的结论：「这段代码要 2 μs」是一个不完整的陈述——真实性能取决于它在什么环境下运行。

一、这段代码想说明什么

正文里有一句话：

「我测过 JSON 序列化只用 2 μs，一个请求 10 ms，所以序列化不是瓶颈。」——这句话的结论是错的，因为在真实并发下，同一个操作可能被放大几十倍。

这段代码就是把这句话变成可观察的数字：同一个函数，在三种环境下运行——

场景	环境	预期现象
A	单线程，无竞争	最快的数字（这就是「微基准」会给你的）
B	8 个线程同时调用，有共享锁	单次耗时大幅上升
C	单线程，但有持续的对象分配	耗时上升，且 GC 开始介入

二、代码

// src/main/kotlin/lesson00/ThreeKindsOfProblems.kt
package lesson00

import java.util.concurrent.CountDownLatch
import kotlin.concurrent.thread
import kotlin.system.measureNanoTime

/** 共享的「热点数据」，用于制造锁竞争 */
private val lock = Any()
private var sharedCounter = 0L

/**
 * 被测函数：模拟一次「有点计算量 + 需要访问共享资源」的操作。
 * 注意它是完全相同的代码，三种场景下不做任何修改。
 */
fun handleRequest(seed: Int): Long {
    // ① 一点本地计算（模拟业务逻辑）
    var local = seed.toLong()
    repeat(200) { local = local * 31 + it }

    // ② 访问共享资源（模拟写指标、更新缓存、计数器）
    synchronized(lock) {
        sharedCounter += local and 0xFF
        local += sharedCounter and 0x0F
    }

    // ③ 一点分配（模拟对象创建、序列化缓冲）
    val payload = ByteArray(256)
    payload[0] = local.toByte()
    return local + payload.size
}

/** 场景 A：单线程、无竞争 —— 这就是典型微基准会报告的"性能" */
fun scenarioA(iterations: Int): Long {
    waitForJit(iterations)
    return measureNanoTime {
        var sink = 0L
        repeat(iterations) { sink += handleRequest(it) }
        check(sink != Long.MIN_VALUE)
    } / iterations
}

/** 场景 B：8 线程争用同一把锁 */
fun scenarioB(iterations: Int, threads: Int = 8): Long {
    waitForJit(iterations)
    val perThread = iterations / threads
    val start = CountDownLatch(1)
    val done = CountDownLatch(threads)
    var totalElapsed = 0L

    repeat(threads) {
        thread {
            start.await()
            val elapsed = measureNanoTime {
                var sink = 0L
                repeat(perThread) { sink += handleRequest(it) }
                check(sink != Long.MIN_VALUE)
            }
            synchronized(lock) { totalElapsed = maxOf(totalElapsed, elapsed) }
            done.countDown()
        }
    }
    start.countDown()
    done.await()
    // 每个线程各自跑了 perThread 次，用时约等于最慢那个线程的耗时
    return totalElapsed / perThread
}

/** 场景 C：单线程，但持续分配大对象，制造 GC 压力 */
fun scenarioC(iterations: Int): Long {
    waitForJit(iterations)
    val garbage = ArrayList<ByteArray>(4096)
    return measureNanoTime {
        var sink = 0L
        repeat(iterations) { i ->
            sink += handleRequest(i)
            garbage.add(ByteArray(4096))          // 每秒产生大量垃圾
            if (garbage.size > 4096) garbage.clear()
        }
        check(sink != Long.MIN_VALUE)
    } / iterations
}

/** 预热：让 JIT 完成编译，否则测到的是解释执行阶段 */
private fun waitForJit(iterations: Int) {
    var sink = 0L
    repeat(iterations / 2) { sink += handleRequest(it) }
    check(sink != Long.MIN_VALUE)
}

fun main() {
    val n = 200_000
    println("同一个 handleRequest()，三种环境下运行：\n")
    println("A 单线程无竞争      : %6d ns/op".format(scenarioA(n)))
    println("B 8 线程争用同一把锁 : %6d ns/op".format(scenarioB(n)))
    println("C 单线程 + 分配压力  : %6d ns/op".format(scenarioC(n)))
    println("\n注意：三行是同一段代码。差别只来自运行环境。")
}

三、预期输出（形态）

同一个 handleRequest()，三种环境下运行：

A 单线程无竞争      :     82 ns/op
B 8 线程争用同一把锁 :   1840 ns/op
C 单线程 + 分配压力  :    260 ns/op

注意：三行是同一段代码。差别只来自运行环境。

你的数字会不同，但趋势应该一致：B 明显比 A 慢一个数量级以上。

配套代码：四层指标的埋点骨架

Mon, 01 Jan 0001 00:00:00 +0000

1.1 配套代码：四层指标的埋点骨架

对应小节：1.1 指标分四层这份代码是可以直接抄进项目的骨架。

一、注册表与四层指标的对应关系

// src/main/kotlin/metrics/MetricsRegistry.kt
package metrics

import com.zaxxer.hikari.HikariDataSource
import io.micrometer.core.instrument.Gauge
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.binder.jvm.*
import io.micrometer.core.instrument.binder.system.ProcessorMetrics
import io.micrometer.core.instrument.binder.system.FileDescriptorMetrics
import io.micrometer.prometheusmetrics.PrometheusConfig
import io.micrometer.prometheusmetrics.PrometheusMeterRegistry
import java.util.concurrent.ThreadPoolExecutor
import java.util.concurrent.atomic.AtomicInteger

val registry: PrometheusMeterRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT)

fun registerFourLayers(ds: HikariDataSource, executor: ThreadPoolExecutor) {

    // ══════════════════════════════════════════════════════════
    // 第 3 层：资源层 —— 消耗了什么
    // 这些 binder 会自动注册一批指标，不用手写
    // ══════════════════════════════════════════════════════════
    JvmMemoryMetrics().bindTo(registry)      // jvm_memory_used_bytes / max_bytes
    JvmGcMetrics().bindTo(registry)          // jvm_gc_pause_seconds（含分位数直方图）
    JvmThreadMetrics().bindTo(registry)      // jvm_threads_live / states
    ClassLoaderMetrics().bindTo(registry)    // 类加载数量（冷启动相关）
    ProcessorMetrics().bindTo(registry)      // system_cpu_usage / process_cpu_usage
    FileDescriptorMetrics().bindTo(registry) // 文件描述符使用（连接泄漏的第一信号）

    // ══════════════════════════════════════════════════════════
    // 第 4 层：饱和度层 —— 离上限还有多远（最重要的一层）
    // ══════════════════════════════════════════════════════════

    // 数据库连接池：pending 是最关键的指标
    Gauge.builder("db.pool.pending") { ds.hikariPoolMXBean?.threadsAwaitingConnection ?: 0 }
        .description("正在等待连接的线程数（> 0 说明已经排队）")
        .register(registry)

    Gauge.builder("db.pool.active") { ds.hikariPoolMXBean?.activeConnections ?: 0 }
        .description("正在被使用的连接数")
        .register(registry)

    Gauge.builder("db.pool.idle") { ds.hikariPoolMXBean?.idleConnections ?: 0 }
        .register(registry)

    Gauge.builder("db.pool.total") { ds.hikariPoolMXBean?.totalConnections ?: 0 }
        .register(registry)

    // 线程池队列深度：持续非空说明处理不过来
    Gauge.builder("executor.queue.depth") { executor.queue.size.toDouble() }
        .description("线程池等待队列长度")
        .register(registry)

    Gauge.builder("executor.queue.remaining") { executor.queue.remainingCapacity().toDouble() }
        .description("队列剩余容量（接近 0 说明即将开始拒绝）")
        .register(registry)

    Gauge.builder("executor.active") { executor.activeCount.toDouble() }
        .register(registry)
}

为什么 pending 比 active 更重要：active 高只说明「连接都在忙」，这是正常的；pending > 0 说明「已经有请求在排队等连接」——这是已经出问题的信号。

配套代码：渐进退化模拟与门禁经济性

Mon, 01 Jan 0001 00:00:00 +0000

8.1 配套代码：渐进退化模拟与门禁经济性

对应小节：8.1 为什么需要门禁两件事：① 用数据展示「渐进退化」如何逃过人工评审；② 算清门禁的经济性。

一、渐进退化模拟

# tools/simulate_gradual_degradation.py
"""
模拟「渐进退化」：每次改动只退化 3%~15%，看多久回到起点。

同时模拟「有门禁」的情况：阈值 25%，超过就拦住。
"""
import random


def simulate(months=12, changes_per_month=4, without_gate=True, seed=42):
    """
    模拟 12 个月的性能变化。

    每次改动的退化是随机的（0%~15%），偶尔有优化（-30%~-5%）。
    返回 (时间线, 最终值, 被拦住的次数)
    """
    rnd = random.Random(seed)
    p99 = 95.0                     # 起点（第 7 章优化后的值）
    baseline = 95.0                # 基线（有门禁时的对比对象）
    timeline = [(0, p99)]
    blocked = 0

    for month in range(1, months + 1):
        for _ in range(changes_per_month):
            r = rnd.random()
            if r < 0.15:
                # 15% 概率是一次优化
                change = -rnd.uniform(0.05, 0.30)
            elif r < 0.35:
                # 20% 概率是"看起来合理但退化"的改动（新增功能）
                change = rnd.uniform(0.03, 0.15)
            elif r < 0.45:
                # 10% 概率是数据量增长的影响
                change = rnd.uniform(0.05, 0.20)
            else:
                # 55% 概率是无影响的改动
                change = rnd.uniform(-0.02, 0.02)

            new_p99 = p99 * (1 + change)

            # 有门禁时：如果相对基线退化超过阈值，拦住
            if not without_gate:
                if (new_p99 - baseline) / baseline > 0.25:
                    blocked += 1
                    continue       # 这次改动被拦住，性能不变

            p99 = new_p99

        timeline.append((month, p99))

    return timeline, p99, blocked


def main():
    print("═" * 78)
    print("渐进退化模拟：12 个月，每月 4 次改动")
    print("═" * 78)
    print()

    # 无门禁
    tl_no, final_no, _ = simulate(without_gate=True)
    # 有门禁
    tl_yes, final_yes, blocked = simulate(without_gate=False)

    print(f"{'月份':<6}{'无门禁 P99':>14}{'有门禁 P99':>14}{'差异':>12}")
    print("-" * 78)
    for (m1, v1), (m2, v2) in zip(tl_no, tl_yes):
        diff = (v2 - v1) / v1 * 100 if v1 else 0
        print(f"{m1:<6}{v1:>13.1f}ms{v2:>13.1f}ms{diff:>11.1f}%")

    print()
    print("═" * 78)
    print("结论：")
    print(f"  无门禁：95.0ms → {final_no:.1f}ms（{final_no/95.0:.2f} 倍）")
    print(f"  有门禁：95.0ms → {final_yes:.1f}ms（{final_yes/95.0:.2f} 倍）")
    print(f"  门禁拦住了 {blocked} 次退化改动")
    print()

    if final_no > 200:
        print(f"  ⚠️  无门禁的情况下，P99 已经超过 200ms（SLO 违约）")
    print()
    print("关键观察：")
    print("  ① 每次改动的退化都在 3%~20% —— 【都在噪声范围内】")
    print("  ② 12 个月累积起来，性能可能翻倍甚至更多")
    print("  ③ 人工评审发现不了单次 5% 的退化（第 5.7 节的 MDD）")
    print("  ④ 门禁的作用是【拦住累积】，不是拦住单次")
    print("═" * 78)


if __name__ == "__main__":
    main()

预期输出：

配套代码：短链服务骨架与六颗埋雷

Mon, 01 Jan 0001 00:00:00 +0000

9.1 配套代码：短链服务骨架与六颗埋雷

对应小节：9.1 项目设定与埋雷清单 这是唯一一节需要写较多业务代码的地方——之后的章节都是编排与模板。

一、目录结构

src/main/kotlin/shortlink/
├── Application.kt              # Ktor 启动 + 指标注册
├── model/
│   ├── Link.kt                 # 领域模型
│   └── Dto.kt                  # request/response
├── service/
│   ├── LinkService.kt          # 业务逻辑（含埋雷 ⑥）
│   └── CodeGenerator.kt        # 短码生成（含埋雷 ⑥）
├── repository/
│   ├── LinkRepository.kt       # 数据访问（含埋雷 ① ② ④）
│   └── LinkCache.kt            # 缓存（含埋雷 ③）
├── http/
│   └── Routes.kt               # 路由（含埋雷 ⑤）
└── metrics/
    └── Metrics.kt              # 四层指标

二、领域模型与 DTO

// model/Link.kt
package shortlink.model

import java.time.Instant

data class Link(
    val id: Long,
    val code: String,
    val url: String,
    val userId: Long,
    val createdAt: Instant,
    val hits: Long,
)

// model/Dto.kt
package shortlink.model

import kotlinx.serialization.Serializable

@Serializable
data class CreateLinkRequest(val url: String, val userId: Long = 1)

@Serializable
data class CreateLinkResponse(val code: String)

三、埋雷 ⑥：`synchronized` 生成短码

// service/CodeGenerator.kt
package shortlink.service

import java.security.SecureRandom

private const val BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
private const val CODE_LENGTH = 6

class CodeGenerator {
    private val random = SecureRandom()

    /**
     * ═══ 埋雷 ⑥ ═══
     *
     * 问题：
     *   ① 用了 synchronized（线程级锁）—— 在协程里可能是"跨越挂起点的锁"
     *   ② 每次调用都新建 SecureRandom（其实可以用一个共享实例）
     *   ③ 冲突后的重试逻辑在 Service 层（见 LinkService）
     *
     * 症状：写路径偶发卡顿；线程 dump 可能出现 BLOCKED
     * 修法：改用 Mutex（协程感知），或去掉锁用 CAS 重试
     */
    @Synchronized
    fun generate(): String {
        val sb = StringBuilder(CODE_LENGTH)
        repeat(CODE_LENGTH) {
            sb.append(BASE62[random.nextInt(BASE62.length)])
        }
        return sb.toString()
    }
}

四、埋雷 ① ② ④：Repository 的三个问题

// repository/LinkRepository.kt
package shortlink.repository

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import shortlink.model.Link
import java.sql.Connection
import java.sql.ResultSet
import java.time.Instant
import javax.sql.DataSource

class LinkRepository(private val ds: DataSource) {

    /**
     * ═══ 埋雷 ① ═══
     * 建表时 code 列【没有唯一索引】→ 这条查询走全表扫描
     *
     * 症状：随数据量线性变慢（100 万行时约 380ms）
     * 验证：EXPLAIN (ANALYZE, BUFFERS) 会看到 Seq Scan
     * 修法：CREATE UNIQUE INDEX ON links(code)
     *
     * ═══ 埋雷 ④ ═══
     * 这里【没有】withContext(Dispatchers.IO)
     * → JDBC 是阻塞调用，直接跑在调用者的调度器上
     * → 如果调用者是 Dispatchers.Default（并行度=核数），会被占满
     *
     * 症状：CPU 低但所有接口一起慢
     * 验证：wall 火焰图 + RUNNABLE 线程数 == CPU 核数
     * 修法：withContext(Dispatchers.IO) + Semaphore 限流
     */
    suspend fun findByCode(code: String): Link? {
        return ds.connection.use { c ->              // ❌ 阻塞调用，未切调度器
            c.prepareStatement(
                "SELECT id, code, url, user_id, created_at, hits FROM links WHERE code = ?"
            ).use { ps ->
                ps.setString(1, code)
                ps.executeQuery().use { rs -> if (rs.next()) rs.toLink() else null }
            }
        }
    }

    suspend fun findById(id: Long): Link? {
        return ds.connection.use { c ->
            c.prepareStatement(
                "SELECT id, code, url, user_id, created_at, hits FROM links WHERE id = ?"
            ).use { ps ->
                ps.setLong(1, id)
                ps.executeQuery().use { rs -> if (rs.next()) rs.toLink() else null }
            }
        }
    }

    /**
     * ═══ 埋雷 ② ═══
     * 每次跳转都 UPDATE hits —— 写放大 + 行锁竞争
     *
     * 症状：高并发下热门短链的 UPDATE 争抢同一行锁；
     *       lock 火焰图有内容；pg_stat_activity 有 wait_event_type=Lock
     * 修法：批量/异步累加（但收益 < MDD，本 Lab 会否决它）
     */
    suspend fun incrementHits(id: Long) {
        ds.connection.use { c ->
            c.prepareStatement("UPDATE links SET hits = hits + 1 WHERE id = ?").use { ps ->
                ps.setLong(1, id)
                ps.executeUpdate()
            }
        }
    }

    suspend fun insert(code: String, url: String, userId: Long): Link {
        return ds.connection.use { c ->
            c.prepareStatement(
                "INSERT INTO links (code, url, user_id) VALUES (?, ?, ?) RETURNING id, created_at, hits"
            ).use { ps ->
                ps.setString(1, code)
                ps.setString(2, url)
                ps.setLong(3, userId)
                ps.executeQuery().use { rs ->
                    rs.next()
                    Link(rs.getLong(1), code, url, userId, rs.getTimestamp(2).toInstant(), rs.getLong(3))
                }
            }
        }
    }

    private fun ResultSet.toLink() = Link(
        getLong("id"), getString("code"), getString("url"),
        getLong("user_id"), getTimestamp("created_at").toInstant(), getLong("hits"),
    )
}

五、埋雷 ③：缓存 TTL 无抖动

// repository/LinkCache.kt
package shortlink.repository

import com.github.benmanes.caffeine.cache.Cache
import com.github.benmanes.caffeine.cache.Caffeine
import shortlink.model.Link
import java.time.Duration

class LinkCache {

    /**
     * ═══ 埋雷 ③ ═══
     * 所有 key 用【同一个固定 TTL】→ 同一批写入的 key 会同时失效
     *
     * 症状：数据库 QPS 出现周期性脉冲（每 10 分钟一次）
     *       —— 只有浸泡测试（≥1 小时）才能观察到
     * 验证：把 DB QPS 的脉冲时刻与 TTL(10min) 对齐
     * 修法：TTL 加随机抖动（±20%）
     */
    private val cache: Cache<String, Link> = Caffeine.newBuilder()
        .maximumSize(100_000)
        .expireAfterWrite(Duration.ofMinutes(10))       // ❌ 无抖动
        .recordStats()
        .build()

    fun get(code: String): Link? = cache.getIfPresent(code)

    fun put(code: String, link: Link) {
        cache.put(code, link)
    }

    fun invalidate(code: String) {
        cache.invalidate(code)
    }

    fun hitRate(): Double = cache.stats().hitRate()
    fun stats() = cache.stats()
}

六、Service 层：编排 + 短码冲突重试

// service/LinkService.kt
package shortlink.service

import shortlink.model.Link
import shortlink.repository.LinkCache
import shortlink.repository.LinkRepository
import org.slf4j.LoggerFactory

class LinkService(
    private val repo: LinkRepository,
    private val cache: LinkCache,
    private val codeGenerator: CodeGenerator,
) {
    private val log = LoggerFactory.getLogger(LinkService::class.java)

    /**
     * 读取路径：缓存优先，未命中查库并回填
     *
     * 注意：这里没有 withContext(Dispatchers.IO) —— 由 Repository 负责（而它也没有，
     *      所以整个链路跑在调用者的调度器上 → 埋雷 ④ 生效）
     */
    suspend fun resolve(code: String): Link? {
        // ① 先查缓存
        cache.get(code)?.let { return it }

        // ② 未命中 → 查库
        val link = repo.findByCode(code) ?: return null

        // ③ 回填缓存
        cache.put(code, link)

        // ④ 累加计数（埋雷 ②）
        repo.incrementHits(link.id)

        return link
    }

    /** 写入路径：生成短码 + 冲突重试 */
    suspend fun create(url: String, userId: Long): String {
        repeat(5) { attempt ->
            val code = codeGenerator.generate()        // 埋雷 ⑥：synchronized
            try {
                repo.insert(code, url, userId)
                return code
            } catch (e: Exception) {
                // 唯一索引冲突（code 已存在）—— 这是【正常业务】，不是故障
                if (isUniqueViolation(e)) {
                    log.debug("code collision on attempt {}: {}", attempt, code)
                    // 继续重试
                } else {
                    throw e
                }
            }
        }
        throw IllegalStateException("failed to generate unique code after 5 attempts")
    }

    private fun isUniqueViolation(e: Exception): Boolean =
        e.message?.contains("duplicate key") == true ||
        e.message?.contains("unique constraint") == true
}

注意 isUniqueViolation 这一段的含义：

配套代码：CI 微基准门禁

Mon, 01 Jan 0001 00:00:00 +0000

8.2 配套代码：CI 微基准门禁

对应小节：8.2 CI 微基准门禁四个部分：① CI workflow；② 比较脚本；③ 噪声分析；④ 误报日志。

一、CI workflow（完整版）

# .github/workflows/perf-gate.yml
name: perf-gate

on:
  push:
    branches: [main]              # ⚠️ 只在主干跑
  workflow_dispatch:

jobs:
  micro-benchmark:
    # ⚠️ 生产项目应使用自建、规格固定的 runner
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'

      - uses: actions/cache@v4
        with:
          path: ~/.gradle
          key: gradle-${{ hashFiles('**/*.gradle.kts') }}

      # ① 记录 CI 环境（用于判断"环境是否变化"）
      - name: Record CI environment
        run: |
          {
            echo "runner_os=$(uname -s -r -m)"
            echo "cpus=$(nproc)"
            echo "mem=$(free -h | awk '/Mem:/{print $2}')"
            echo "java=$(java -version 2>&1 | head -1)"
            echo "commit=${{ github.sha }}"
          } | tee perf-ci-env.txt

      # ② 跑基准
      - name: Run benchmarks
        run: ./gradlew benchmark -q

      # ③ 与基线对比
      #    ⚠️ 第一阶段用 --report-only（只报告不失败），观察两周确认零误报
      #       第二阶段去掉 --report-only 启用失败
      - name: Compare against baseline
        id: compare
        continue-on-error: true
        run: |
          python3 tools/compare_benchmark.py \
            build/reports/benchmarks/main.json \
            perf/baseline.json \
            --threshold 0.25 \
            --report-only \
            --output perf-result.md

      # ④ 把结果写到 CI 摘要（开发者不用点开日志就能看到）
      - name: Publish summary
        if: always()
        run: |
          cat perf-result.md >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### CI 环境" >> $GITHUB_STEP_SUMMARY
          cat perf-ci-env.txt >> $GITHUB_STEP_SUMMARY

      # ⑤ 上传原始数据（便于事后分析）
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: benchmark-results-${{ github.sha }}
          path: |
            build/reports/benchmarks/
            perf-result.md
            perf-ci-env.txt

      # ⑥ 启用失败（第二阶段才打开）
      # - name: Fail on regression
      #   if: steps.compare.outcome == 'failure'
      #   run: exit 1

注意第 ③ 步的注释：先用 --report-only 观察两周——这是避免门禁被过早讨厌的关键（第 8.2 节）。

配套代码：SLO 表与延迟预算校验

Mon, 01 Jan 0001 00:00:00 +0000

9.2 配套代码：SLO 表与延迟预算校验

对应小节：9.2 步骤一：定义目标

一、SLO 定义文件

# perf/slo.yaml —— 单一事实源：文档、门禁、告警都从这里读
service: shortlink
version: "1.0"
owner: "@backend-team"
updated: "2024-06-01"

slis:
  # ── 接口级 ──
  - name: redirect_latency
    description: "跳转接口的端到端延迟"
    metric: "http_server_requests_seconds"
    labels: { uri: "/{code}", method: GET }
    unit: ms

  - name: create_latency
    description: "创建接口的端到端延迟"
    metric: "http_server_requests_seconds"
    labels: { uri: "/links", method: POST }
    unit: ms

  - name: redirect_availability
    description: "跳转接口的成功率"
    metric: "app_requests_failed / app.requests.total"
    labels: { uri: "/{code}" }
    unit: ratio

  - name: dependency_latency
    description: "数据库查询延迟（依赖级）"
    metric: "app_db_query_seconds"
    unit: ms

# ── 关键：错误预算的分子要排除"正常业务失败" ──
exclusions:
  - "短码冲突（业务正常，重试成功）"
  - "用户输入的非法 URL（归 4xx，不计失败）"

slos:
  - sli: redirect_latency
    objective: "P99 < 100ms"
    window: "28d"
    error_budget: "1% 的请求可超 100ms"

  - sli: create_latency
    objective: "P99 < 200ms"      # 写路径预算更宽（有 INSERT）
    window: "28d"
    error_budget: "1%"

  - sli: redirect_availability
    objective: ">= 99.9%"
    window: "28d"
    error_budget: "0.1% = 43.2min/月"

  - sli: dependency_latency
    objective: "P99 < 60ms"       # 依赖预算 = 端到端预算的一部分
    window: "28d"

budget:
  latency_budget:
    total_ms: 100
    allocations:
      - { component: "网关/负载均衡", ms: 5,  type: serial }
      - { component: "Ktor 路由与序列化", ms: 5, type: serial }
      - { component: "业务逻辑", ms: 10, type: serial }
      - { component: "数据库查询", ms: 60, type: critical, parallel_with: ["缓存查询"] }
      - { component: "缓存查询", ms: 2,  type: parallel }
      - { component: "余量", ms: 18, type: reserve }
    notes: |
      数据库与缓存是【互斥】的（缓存未命中才查库），
      所以最大路径 = 串行部分 + max(数据库, 缓存) = 80 + 60 = 140ms？❌

      不对 —— 串行部分只有 网关+路由+业务 = 20ms，
      加上 max(60, 2) = 60ms，总计 80ms，留 20ms 余量 ✅

二、延迟预算校验器

#!/usr/bin/env python3
"""tools/validate-budget.py —— 校验延迟预算是否自洽

只做三件事：
  1. 串行项相加 + 并行项取最大 <= 总预算
  2. 每项都有明确的 type（serial/parallel/critical/reserve）
  3. 余量 >= 20%（否则没有容错空间）
"""
import sys
import yaml


def validate(path: str) -> int:
    with open(path) as f:
        slo = yaml.safe_load(f)

    budget = slo["budget"]["latency_budget"]
    total = budget["total_ms"]
    allocs = budget["allocations"]

    errors = []

    # ── ① 每项必须声明 type ──
    for a in allocs:
        if "type" not in a:
            errors.append(f"「{a['component']}」缺少 type 字段")

    serial = [a for a in allocs if a["type"] in ("serial", "critical")]
    parallel = [a for a in allocs if a["type"] == "parallel"]
    reserve = [a for a in allocs if a["type"] == "reserve"]

    serial_sum = sum(a["ms"] for a in serial)
    parallel_max = max((a["ms"] for a in parallel), default=0)

    # ── ② 并行项必须真的并行（不能有依赖关系）──
    # 简化：只检查是否显式声明了 parallel_with
    for a in parallel:
        if "parallel_with" not in a:
            errors.append(
                f"「{a['component']}」标为 parallel 但未声明 parallel_with —— "
                f"无法证明它真的并行"
            )

    worst_path = serial_sum + parallel_max
    reserve_ms = sum(a["ms"] for a in reserve)
    reserve_pct = reserve_ms / total * 100

    # ── ③ 最坏路径 + 余量 <= 总预算 ──
    if worst_path + reserve_ms > total:
        errors.append(
            f"预算超支：最坏路径 {worst_path}ms + 余量 {reserve_ms}ms "
            f"= {worst_path + reserve_ms}ms > 总预算 {total}ms"
        )

    # ── ④ 余量比例 ──
    if reserve_pct < 20:
        errors.append(
            f"余量只有 {reserve_pct:.0f}%（< 20%）—— "
            f"没有容错空间，任何一项超支都会击穿 SLO"
        )

    # ── 输出 ──
    print(f"总预算：{total}ms")
    print(f"串行路径：{serial_sum}ms  " + " + ".join(f"{a['ms']}" for a in serial))
    print(f"并行取最大：{parallel_max}ms  " + ", ".join(a["component"] for a in parallel))
    print(f"最坏路径：{worst_path}ms")
    print(f"余量：{reserve_ms}ms ({reserve_pct:.0f}%)")
    print()

    if errors:
        print("❌ 预算校验失败：")
        for e in errors:
            print(f"   • {e}")
        return 1

    print("✅ 预算自洽")
    print()
    print(f"解读：最坏路径 {worst_path}ms，留 {total - worst_path}ms 余量")
    print(f"      → 只要依赖不超过各自预算，端到端不会击穿 {total}ms")
    return 0


if __name__ == "__main__":
    sys.exit(validate(sys.argv[1] if len(sys.argv) > 1 else "perf/slo.yaml"))

三、把 SLO 变成压测阈值

#!/usr/bin/env bash
# tools/gen-k6-thresholds.sh —— 从 slo.yaml 生成 k6 的 thresholds 片段
# 为什么这么做：阈值和 SLO 必须是【同一个数字】，否则会漂移
set -euo pipefail

SLO="${1:-perf/slo.yaml}"
OUT="perf/thresholds.js"

python3 - "$SLO" > "$OUT" <<'PY'
import sys, yaml

with open(sys.argv[1]) as f:
    slo = yaml.safe_load(f)

print("// 本文件由 tools/gen-k6-thresholds.sh 自动生成 —— 请勿手改")
print("// 改 SLO 请改 perf/slo.yaml，然后重跑生成脚本")
print("export const thresholds = {")

for s in slo["slos"]:
    sli = s["sli"]
    obj = s["objective"]                      # 例如 "P99 < 100ms"

    if "P99 <" in obj:
        ms = obj.split("<")[1].strip().rstrip("ms")
        # 门禁阈值 = SLO 阈值 × 1.0（不做额外收紧）
        # 为什么不像常规那样收紧 1.5 倍：这里是在【验证 SLO】，
        # 不是在【卡回归】——回归门禁见第 9.9 节
        print(f"  '{sli}': ['p(99)<{ms}'],")

print("};")
PY

echo "✅ 已生成 $OUT"
echo
cat "$OUT"

生成的片段：

配套代码：减少工作的五种模式

Mon, 01 Jan 0001 00:00:00 +0000

7.2 配套代码：减少工作的五种模式

对应小节：7.2 减少工作每种模式给「反例 → 正例 → 验证方法」，以及一份可自动扫描的审查清单。

一、❶ 批处理：N 次变 1 次

// ❌ 反例：N 次往返
suspend fun loadOrdersBad(ids: List<Long>): List<Order> =
    ids.map { repo.findById(it) ?: error("not found") }      // N 次查询

// ✅ 正例 1：批量查询（= any）
suspend fun loadOrdersGood(ids: List<Long>): List<Order> = withContext(Dispatchers.IO) {
    ds.connection.use { c ->
        c.prepareStatement("select id, user_id, amount from orders where id = any(?)").use { ps ->
            ps.setArray(1, c.createArrayOf("bigint", ids.toTypedArray()))
            ps.executeQuery().use { rs ->
                buildList { while (rs.next()) add(rs.toOrder()) }
            }
        }
    }
}

// ✅ 正例 2：分批（避免单次 IN 列表过长，也便于控制内存）
suspend fun loadOrdersBatched(ids: List<Long>, batchSize: Int = 500): List<Order> =
    ids.chunked(batchSize).flatMap { chunk -> loadOrdersGood(chunk) }

// ✅ 正例 3：并行分批（IO 密集，且下游能承受）
suspend fun loadOrdersParallel(ids: List<Long>, batchSize: Int = 500): List<Order> =
    coroutineScope {
        ids.chunked(batchSize)
            .map { chunk -> async(Dispatchers.IO) { loadOrdersGood(chunk) } }
            .awaitAll()
            .flatten()
    }

验证方法：

配套代码：延迟分解的 PromQL 与自动计算

Mon, 01 Jan 0001 00:00:00 +0000

6.2 配套代码：延迟分解的 PromQL 与自动计算

对应小节：6.2 延迟分解把「三段减法」变成可执行的查询与脚本。

一、三段分解的 PromQL

-- ═══════════════════════════════════════════════════════════
-- ① 服务端完整延迟（进入 handler 到响应写完）
-- ═══════════════════════════════════════════════════════════
histogram_quantile(0.99,
  sum by (le) (rate(http_server_requests_seconds_bucket{uri="/orders/{id}"}[5m])))

-- ═══════════════════════════════════════════════════════════
-- ② 应用内延迟（handler 内部）
-- ═══════════════════════════════════════════════════════════
histogram_quantile(0.99,
  sum by (le) (rate(app_handler_duration_seconds_bucket[5m])))

-- ═══════════════════════════════════════════════════════════
-- ③ 服务排队 = ① − ②
-- ═══════════════════════════════════════════════════════════
histogram_quantile(0.99,
  sum by (le) (rate(http_server_requests_seconds_bucket{uri="/orders/{id}"}[5m])))
-
histogram_quantile(0.99,
  sum by (le) (rate(app_handler_duration_seconds_bucket[5m])))

-- ═══════════════════════════════════════════════════════════
-- ④ 各依赖
-- ═══════════════════════════════════════════════════════════
histogram_quantile(0.99, sum by (le) (rate(dep_postgres_seconds_bucket[5m])))
histogram_quantile(0.99, sum by (le) (rate(dep_redis_seconds_bucket[5m])))
histogram_quantile(0.99, sum by (le) (rate(dep_downstream_seconds_bucket[5m])))

-- ═══════════════════════════════════════════════════════════
-- ⑤ 应用自身开销 = ② − Σ依赖
--    ⚠️ 只在【串行调用】时成立；并行调用会算出负数
-- ═══════════════════════════════════════════════════════════
histogram_quantile(0.99, sum by (le) (rate(app_handler_duration_seconds_bucket[5m])))
-
(
  histogram_quantile(0.99, sum by (le) (rate(dep_postgres_seconds_bucket[5m])))
  +
  histogram_quantile(0.99, sum by (le) (rate(dep_redis_seconds_bucket[5m])))
  +
  histogram_quantile(0.99, sum by (le) (rate(dep_downstream_seconds_bucket[5m])))
)

⚠️ 重要提醒：分位数相减是近似（第 6.2 节）。它适合判断「哪段是大头」，不适合精确归因。精确归因需要 tracing 的 span 树。

二、自动分解脚本（从 Prometheus 拉数据）

# tools/decompose-latency.py <PROMETHEUS_URL> <URI_LABEL> [--percentile 0.99]
"""
从 Prometheus 拉取各段延迟，生成分解表。

用法：
  python3 tools/decompose-latency.py http://localhost:9090 '/orders/{id}'
"""
import json
import sys
import urllib.parse
import urllib.request


def query(prom_url, expr):
    url = f"{prom_url}/api/v1/query?" + urllib.parse.urlencode({"query": expr})
    try:
        with urllib.request.urlopen(url, timeout=10) as r:
            data = json.load(r)
        if data["status"] != "success":
            return None
        result = data["data"]["result"]
        return float(result[0]["value"][1]) if result else None
    except Exception as e:
        print(f"  ⚠️  查询失败: {e}", file=sys.stderr)
        return None


def hq(metric, selector="", q=0.99):
    return (f'histogram_quantile({q}, sum by (le) '
            f'(rate({metric}_bucket{selector}[5m])))')


def main():
    prom = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:9090"
    uri = sys.argv[2] if len(sys.argv) > 2 else ""
    q = 0.99
    if "--percentile" in sys.argv:
        q = float(sys.argv[sys.argv.index("--percentile") + 1])

    print("═" * 70)
    print(f"延迟分解（P{q*100:.0f}，URI={uri or '全部'}）")
    print("═" * 70)
    print()

    selector = f'{{uri="{uri}"}}' if uri else ""

    segments = {
        "① 服务端完整延迟": hq("http_server_requests_seconds", selector, q),
        "② 应用内延迟": hq("app_handler_duration_seconds", "", q),
        "③ dep.postgres": hq("dep_postgres_seconds", "", q),
        "④ dep.redis": hq("dep_redis_seconds", "", q),
        "⑤ dep.downstream": hq("dep_downstream_seconds", "", q),
    }

    values = {}
    for label, expr in segments.items():
        v = query(prom, expr)
        values[label] = v

    server = values["① 服务端完整延迟"]
    inapp = values["② 应用内延迟"]
    deps = [values["③ dep.postgres"], values["④ dep.redis"], values["⑤ dep.downstream"]]

    def fmt(v):
        return f"{v*1000:.1f} ms" if v is not None else "n/a"

    # 打印各段
    print(f"{'段':<22}{'P' + str(int(q*100)):<10}{'占比'}")
    print("-" * 70)
    print(f"{'① 服务端完整延迟':<22}{fmt(server):<12}100%")
    print(f"{'② 应用内延迟':<22}{fmt(inapp):<12}"
          f"{(inapp/server*100):.1f}%" if server and inapp else "n/a")

    if server and inapp:
        queued = server - inapp
        print(f"{'③ 服务排队（①−②）':<22}{fmt(queued):<12}{queued/server*100:.1f}%")

    for label, v in zip(["④ dep.postgres", "⑤ dep.redis", "⑥ dep.downstream"], deps):
        if v is not None and server:
            print(f"{label:<22}{fmt(v):<12}{v/server*100:.1f}%")

    # 应用自身开销
    if inapp and all(d is not None for d in deps):
        dep_sum = sum(deps)
        self_cost = inapp - dep_sum
        print("-" * 70)
        if self_cost < 0:
            print(f"{'⑦ 应用自身（②−Σ依赖）':<22}{fmt(self_cost):<12}"
                  f"❌ 负数！说明链路中有并行调用，不能简单相减")
            print("   → 用 tracing 的 span 树看关键路径（第 6.2 节）")
        else:
            print(f"{'⑦ 应用自身（②−Σ依赖）':<22}{fmt(self_cost):<12}"
                  f"{self_cost/server*100:.1f}%")

    print()
    print("═" * 70)
    print("判读：")
    print("  哪一段占比最大，就从那一段开始排查。")
    print("  ⚠️  分位数相减是近似，只用于判断「哪段是大头」。")
    print("     精确归因请用 tracing span 树（同一批请求的各段耗时）。")
    print("═" * 70)


if __name__ == "__main__":
    main()

三、基于 tracing 的精确分解（推荐）

分位数相减是近似。精确做法是用 tracing：每个请求的 span 树里都有各段的真实耗时。

配套代码：时长规划与预热判定

Mon, 01 Jan 0001 00:00:00 +0000

5.2 配套代码：时长规划与预热判定

对应小节：5.2 预热、稳态与运行时长两件事：① 由周期推导时长；② 自动判定预热是否结束。

一、时长规划器

// src/main/kotlin/experiment/DurationPlanner.kt
package experiment

import kotlin.math.max

/**
 * 压测时长规划。
 *
 * 核心公式：稳态时长 ≥ 最长周期 × 2
 *   1 次 → 只能确认「这个事件发生过」
 *   2 次 → 能确认「它的影响是稳定的、可重复的」
 */
data class Periods(
    val gcOldGenMinutes: Double = 5.0,        // 从 GC 日志推算（两次 Full/Mixed GC 的间隔）
    val cacheTtlMinutes: Double = 30.0,       // 缓存 TTL（本地 + Redis，取较大者）
    val scheduledTaskMinutes: Double = 60.0,  // 最长定时任务间隔
    val poolRecycleMinutes: Double = 30.0,    // 连接池/线程池 idle 回收
    val warmupMinutes: Double = 2.0,          // 从滚动 CV 判定（第 2 章 2.4）
)

data class DurationPlan(
    val longestPeriodMinutes: Double,
    val warmupMinutes: Double,
    val steadyStateMinutes: Double,
    val totalMinutes: Double,
    val warnings: List<String>,
)

fun planDuration(p: Periods): DurationPlan {
    val longest = listOf(
        p.gcOldGenMinutes, p.cacheTtlMinutes, p.scheduledTaskMinutes, p.poolRecycleMinutes
    ).max()

    var steady = longest * 2
    val warnings = mutableListOf<String>()

    // 下限保护：即使公式算出更短，也至少 3 分钟
    if (steady < 3.0) {
        warnings += "按公式只需 %.1f 分钟，但低于 3 分钟会混入测量噪声与过渡态——已提升到 3 分钟"
            .format(steady)
        steady = 3.0
    }

    // 上限提醒：超过 2 小时成本过高，建议分层
    if (steady > 120) {
        warnings += "稳态需要 %.0f 分钟（> 2 小时），成本很高。建议：".format(steady)
        warnings += "  ① 测试环境可调短缓存 TTL（例如 30 分钟 → 5 分钟）"
        warnings += "  ② 把长周期问题交给专门的浸泡测试（1–12 小时），"
        warnings += "     日常优化验证只用 10–20 分钟覆盖 GC 周期"
    }

    // 检查是否某个周期被显著低估
    if (p.scheduledTaskMinutes < p.cacheTtlMinutes * 0.2) {
        warnings += "定时任务间隔（%.0f 分钟）远小于缓存 TTL（%.0f 分钟）——确认是否真的存在这么频繁的任务"
            .format(p.scheduledTaskMinutes, p.cacheTtlMinutes)
    }

    return DurationPlan(
        longestPeriodMinutes = longest,
        warmupMinutes = p.warmupMinutes,
        steadyStateMinutes = steady,
        totalMinutes = p.warmupMinutes + steady,
        warnings = warnings,
    )
}

/** 从实际场景推导周期（辅助函数） */
fun periodsFromGcLog(p99GcIntervalMinutes: Double, cacheTtl: Double, taskInterval: Double) =
    Periods(
        gcOldGenMinutes = p99GcIntervalMinutes,
        cacheTtlMinutes = cacheTtl,
        scheduledTaskMinutes = taskInterval,
        poolRecycleMinutes = cacheTtl / 2,     // 池回收通常与 TTL 同量级
    )

fun main() {
    println("═══ 场景一：典型 Web 服务 ═══")
    val p1 = Periods()   // 默认值
    printPlan(p1)

    println()
    println("═══ 场景二：轻量服务（周期都较短）═══")
    printPlan(Periods(
        gcOldGenMinutes = 2.0,
        cacheTtlMinutes = 10.0,
        scheduledTaskMinutes = 15.0,
        poolRecycleMinutes = 5.0,
    ))

    println()
    println("═══ 场景三：有每小时对账任务（成本高）═══")
    printPlan(Periods(
        gcOldGenMinutes = 5.0,
        cacheTtlMinutes = 30.0,
        scheduledTaskMinutes = 60.0,
        poolRecycleMinutes = 30.0,
    ))
}

private fun printPlan(p: Periods) {
    val plan = planDuration(p)
    println("各周期：GC %.0f / 缓存 %.0f / 定时任务 %.0f / 池回收 %.0f 分钟"
        .format(p.gcOldGenMinutes, p.cacheTtlMinutes, p.scheduledTaskMinutes, p.poolRecycleMinutes))
    println("最长周期 = %.0f 分钟".format(plan.longestPeriodMinutes))
    println("预热     = %.0f 分钟（不计入统计）".format(plan.warmupMinutes))
    println("稳态测量 = %.0f 分钟".format(plan.steadyStateMinutes))
    println("总时长   = %.0f 分钟".format(plan.totalMinutes))
    plan.warnings.forEach { println("  ⚠️  $it") }
}

预期输出：

配套代码：直方图合并实验

Mon, 01 Jan 0001 00:00:00 +0000

1.2 配套代码：直方图合并实验

对应小节：1.2 百分位不可平均要验证的结论：把多实例的 P99 求平均，会错得离谱且方向不确定；合并直方图才是正解。

一、先实现一个最小的直方图

真实系统里这件事由 Prometheus 的 histogram 完成，但自己实现一遍（30 行）能彻底消除困惑。

// src/main/kotlin/lesson01/BucketHistogram.kt
package lesson01

/**
 * 分桶直方图：只记录"每个桶里有多少个样本"。
 * 关键性质：**桶计数可以相加**，所以多实例的直方图能合并。
 *
 * @param bounds 桶的**上边界**（升序），例如 [5, 10, 20, 50, 100]
 *               最后一个桶是 (bounds.last(), +∞)
 */
class BucketHistogram(private val bounds: DoubleArray) {

    /** counts[i] = 落在第 i 个桶里的样本数；counts 比 bounds 多一个（溢出桶） */
    val counts = LongArray(bounds.size + 1)

    fun observe(value: Double) {
        val i = bounds.indexOfFirst { value <= it }
        counts[if (i < 0) bounds.size else i]++
    }

    fun total(): Long = counts.sum()

    /** ✅ 合并：这就是 Prometheus 的 `sum by (le)` 在做的事 */
    fun merge(other: BucketHistogram): BucketHistogram {
        require(bounds.contentEquals(other.bounds)) { "桶边界必须一致才能合并" }
        val merged = BucketHistogram(bounds)
        for (i in counts.indices) merged.counts[i] = counts[i] + other.counts[i]
        return merged
    }

    /**
     * 取分位数。返回"包含该分位数的桶的上边界"。
     * 这是 Prometheus histogram_quantile 的简化版——真实实现会在桶内做线性插值，
     * 所以这里的结果会有轻微偏差，但足够说明问题。
     */
    fun quantile(q: Double): Double {
        val target = q * total()
        var cumulative = 0L
        for (i in counts.indices) {
            cumulative += counts[i]
            if (cumulative >= target) {
                return if (i == 0) bounds[0] else bounds[i - 1]
            }
        }
        return bounds.last()
    }

    fun average(): Double {
        // 注意：直方图本身算不出精确平均值（丢失了桶内分布），这里用桶上边界近似
        var sum = 0.0
        var n = 0L
        for (i in counts.indices) {
            val representative = if (i == 0) bounds[0] else bounds[i - 1]
            sum += representative * counts[i]
            n += counts[i]
        }
        return if (n == 0L) 0.0 else sum / n
    }
}

/** 构造两个"实例"的直方图：A 健康，B 有 1% 的慢请求 */
fun buildTwoInstances(bounds: DoubleArray, samplesPerInstance: Int = 100_000): Pair<BucketHistogram, BucketHistogram> {
    val a = BucketHistogram(bounds)
    val b = BucketHistogram(bounds)

    var seed = 12345L
    fun nextDouble(): Double {
        // 简单的确定性伪随机，便于复现
        seed = seed * 6364136223846793005L + 1442695040888963407L
        return ((seed ushr 11).toDouble() / (1L shl 53).toDouble())
    }

    repeat(samplesPerInstance) {
        // 实例 A：99% 在 4~7ms，1% 在 15~25ms
        a.observe(if (nextDouble() < 0.01) 15 + nextDouble() * 10 else 4 + nextDouble() * 3)
        // 实例 B：99% 在 4~7ms，1% 在 1800~2200ms
        b.observe(if (nextDouble() < 0.01) 1800 + nextDouble() * 400 else 4 + nextDouble() * 3)
    }
    return a to b
}

fun main() {
    val bounds = doubleArrayOf(5.0, 10.0, 20.0, 50.0, 100.0, 200.0, 500.0, 1000.0, 2500.0)
    val (a, b) = buildTwoInstances(bounds)

    val p99a = a.quantile(0.99)
    val p99b = b.quantile(0.99)
    val p99merged = a.merge(b).quantile(0.99)

    println("=== 实验：两个实例的 P99 ===")
    println("A 实例 P99          : %8.1f ms".format(p99a))
    println("B 实例 P99          : %8.1f ms".format(p99b))
    println()
    println("❌ 两个 P99 求平均   : %8.1f ms   ← 不代表任何真实用户".format((p99a + p99b) / 2))
    println("✅ 合并直方图后计算  : %8.1f ms   ← 这才是真实用户看到的分位数".format(p99merged))
    println()
    println("误差                : %.1f 倍".format(((p99a + p99b) / 2) / p99merged))
    println("说明：B 的慢请求只占总样本的 0.5%%，还没到 P99 的位置，")
    println("      所以真实的 P99 依然落在快请求区间。")
    println()

    // ── 反过来：慢请求占比变大时，平均反而会低估 ──────────────
    println("=== 反向验证：把 B 的慢请求比例提高到 5% ===")
    val bounds2 = bounds
    val c = BucketHistogram(bounds2)
    val d = BucketHistogram(bounds2)
    var seed = 999L
    fun nextDouble(): Double {
        seed = seed * 6364136223846793005L + 1442695040888963407L
        return ((seed ushr 11).toDouble() / (1L shl 53).toDouble())
    }
    repeat(100_000) {
        c.observe(if (nextDouble() < 0.01) 15 + nextDouble() * 10 else 4 + nextDouble() * 3)
        d.observe(if (nextDouble() < 0.05) 1800 + nextDouble() * 400 else 4 + nextDouble() * 3)
    }
    val p99c = c.quantile(0.99)
    val p99d = d.quantile(0.99)
    val p99merged2 = c.merge(d).quantile(0.99)
    println("C 实例 P99          : %8.1f ms".format(p99c))
    println("D 实例 P99          : %8.1f ms".format(p99d))
    println("❌ 两个 P99 求平均   : %8.1f ms".format((p99c + p99d) / 2))
    println("✅ 合并直方图后计算  : %8.1f ms".format(p99merged2))
    println()
    println("这次「求平均」是【低估】了。同一个错误做法，")
    println("在不同的流量分布下会朝相反方向错 —— 这就是它最危险的地方。")
}

二、预期输出

=== 实验：两个实例的 P99 ===
A 实例 P99          :     20.0 ms
B 实例 P99          :   2500.0 ms

❌ 两个 P99 求平均   :   1260.0 ms   ← 不代表任何真实用户
✅ 合并直方图后计算  :     20.0 ms   ← 这才是真实用户看到的分位数

误差                : 63.0 倍

=== 反向验证：把 B 的慢请求比例提高到 5% ===
C 实例 P99          :     20.0 ms
D 实例 P99          :   2500.0 ms
❌ 两个 P99 求平均   :   1260.0 ms
✅ 合并直方图后计算  :   2500.0 ms

这次「求平均」是【低估】了。

请注意两次实验的对比：同样的错误做法，第一次高估 63 倍，第二次低估 2 倍。

配套代码：组件基准（Testcontainers + 采样循环）

Mon, 01 Jan 0001 00:00:00 +0000

3.2 配套代码：组件基准（Testcontainers + 采样循环）

对应小节：3.2 组件基准这份代码可以直接改造成你自己项目的组件基准。

一、测试容器与数据准备

// src/test/kotlin/bench/ComponentBenchmarkBase.kt
package bench

import com.zaxxer.hikari.HikariConfig
import com.zaxxer.hikari.HikariDataSource
import org.testcontainers.containers.PostgreSQLContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers
import java.sql.Connection
import kotlin.random.Random

@Testcontainers
abstract class ComponentBenchmarkBase {

    companion object {
        /**
         * 关键：容器在整个测试类生命周期内复用。
         * 每次启动容器要几秒到几十秒，会严重污染测量。
         */
        @Container
        @JvmStatic
        val pg: PostgreSQLContainer<*> = PostgreSQLContainer("postgres:16-alpine")
            .withDatabaseName("bench")
            .withUsername("bench")
            .withPassword("bench")
            .withReuse(true)
    }

    protected lateinit var ds: HikariDataSource

    protected fun startPool(poolSize: Int = 10) {
        ds = HikariDataSource(HikariConfig().apply {
            jdbcUrl = pg.jdbcUrl
            username = pg.username
            password = pg.password
            maximumPoolSize = poolSize
        })
    }

    /**
     * 建表 + 灌数据。
     *
     * ⚠️ 三个关键决策：
     *   1. 数据量 10 万行（与线上同数量级，否则执行计划不同）
     *   2. 幂律热点（前 1% 用户占大部分查询）
     *   3. 故意留一个【没有索引】的列，作为阳性对照
     */
    protected fun seedData(rows: Int = 100_000) {
        ds.connection.use { c ->
            c.createStatement().execute("""
                create table if not exists orders (
                    id          bigserial primary key,
                    user_id     bigint not null,
                    status      text   not null,
                    amount      bigint not null,
                    created_at  timestamptz not null default now()
                )
            """.trimIndent())

            // 用幂律分布生成 user_id：少数用户占大部分订单
            val rnd = Random(42)
            c.prepareStatement("insert into orders(user_id, status, amount) values (?, ?, ?)").use { ps ->
                for (i in 1..rows) {
                    // 幂律：u^3 让值集中在小区间（热点用户）
                    val u = rnd.nextDouble()
                    val userId = (1 + (1_000 * Math.pow(u, 3.0))).toLong()
                    ps.setLong(1, userId)
                    ps.setString(2, if (i % 10 == 0) "REFUNDED" else "PAID")
                    ps.setLong(3, rnd.nextLong(100, 100_00))
                    ps.addBatch()
                    if (i % 5_000 == 0) ps.executeBatch()
                }
                ps.executeBatch()
            }

            // ✅ 建索引：user_id（读路径的主索引）
            c.createStatement().execute("create index if not exists idx_orders_user_id on orders(user_id)")
            // ❌ 故意不建 status 的索引 —— 作为"缺索引"的阳性对照

            c.createStatement().execute("analyze orders")
        }
    }

    protected fun <T> withConn(block: (Connection) -> T): T = ds.connection.use(block)
}

二、采样循环与百分位统计

// src/test/kotlin/bench/Sampling.kt
package bench

/**
 * 组件基准的采样工具。
 *
 * 为什么不用 JMH：
 *   - 数据库查询有副作用（改变缓存、锁、统计信息），JMH 的"重复执行同一状态"不成立
 *   - 数据库延迟是重尾的，需要看分布而不是均值
 *   - 需要统计"查询次数"来发现 N+1
 */
class Sampler(
    private val warmup: Int = 5_000,
    private val rounds: Int = 30_000,
) {
    private var queryCount = 0L

    fun <T> run(label: String, body: (Int) -> T): LongArray {
        queryCount = 0

        // ① 预热：让连接池填满、PG 缓存热起来、JIT 完成编译
        repeat(warmup) { body(it) }

        // ② 采样：每次单独计时
        val samples = LongArray(rounds)
        for (i in 0 until rounds) {
            val t0 = System.nanoTime()
            body(i)
            samples[i] = System.nanoTime() - t0
        }

        samples.sort()
        println("%-38s P50 %8.1f us   P95 %8.1f us   P99 %8.1f us   查询数 %d".format(
            label,
            pct(samples, 0.50) / 1000.0,
            pct(samples, 0.95) / 1000.0,
            pct(samples, 0.99) / 1000.0,
            queryCount,
        ))
        return samples
    }

    /** 让被测代码能报告"这一轮执行了几次查询"——用于发现 N+1 */
    fun countQuery() { queryCount++ }

    companion object {
        fun pct(sorted: LongArray, q: Double): Double =
            sorted[((sorted.size - 1) * q).toInt().coerceIn(0, sorted.size - 1)].toDouble()

        fun report(title: String, sorted: LongArray, queryCount: Long = -1) {
            println("$title: P50=%.1f P95=%.1f P99=%.1f us%s".format(
                pct(sorted, 0.50) / 1000, pct(sorted, 0.95) / 1000, pct(sorted, 0.99) / 1000,
                if (queryCount >= 0) "  查询数=$queryCount" else ""))
        }
    }
}

三、四件事分开测

// src/test/kotlin/bench/OrderRepositoryBenchmark.kt
package bench

import org.junit.jupiter.api.BeforeAll
import org.junit.jupiter.api.Test
import kotlin.random.Random

class OrderRepositoryBenchmark : ComponentBenchmarkBase() {

    @BeforeAll
    fun setUp() {
        startPool(poolSize = 10)
        seedData(rows = 100_000)
    }

    private val sampler = Sampler(warmup = 5_000, rounds = 30_000)

    // ── ① 主键查询（走主键索引） ──────────────────────────────
    @Test
    fun `1 - findById`() {
        sampler.run("① findById（主键）") { i ->
            withConn { c ->
                c.prepareStatement("select id, user_id, amount from orders where id = ?").use { ps ->
                    ps.setLong(1, 1L + Random(i).nextInt(100_000))
                    ps.executeQuery().use { rs -> while (rs.next()) rs.getLong(3) }
                }
            }
            sampler.countQuery()
        }
    }

    // ── ② 二级索引查询（走 user_id 索引 + 回表） ──────────────
    @Test
    fun `2 - findByUserId`() {
        sampler.run("② findByUserId（二级索引）") { i ->
            withConn { c ->
                c.prepareStatement(
                    "select id, amount from orders where user_id = ? order by created_at desc limit 20"
                ).use { ps ->
                    ps.setLong(1, 1L + Random(i).nextInt(1_000))
                    ps.executeQuery().use { rs -> while (rs.next()) rs.getLong(2) }
                }
            }
            sampler.countQuery()
        }
    }

    // ── ③ 无索引列（全表扫描）—— 阳性对照 ────────────────────
    @Test
    fun `3 - findByStatus（无索引，全表扫描）`() {
        sampler.run("③ findByStatus（⚠️ 无索引）") { i ->
            withConn { c ->
                c.prepareStatement(
                    "select id, amount from orders where status = ? limit 20"
                ).use { ps ->
                    ps.setString(1, if (i % 2 == 0) "PAID" else "REFUNDED")
                    ps.executeQuery().use { rs -> while (rs.next()) rs.getLong(2) }
                }
            }
            sampler.countQuery()
        }
    }

    // ── ④ 批量查询 vs 循环单查（量化 N+1 的代价） ─────────────
    @Test
    fun `4a - N+1 循环单查（100 次）`() {
        sampler.run("④a 循环单查 ×100（N+1）") { _ ->
            val ids = (1L..100L).map { (it * 7919) % 100_000 + 1 }
            ids.forEach { id ->
                withConn { c ->
                    c.prepareStatement("select amount from orders where id = ?").use { ps ->
                        ps.setLong(1, id)
                        ps.executeQuery().use { rs -> while (rs.next()) rs.getLong(1) }
                    }
                }
                sampler.countQuery()
            }
        }
    }

    @Test
    fun `4b - 批量查询（1 次）`() {
        sampler.run("④b 批量查询（= any）") { _ ->
            val ids = (1L..100L).map { (it * 7919) % 100_000 + 1 }
            withConn { c ->
                c.prepareStatement("select id, amount from orders where id = any(?)").use { ps ->
                    ps.setArray(1, c.createArrayOf("bigint", ids.toTypedArray()))
                    ps.executeQuery().use { rs -> while (rs.next()) rs.getLong(2) }
                }
            }
            sampler.countQuery()
        }
    }
}

四、预期输出与判读

① findById（主键）                  P50    380.2 us   P95    890.1 us   P99   2104.3 us   查询数 30000
② findByUserId（二级索引）           P50   1180.4 us   P95   3402.7 us   P99   8706.2 us   查询数 30000
③ findByStatus（⚠️ 无索引）          P50  18234.6 us   P95  42108.9 us   P99  96412.5 us   查询数 30000
④a 循环单查 ×100（N+1）              P50 182340.0 us   P95 402118.0 us   P99 512004.0 us   查询数 3000000
④b 批量查询（= any）                 P50   1804.3 us   P95   3102.8 us   P99   6208.1 us   查询数 30000

四个结论直接从这张表读出来：

配套代码：调用点类型数量与去优化

Mon, 01 Jan 0001 00:00:00 +0000

2.2 配套代码：调用点类型数量与去优化

对应小节：2.2 JIT 的三大优化与去优化要验证的结论：同一个调用点混入的类型越多，性能越差；而且退化不是按比例发生的。

一、实验：单态 / 双态 / 巨态

// src/main/kotlin/lesson02/CallSitePolymorphism.kt
package lesson02

import kotlin.random.Random

/** 一个有多个实现的接口 */
interface Handler {
    fun handle(v: Int): Int
}

class HandlerA : Handler { override fun handle(v: Int) = v + 1 }
class HandlerB : Handler { override fun handle(v: Int) = v * 2 }
class HandlerC : Handler { override fun handle(v: Int) = v - 3 }
class HandlerD : Handler { override fun handle(v: Int) = v xor 7 }
class HandlerE : Handler { override fun handle(v: Int) = v shr 1 }

private var sink = 0L

/**
 * 关键：这里只有一个调用点 `h.handle(v)`。
 * 传入的 Handler 实现类数量，决定了这个调用点的"态"。
 */
fun runLoop(handlers: Array<Handler>, iterations: Int): Long {
    var acc = 0L
    var state = 12345
    repeat(iterations) {
        state = state * 1103515245 + 12345            // 简单的伪随机，避免被优化
        val h = handlers[(state ushr 16) and (handlers.size - 1)]
        acc += h.handle(it)                            // ← 唯一的调用点
    }
    sink += acc
    return acc
}

fun measure(handlers: Array<Handler>, warmup: Int = 2_000_000, measure: Int = 5_000_000): Double {
    repeat(warmup) { runLoop(handlers, 100) }
    val t0 = System.nanoTime()
    runLoop(handlers, measure)
    val t1 = System.nanoTime()
    return (t1 - t0).toDouble() / measure
}

fun main() {
    // 注意：handlers.size 必须是 2 的幂，上面的位运算取模才正确
    val cases = listOf(
        "单态（1 种实现）" to arrayOf<Handler>(HandlerA()),
        "双态（2 种实现）" to arrayOf<Handler>(HandlerA(), HandlerB()),
        "四态（4 种实现）" to arrayOf<Handler>(HandlerA(), HandlerB(), HandlerC(), HandlerD()),
        "巨态（8 种实现）" to arrayOf<Handler>(
            HandlerA(), HandlerB(), HandlerC(), HandlerD(),
            HandlerE(), HandlerA(), HandlerB(), HandlerC()
        ),
    )

    println("调用点的类型数量 → 单次耗时")
    println("-".repeat(46))
    val baseline = measure(cases[0].second)
    for ((label, handlers) in cases) {
        val ns = measure(handlers)
        println("%-18s %8.2f ns/op   (%.2fx)".format(label, ns, ns / baseline))
    }
    println()
    println("sink = $sink")
    println()
    println("预期：类型越多越慢。注意『双态』相对『单态』的退化幅度——")
    println("      即使只有 2 种类型，JIT 也无法再做单态内联优化。")
}

二、预期输出形态

调用点的类型数量 → 单次耗时
----------------------------------------------
单态（1 种实现）        4.12 ns/op   (1.00x)
双态（2 种实现）        7.83 ns/op   (1.90x)
四态（4 种实现）       12.41 ns/op   (3.01x)
巨态（8 种实现）       18.06 ns/op   (4.38x)

关键不是具体倍数，而是趋势：即使只有 2 种实现，退化也很明显（接近 2 倍）。这就是「1% 的慢路径拖累 99% 的快路径」的微观机制。

配套代码：async-profiler 命令全集与火焰图解读

Mon, 01 Jan 0001 00:00:00 +0000

4.3 配套代码：async-profiler 命令全集与火焰图解读

对应小节：4.3 async-profiler 这份文件是命令速查 + 判读手册，建议放在手边。

一、安装与权限（最容易卡住的一步）

# 下载（以 3.x 为例）
curl -L -o async-profiler.tar.gz \
  https://github.com/async-profiler/async-profiler/releases/download/v3.0/async-profiler-3.0-linux-x64.tar.gz
tar xzf async-profiler.tar.gz && cd async-profiler-3.0-linux-x64

# 验证
./asprof --version

# Linux 权限：perf_event_paranoid 必须 <= 1
cat /proc/sys/kernel/perf_event_paranoid
sudo sysctl -w kernel.perf_event_paranoid=1

# 容器内：需要额外 capability 或放宽 seccomp
# docker run --cap-add SYS_ADMIN ...
# 或者（Docker Compose）
#   cap_add: [SYS_ADMIN]
#   security_opt: [seccomp:unconfined]

如果拿不到 perf 权限：async-profiler 会退化到 itimer 模式（精度较低但可用）：

asprof -e itimer -d 60 -f out.html <pid>

「火焰图很空」的头号原因就是权限问题——先检查这一项，再怀疑别的。

配套代码：三个测量点的埋点与延迟分解

Mon, 01 Jan 0001 00:00:00 +0000

1.3 配套代码：三个测量点的埋点与延迟分解

对应小节：1.3 测量点目标：让代码能回答「这个接口的 P99 里，数据库占多少毫秒、排队占多少毫秒、我写的代码占多少毫秒」。

一、依赖级计时器

// src/main/kotlin/metrics/TimedDependency.kt
package metrics

import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Timer
import java.time.Duration

/**
 * 每个依赖一个 Timer。
 * 注意：这里用 builder 而不是 record()，因为需要为每个依赖单独配置桶边界。
 */
class DependencyTimers(registry: MeterRegistry) {

    private fun timer(name: String, description: String): Timer =
        Timer.builder(name)
            .description(description)
            .publishPercentileHistogram(true)
            .serviceLevelObjectives(*sloBuckets.toTypedArray())
            .minimumExpectedValue(Duration.ofMillis(1))
            .maximumExpectedValue(Duration.ofSeconds(5))
            .register(registry)

    val postgres = timer("dep.postgres", "PostgreSQL 调用耗时（含等待连接）")
    val redis = timer("dep.redis", "Redis 调用耗时")
    val downstream = timer("dep.downstream", "下游 HTTP 调用耗时")

    /**
     * 跨越挂起点的计时是合法的：Timer.Sample 只记录起始时刻。
     * 因此协程调度的时间也会被计入 —— 这正是我们想要的（用户看到的就是这段时间）。
     */
    suspend fun <T> timed(timer: Timer, registry: MeterRegistry, block: suspend () -> T): T {
        val sample = Timer.start(registry)
        return try {
            block()
        } finally {
            sample.stop(timer)
        }
    }
}

一个容易忽略的细节：dep.postgres 的计时包含了「等连接池分配连接」的时间。这其实很有用——如果这个 Timer 的 P99 突然飙升，你要进一步区分「等连接」和「查询慢」，方法是同时看 db_pool_pending 指标（饱和度层）。

配套代码：全链路性能门禁

Mon, 01 Jan 0001 00:00:00 +0000

8.3 配套代码：全链路性能门禁

对应小节：8.3 全链路性能门禁一份完整的门禁脚本，含饱和度检查（最容易被忽略但最有价值的一项）。

一、完整的全链路门禁脚本

#!/usr/bin/env bash
# tools/e2e-perf-gate.sh <VERSION_TAG>
#
# 全链路性能门禁：发布候选阶段运行。
#
# 前置条件（缺一不可，否则结果不可信）：
#   ① 专用环境（固定规格、独占、压测客户端独立）
#   ② 固定的数据集（每次重置到同一状态）
#   ③ 固定的 JVM 参数与容器配置
set -euo pipefail

VERSION="${1:?usage: e2e-perf-gate.sh <version_tag>}"
EXP_ID="gate-${VERSION}"
DIR="docs/experiments/${EXP_ID}"
mkdir -p "$DIR/results"

echo "═══════════════════════════════════════════════════════════════"
echo "全链路性能门禁：$VERSION"
echo "═══════════════════════════════════════════════════════════════"
echo

# ═══ 1/7 环境检查（不通过就终止）═══
echo "【1/7】环境检查"
tools/check-environment.sh "$EXP_ID" > /dev/null 2>&1 || true
if grep -q "❌" "$DIR/results/env-check.txt" 2>/dev/null; then
  echo "❌ 环境检查未通过 —— 本次结果不可信，终止"
  grep "❌" "$DIR/results/env-check.txt" | sed 's/^/   /'
  exit 2
fi
tools/collect-env.sh "$EXP_ID" > /dev/null 2>&1 || true
echo "   ✅ 环境检查通过"
echo

# ═══ 2/7 记录代码版本 ═══
echo "【2/7】记录代码版本"
{
  echo "commit=$(git rev-parse HEAD)"
  echo "tag=$VERSION"
  echo "dirty=$(git status --porcelain | wc -l | tr -d ' ')"
} | tee "$DIR/results/code-state.txt"
echo

# ═══ 3/7 重置数据集并重启 ═══
echo "【3/7】重置数据集"
scripts/reset-dataset.sh
scripts/restart-app.sh "$DIR/results/gc.log"
sleep 10
echo "   ✅ 服务已重启"
echo

# ═══ 4/7 预热（不计入统计）═══
echo "【4/7】预热 60 秒"
BASE_URL="$TARGET_URL" k6 run --quiet --vus 20 --duration 60s \
  loadtest/profile-constant.js > /dev/null 2>&1
echo "   ✅ 预热完成"
echo

# ═══ 5/7 测量 3 轮 ═══
echo "【5/7】测量 3 轮（每轮 3 分钟）"
for i in 1 2 3; do
  echo "   ── 第 $i 轮 ──"
  BASE_URL="$TARGET_URL" RATE="${TARGET_QPS:-500}" DURATION=3m \
  k6 run --summary-export="$DIR/results/round-$i.json" \
         loadtest/profile-constant.js > "$DIR/results/round-$i-stdout.txt" 2>&1

  # ⭐ 关键：同时采集饱和度指标（不只是延迟）
  curl -s --max-time 5 "${TARGET_URL%/}/metrics" > "$DIR/results/metrics-$i.txt" 2>/dev/null || true

  python3 - "$DIR/results/round-$i.json" <<'PY'
import json, sys
m = json.load(open(sys.argv[1]))["metrics"]
d = m["http_req_duration"]
print(f"      QPS={m['http_reqs']['rate']:.1f}  P50={d['med']:.1f}  "
      f"P95={d['p(95)']:.1f}  P99={d['p(99)']:.1f}  错误率={m['http_req_failed']['rate']:.2%}")
PY
done
echo

# ═══ 6/7 检查（四项）═══
echo "【6/7】门禁检查"
python3 tools/e2e_gate_check.py "$DIR/results" perf/e2e-baseline.json
GATE_RESULT=$?
echo

# ═══ 7/7 结论 ═══
echo "【7/7】结论"
if [ $GATE_RESULT -eq 0 ]; then
  echo "✅ 性能门禁通过"
  echo
  echo "后续："
  echo "  ① 把结果归档：cp -r $DIR perf/gate-history/$VERSION"
  echo "  ② 继续发布流程（进入金丝雀阶段）"
  echo "  ③ 发布完成后，把本次结果更新为新的候选基线"
else
  echo "❌ 性能门禁失败"
  echo
  echo "后续："
  echo "  ① 查看 $DIR/results/ 下的详细数据"
  echo "  ② 按第 8.3 节的决策树处理："
  echo "     查环境 → 判幅度 → 定位（第 6 章）→ 决策"
  echo "  ③ ⚠️ 不要直接更新基线"
  exit 1
fi

二、四项检查的实现（含饱和度）

# tools/e2e_gate_check.py <RESULTS_DIR> <BASELINE_JSON>
"""
全链路门禁的检查逻辑。

四项检查：
  ① SLO 达标（延迟 + 错误率）
  ② 拐点未后移（如果有拐点数据）
  ③ 饱和度正常 ⭐（最容易被忽略）
  ④ 资源无异常（内存、连接）
"""
import json
import pathlib
import re
import statistics as st
import sys


def load_rounds(d):
    rounds = []
    for f in sorted(pathlib.Path(d).glob("round-*.json")):
        try:
            m = json.loads(f.read_text())["metrics"]
            dr = m["http_req_duration"]
            rounds.append({
                "qps": m["http_reqs"]["rate"],
                "p50": dr["med"], "p95": dr["p(95)"], "p99": dr["p(99)"],
                "err": m["http_req_failed"]["rate"],
            })
        except Exception:
            pass
    return rounds


def load_metrics_snapshot(d, round_no):
    """从 /metrics 快照里提取饱和度指标"""
    p = pathlib.Path(d) / f"metrics-{round_no}.txt"
    if not p.exists():
        return {}
    text = p.read_text(errors="ignore")
    out = {}
    for key, pattern in [
        ("pool_pending", r"^db_pool_pending\s+([\d.]+)"),
        ("pool_active", r"^db_pool_active\s+([\d.]+)"),
        ("pool_total", r"^db_pool_total\s+([\d.]+)"),
        ("queue_depth", r"^executor_queue_depth\s+([\d.]+)"),
        ("heap_used_mb", r"^jvm_memory_used_bytes\{.*heap.*\}\s+([\d.]+)"),
    ]:
        m = re.search(pattern, text, re.MULTILINE)
        if m:
            v = float(m.group(1))
            out[key] = v / 1048576 if key == "heap_used_mb" else v
    return out


def main(results_dir, baseline_path):
    rounds = load_rounds(results_dir)
    if not rounds:
        print("❌ 没有找到测量数据")
        sys.exit(2)

    baseline = {}
    bp = pathlib.Path(baseline_path)
    if bp.exists():
        baseline = json.loads(bp.read_text())

    problems = []
    warnings = []
    passed = []

    print("═" * 84)
    print("全链路门禁检查（四项）")
    print("═" * 84)
    print()

    # ── ① SLO 达标 ──────────────────────────────────────────
    print("【① SLO 达标】")
    p99 = st.median([r["p99"] for r in rounds])
    err = st.median([r["err"] for r in rounds])
    p99_slo = baseline.get("slo_p99_ms", 200)
    err_slo = baseline.get("slo_error_rate", 0.001)

    print(f"  P99 (中位数): {p99:.1f} ms   （SLO: < {p99_slo} ms）")
    print(f"  错误率       : {err:.2%}   （SLO: < {err_slo:.2%}）")

    if p99 > p99_slo:
        problems.append(f"SLO 违约：P99 {p99:.1f}ms > {p99_slo}ms")
        print("  ❌ SLO 违约")
    elif p99 > p99_slo * 0.9:
        warnings.append(f"P99 接近 SLO（{p99:.1f}/{p99_slo}ms）")
        print("  ⚠️  接近 SLO 上限")
    else:
        passed.append("SLO 达标")
        print("  ✅ 达标")

    if err > err_slo:
        problems.append(f"错误率超标：{err:.2%} > {err_slo:.2%}")
        print("  ❌ 错误率超标")
    print()

    # ── ② 基线对比（延迟与吞吐）──────────────────────────────
    print("【② 与基线对比】")
    if baseline.get("p99"):
        base_p99 = baseline["p99"]
        delta = (p99 - base_p99) / base_p99 * 100
        threshold = baseline.get("p99_threshold_pct", 20)
        print(f"  P99: 基线 {base_p99:.1f}ms → 当前 {p99:.1f}ms （{delta:+.1f}%，阈值 ±{threshold}%）")
        if delta > threshold:
            problems.append(f"P99 退化 {delta:+.1f}%")
            print("  ❌ 退化超阈值")
        else:
            passed.append("P99 无退化")
            print("  ✅")
    else:
        print("  （基线中无 P99 数据，跳过）")
    print()

    # ── ③ 饱和度 ⭐（最容易被忽略）──────────────────────────
    print("【③ 饱和度检查】⭐ 领先指标")
    pending_vals, queue_vals = [], []
    for i in range(1, len(rounds) + 1):
        snap = load_metrics_snapshot(results_dir, i)
        if "pool_pending" in snap:
            pending_vals.append(snap["pool_pending"])
        if "queue_depth" in snap:
            queue_vals.append(snap["queue_depth"])

    if pending_vals:
        max_pending = max(pending_vals)
        print(f"  连接池 pending 最大值: {max_pending:.0f}")
        if max_pending > 0:
            problems.append(f"连接池出现排队（pending 最大 {max_pending:.0f}）")
            print("  ❌ 存在排队 —— 系统余量已被耗尽")
            print("     即使延迟达标，也应拒绝通过（第 8.3 节）")
        else:
            passed.append("连接池无排队")
            print("  ✅ 无排队")
    else:
        print("  （未采集到 pending 指标 —— 建议在 metrics 快照里加上）")

    if queue_vals:
        max_queue = max(queue_vals)
        print(f"  线程池队列最大深度: {max_queue:.0f}")
        if max_queue > 100:
            problems.append(f"线程池队列积压（{max_queue:.0f}）")
            print("  ❌ 队列积压")
        else:
            passed.append("队列无积压")
            print("  ✅ 队列正常")
    print()

    # ── ④ 资源趋势（泄漏检测）──────────────────────────────
    print("【④ 资源趋势】")
    heaps = []
    for i in range(1, len(rounds) + 1):
        snap = load_metrics_snapshot(results_dir, i)
        if "heap_used_mb" in snap:
            heaps.append(snap["heap_used_mb"])
    if len(heaps) >= 3:
        print(f"  堆使用: {[f'{h:.0f}' for h in heaps]} MB")
        if heaps[-1] > heaps[0] * 1.5:
            warnings.append("堆使用有上升趋势（建议做浸泡测试）")
            print("  ⚠️  有上升趋势 —— 建议单独做浸泡测试确认（第 3 章 3.5）")
        else:
            passed.append("资源稳定")
            print("  ✅ 稳定")
    else:
        print("  （轮数不足或未采集，跳过）")
    print()

    # ── 汇总 ────────────────────────────────────────────────
    print("═" * 84)
    if problems:
        print(f"❌ 门禁失败（{len(problems)} 项问题）")
        for p in problems:
            print(f"   - {p}")
        print()
        print("处理方式：")
        print("  ① 检查环境（env-check.txt 有没有 ❌）")
        print("  ② 判断幅度（是噪声还是真退化）")
        print("  ③ 定位（用第 6 章的延迟分解与火焰图）")
        print("  ④ 不要直接更新基线")
        sys.exit(1)
    elif warnings:
        print(f"⚠️  门禁通过，但有 {len(warnings)} 项警告")
        for w in warnings:
            print(f"   - {w}")
        sys.exit(0)
    else:
        print("✅ 门禁通过（四项检查全部通过）")
        sys.exit(0)


if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else "perf/e2e-baseline.json")

三、基线文件格式

{
  "version": "v2.3.0",
  "date": "2025-01-10",
  "environment": {
    "instance": "4C8G",
    "replicas": 3,
    "jvm_args": "-Xms2g -Xmx2g -XX:+UseG1GC",
    "container_cpu_limit": "4",
    "container_mem_limit": "8Gi"
  },
  "slo_p99_ms": 200,
  "slo_error_rate": 0.001,
  "p99": 95.2,
  "p95": 42.1,
  "p50": 12.3,
  "qps": 500,
  "p99_threshold_pct": 20,
  "saturation": {
    "pool_pending_max": 0,
    "queue_depth_max": 0
  },
  "notes": "拐点约 900 RPS（E02 实验）；数据量 100 万行"
}

注意 saturation 这一栏：把基线时的饱和度也记下来——这样当前值不为 0 时就能立刻发现"余量在减少"。

配套代码：均值如何骗人，尾部如何放大

Mon, 01 Jan 0001 00:00:00 +0000

0.3 配套代码：均值如何骗人，尾部如何放大

对应小节：0.3 延迟是分布，不是数字要验证的三个结论：① 均值掩盖长尾 ② 尾延迟跨服务放大 ③ 百分位不能直接平均

一、实验一：均值与百分位的差距

构造一个真实的「重尾」延迟分布：99% 的请求很快（4–7 ms），1% 的请求很慢（800–1200 ms）。这正是后端常见的样子——大部分请求走缓存，少数请求穿透到数据库或遇到 GC。

// src/main/kotlin/lesson00/LatencyDistribution.kt
package lesson00

import kotlin.random.Random

/** 取分位数：输入必须已排序。q=0.99 表示"99% 的样本比它小" */
fun percentile(sorted: LongArray, q: Double): Long {
    val idx = ((sorted.size - 1) * q).toInt().coerceIn(0, sorted.size - 1)
    return sorted[idx]
}

/**
 * 生成一个重尾分布：
 * 99% 的样本落在 [fastMin, fastMax)，1% 落在 [slowMin, slowMax)
 * 单位：毫秒（这里用整数模拟，便于观察）
 */
fun heavyTailed(n: Int, slowRatio: Double = 0.01, seed: Int = 42): LongArray {
    val rnd = Random(seed)
    return LongArray(n) {
        if (rnd.nextDouble() < slowRatio) rnd.nextLong(800, 1200)
        else rnd.nextLong(4, 7)
    }
}

fun main() {
    val samples = heavyTailed(200_000)
    val sorted = samples.sortedArray()
    val mean = samples.average()

    println("=== 实验一：均值 vs 百分位（20 万个请求）===")
    println("平均值      : %8.2f ms   ← 只有这一个数字时，你会以为服务很健康".format(mean))
    println("P50 (中位数): %8d ms   ← 一半用户的实际体验".format(percentile(sorted, 0.50)))
    println("P90         : %8d ms".format(percentile(sorted, 0.90)))
    println("P95         : %8d ms".format(percentile(sorted, 0.95)))
    println("P99         : %8d ms   ← 每 100 个用户就有 1 个这样".format(percentile(sorted, 0.99)))
    println("P999        : %8d ms".format(percentile(sorted, 0.999)))
    println("最大值      : %8d ms".format(sorted.last()))
    println()
    println("差距：P99 是平均值的 %.0f 倍。".format(percentile(sorted, 0.99) / mean))
    println("在 100 万日请求量下，P99 意味着每天有 %,d 个用户体验到这种延迟。"
        .format((1_000_000 * 0.01).toLong()))
    println()

    // ── 实验二：尾延迟跨服务放大 ────────────────────────────────
    demonstrateTailAmplification()

    // ── 实验三：百分位不能直接平均 ──────────────────────────────
    demonstratePercentileAggregationTrap()
}

二、实验二：尾延迟跨服务放大

正文的结论是：10 个下游各 1% 慢 → 整条链路约 10% 慢。

配套代码：并行度调优与隔板

Mon, 01 Jan 0001 00:00:00 +0000

7.3 配套代码：并行度调优与隔板

对应小节：7.3 并发与并行两件事：① 用实验找到最优并行度；② 用隔板实现资源隔离。

一、并行度调优实验

// src/main/kotlin/experiments/ParallelismTuning.kt
package experiments

import kotlinx.coroutines.*
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit
import kotlin.system.measureNanoTime

private var sink = 0L

/** 模拟一次"要 5ms 的 IO 操作" */
suspend fun simulatedIo(): Int {
    delay(5)
    return 1
}

/** 模拟一次"要 1ms 的 CPU 操作" */
fun simulatedCpu(): Int {
    var s = 0
    repeat(10_000) { s += it }
    return s
}

/**
 * 测量不同并行度下的吞吐与延迟。
 *
 * @param parallelism 并发上限
 * @param totalOps 总操作数
 * @param ioBound true = IO 密集（delay），false = CPU 密集
 */
suspend fun measure(parallelism: Int, totalOps: Int, ioBound: Boolean): Triple<Double, Double, Double> {
    val limiter = Semaphore(parallelism)
    val latencies = java.util.concurrent.ConcurrentLinkedQueue<Long>()

    val elapsedNs = measureNanoTime {
        coroutineScope {
            val dispatcher = if (ioBound) Dispatchers.IO else Dispatchers.Default
            (0 until totalOps).map { i ->
                async(dispatcher) {
                    limiter.withPermit {
                        val t0 = System.nanoTime()
                        val r = if (ioBound) simulatedIo() else simulatedCpu()
                        latencies.add(System.nanoTime() - t0)
                        sink += r
                    }
                }
            }.awaitAll()
        }
    }

    val lats = latencies.toLongArray().apply { sort() }
    val qps = totalOps / (elapsedNs / 1e9)
    val p50 = lats[lats.size / 2] / 1e6
    val p99 = lats[(lats.size * 99) / 100] / 1e6
    return Triple(qps, p50, p99)
}

fun main() = runBlocking {
    val cores = Runtime.getRuntime().availableProcessors()
    println("CPU 核数 = $cores")
    println()

    for ((label, ioBound) in listOf("IO 密集（每次 5ms）" to true, "CPU 密集（每次 ~1ms）" to false)) {
        println("═══ $label ═══")
        println()
        val header = "%-8s%12s%12s%12s   %s".format("并行度", "QPS", "P50(ms)", "P99(ms)", "判读")
        println(header)
        println("-".repeat(64))

        var bestQps = 0.0
        for (p in listOf(1, 2, 4, 8, 16, 32, 64)) {
            // 跳过对 CPU 密集无意义的过大并行度
            if (!ioBound && p > cores * 4) continue

            val (qps, p50, p99) = measure(p, totalOps = if (ioBound) 2000 else 5000, ioBound = ioBound)

            val verdict = when {
                p == 1 -> "基线"
                qps > bestQps * 1.1 -> "✅ 仍在提升"
                qps > bestQps * 0.95 -> "⚠️  接近拐点"
                else -> "❌ 已过拐点（QPS 下降）"
            }
            if (qps > bestQps) bestQps = qps

            println("%-8d%12.0f%12.2f%12.2f   %s".format(p, qps, p50, p99, verdict))
        }
        println()
        if (ioBound) {
            println("IO 密集的判读：")
            println("  → QPS 随并行度上升，直到下游/调度器成为瓶颈")
            println("  → 注意 P99：并行度提高后 P99 通常上升（排队）")
            println("  → 选在「QPS 不再显著提升」之前，且 P99 可接受的位置")
        } else {
            println("CPU 密集的判读：")
            println("  → 最优值 ≈ CPU 核数（%d）；超过后 QPS 下降".format(cores))
            println("  → 因为上下文切换成本超过并行收益")
        }
        println()
    }

    println("sink = $sink")
    println()
    println("⚠️  这是开发机上的简化实验，绝对值不可信；看【趋势与拐点位置】。")
}

预期输出形态：

配套代码：微基准四大陷阱的现场复现

Mon, 01 Jan 0001 00:00:00 +0000

2.3 配套代码：微基准四大陷阱的现场复现

对应小节：2.3 微基准四大陷阱每个陷阱都写「坏版本」和「好版本」，并排跑，让差异自己说话。

一、完整实验代码

// src/main/kotlin/lesson02/MicrobenchmarkTraps.kt
package lesson02

import kotlin.random.Random

// ── 被测函数 ──────────────────────────────────────────────────
fun sumArray(data: IntArray): Long {
    var s = 0L
    for (v in data) s += v
    return s
}

/** 含分支的函数：用来演示分支预测 */
fun countPositive(data: IntArray): Int {
    var c = 0
    for (v in data) if (v > 0) c++
    return c
}

data class OrderDto(val id: Long, val name: String, val amount: Long)

fun makeDto(i: Int) = OrderDto(i.toLong(), "order-$i", (i * 31).toLong())

// ── 全局 sink：防止整个实验被优化掉 ────────────────────────────
private var sink = 0L

fun bench(iterations: Int, label: String, body: () -> Long): Double {
    // 粗略预热（真实基准要用 JMH）
    repeat(iterations / 4) { sink += body() }
    val t0 = System.nanoTime()
    repeat(iterations) { sink += body() }
    val t1 = System.nanoTime()
    val ns = (t1 - t0).toDouble() / iterations
    println("%-46s %12.3f ns/op".format(label, ns))
    return ns
}

fun main() {
    val rnd = Random(42)
    val randomData = IntArray(4096) { rnd.nextInt() }
    val constLikeData = IntArray(4096) { it }                 // 规律数据
    val mixedSignData = IntArray(4096) { rnd.nextInt(-100, 100) }
    val allPositive = IntArray(4096) { rnd.nextInt(1, 100) }

    println("═".repeat(76))
    println("陷阱一：死代码消除（DCE）")
    println("═".repeat(76))
    bench(200_000, "❌ 坏版本：不消费返回值") {
        sumArray(randomData)                    // 结果丢弃 → 计算可能被整体删除
        0L
    }
    bench(200_000, "✅ 好版本：消费返回值") {
        sumArray(randomData)
    }
    println("→ 坏版本的数字可能低到物理不可能。判断方法：把数组大小改成 10 倍，看耗时是否变化。\n")

    println("═".repeat(76))
    println("陷阱二：常量折叠")
    println("═".repeat(76))
    bench(200_000, "❌ 坏版本：规律数据（{ it }）") {
        sumArray(constLikeData)
    }
    bench(200_000, "✅ 好版本：运行时随机数据") {
        sumArray(randomData)
    }
    println("→ 规律数据可能被识别出模式（甚至直接套公式），数字与真实负载无关。\n")

    println("═".repeat(76))
    println("陷阱三：分支预测被喂得太好")
    println("═".repeat(76))
    bench(200_000, "❌ 坏版本：全部正数（分支永远成立）") {
        countPositive(allPositive).toLong()
    }
    bench(200_000, "✅ 好版本：正负混合（分支随机失败）") {
        countPositive(mixedSignData).toLong()
    }
    println("→ 全正数时分支预测接近 100% 命中，比真实混合流量快得多。\n")

    println("═".repeat(76))
    println("陷阱四：未消费结果（逃逸分析消除分配）")
    println("═".repeat(76))
    // 用分配速率来观察，而不是耗时
    val before1 = allocatedBytes()
    repeat(1_000_000) { makeDto(it) }                          // 对象不逃逸
    val after1 = allocatedBytes()
    println("❌ 坏版本（对象不逃逸）：分配 %,d 字节".format(after1 - before1))

    val list = ArrayList<OrderDto>(1_000_000)
    val before2 = allocatedBytes()
    repeat(1_000_000) { list.add(makeDto(it)) }                // 对象逃逸到集合
    val after2 = allocatedBytes()
    println("✅ 好版本（对象逃逸到集合）：分配 %,d 字节".format(after2 - before2))
    sink += list.size
    println("→ 不逃逸时逃逸分析可能连对象带分配一起消除，你测不到真实的 GC 压力。")

    println()
    println("sink = $sink")
}

/** 用 ThreadMXBean 读取当前线程累计分配的字节数（近似值，仅用于对比） */
fun allocatedBytes(): Long =
    (java.lang.management.ManagementFactory.getThreadMXBean() as? com.sun.management.ThreadMXBean)
        ?.getThreadAllocatedBytes(Thread.currentThread().threadId())
        ?: -1L

关于 allocatedBytes()：它用了 com.sun.management.ThreadMXBean 这个 JDK 内部 API（只用于教学演示）。如果编译报错，可以换成用 -prof gc（JMH）或 async-profiler 的 alloc 事件来观察。

配套代码：搭服务与造数据

Mon, 01 Jan 0001 00:00:00 +0000

9.3 配套代码：搭服务与造数据

对应小节：9.3 步骤二：搭服务与数据

一、docker-compose

# perf/docker-compose.yaml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: shortlink
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    ports: ["5432:5432"]
    volumes:
      - ./sql:/docker-entrypoint-initdb.d:ro
      - pgdata:/var/lib/postgresql/data
    command:
      - postgres
      # ── 关键：明确资源上限，否则本机 PG 会吃掉所有内存，结果无法解释 ──
      - -c
      - shared_buffers=2GB
      - -c
      - effective_cache_size=6GB
      - -c
      - work_mem=64MB
      - -c
      - max_connections=200
      - -c
      - log_min_duration_statement=100     # 慢查询日志（>100ms 都记）
      - -c
      - track_io_timing=on                 # EXPLAIN BUFFERS 才有 I/O 时间
    deploy:
      resources:
        limits: { cpus: "4", memory: "8g" }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d shortlink"]
      interval: 5s
      retries: 10

  redis:
    image: redis:7
    ports: ["6379:6379"]
    command: ["redis-server", "--maxmemory", "1gb", "--maxmemory-policy", "allkeys-lru"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s

volumes:
  pgdata:

注意 deploy.resources.limits：

配套代码：火焰图的分析辅助

Mon, 01 Jan 0001 00:00:00 +0000

6.3 配套代码：火焰图的分析辅助

对应小节：6.3 火焰图读法三件事：① 从 flat 输出快速找热点；② diff 两次火焰图；③ 自动识别形状特征。

一、从 flat 输出找热点（比读图更快）

#!/usr/bin/env bash
# tools/top-hotspots.sh <PID> [EVENT] [DURATION]
#
# 用 async-profiler 的 flat 输出，直接列出"自身耗时最多"的函数。
# 比在火焰图里肉眼找快得多。
set -uo pipefail

PID="${1:?usage: top-hotspots.sh <pid> [event] [duration]}"
EVENT="${2:-cpu}"
DURATION="${3:-30}"

TMP=$(mktemp)
asprof -d "$DURATION" -e "$EVENT" -o flat -f "$TMP" "$PID" > /dev/null 2>&1

echo "═══ $EVENT 事件的热点排名（采样 ${DURATION}s）═══"
echo

# flat 输出格式：通常每行是 "百分比% 栈帧"
head -25 "$TMP" | while IFS= read -r line; do
  echo "$line"
done

echo
echo "─── 按包/模块聚合（Top 10）───"
awk '{
  # 取倒数第一列作为函数名（格式因版本而异，这是容错处理）
  n = split($0, a, " ");
  frame = a[n];
  # 提取包名（前两段）
  split(frame, parts, ".");
  pkg = parts[1];
  if (length(parts) > 1) pkg = pkg "." parts[2];
  # 提取百分比（第一个字段）
  pct = a[1];
  gsub(/[^0-9.]/, "", pct);
  if (pct != "") sum[pkg] += pct;
} END {
  for (p in sum) printf "%8.2f%%  %s\n", sum[p], p;
}' "$TMP" | sort -rn | head -10

rm -f "$TMP"

二、diff 两次火焰图（证明优化有效）

#!/usr/bin/env bash
# tools/flamegraph-diff.sh <PID> <EVENT> <BEFORE_LABEL> <AFTER_LABEL>
#
# 分别在优化前/后采集，生成差量图。
# 差量图能直接显示"哪条链路变短了"。
set -uo pipefail

PID="${1:?usage: flamegraph-diff.sh <pid> <event> <before_label> <after_label>}"
EVENT="${2:-wall}"
BEFORE="${3:?}"
AFTER="${4:?}"
OUT_DIR="${OUT_DIR:-docs/experiments/flamegraph-diff}"
mkdir -p "$OUT_DIR"

echo "采集 $EVENT 火焰图：$BEFORE"
asprof -d 60 -e "$EVENT" -o collapsed -f "$OUT_DIR/$BEFORE.txt" "$PID"

echo
echo "⏸  现在请应用你的优化（或切到优化后的版本），然后按回车继续..."
read -r _

echo "采集 $EVENT 火焰图：$AFTER"
asprof -d 60 -e "$EVENT" -o collapsed -f "$OUT_DIR/$AFTER.txt" "$PID"

echo
echo "生成差量图..."
if [ ! -d FlameGraph ]; then
  echo "⚠️  未找到 FlameGraph 工具集，正在克隆..."
  git clone --depth 1 https://github.com/brendangregg/FlameGraph 2>/dev/null || {
    echo "❌ 克隆失败，请手动克隆 FlameGraph 后重试"
    exit 1
  }
fi

FlameGraph/difffolded.pl "$OUT_DIR/$BEFORE.txt" "$OUT_DIR/$AFTER.txt" \
  | FlameGraph/flamegraph.pl > "$OUT_DIR/diff-${BEFORE}-vs-${AFTER}.svg"

echo "✅ 差量图 → $OUT_DIR/diff-${BEFORE}-vs-${AFTER}.svg"
echo
echo "读法："
echo "  颜色区分「变多」和「变少」的栈 —— 红色变少的部分就是你优化掉的开销"
echo "  （具体配色取决于 flamegraph.pl 的参数，可用 --colors 调整）"

一个更简单的 diff 方法：比较 flat 输出

# tools/compare-hotspots.py <before-flat.txt> <after-flat.txt>
"""
比较两次 flat 输出的热点变化。
比 SVG 差量图更容易量化（能算出"减少了多少个百分点"）。
"""
import re
import sys


def parse_flat(path):
    """解析 flat 输出：返回 {函数名: 百分比}"""
    result = {}
    with open(path, errors="ignore") as f:
        for line in f:
            # 格式容错：找行首/行中的百分比数字
            m = re.match(r"\s*([\d.]+)\s*%?\s+(.*)", line)
            if m:
                try:
                    pct = float(m.group(1))
                    frame = m.group(2).strip()
                    # 取最后一段作为函数名
                    name = frame.split()[-1] if " " in frame else frame
                    result[name] = result.get(name, 0) + pct
                except ValueError:
                    continue
    return result


def main(before_path, after_path):
    before = parse_flat(before_path)
    after = parse_flat(after_path)

    all_keys = set(before) | set(after)

    print("═" * 92)
    print("热点变化对比（按变化幅度排序）")
    print("═" * 92)
    print()
    print(f"{'函数':<52}{'优化前':>10}{'优化后':>10}{'变化':>12}")
    print("-" * 92)

    rows = []
    for k in all_keys:
        b, a = before.get(k, 0), after.get(k, 0)
        rows.append((a - b, k, b, a))

    # 按"减少最多"排序（负数 = 减少了，好事）
    rows.sort()
    for delta, k, b, a in rows[:15]:
        marker = "✅" if delta < -1 else ("❌" if delta > 1 else "  ")
        print(f"{k[:50]:<52}{b:>9.2f}%{a:>9.2f}%{delta:>+11.2f}%  {marker}")

    print()
    print("─" * 92)
    print("增加最多的（可能是新引入的开销）：")
    for delta, k, b, a in rows[-5:][::-1]:
        if delta > 0.5:
            print(f"  ❌ {k[:60]:<62}{b:>7.2f}% → {a:>7.2f}%  ({delta:+.2f}%)")

    print()
    print("═" * 92)
    print("判读：")
    print("  ✅ 表示该函数的耗占比下降了（优化生效）")
    print("  ❌ 表示上升了（可能是新的瓶颈，或优化引入了副作用）")
    print("═" * 92)


if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("usage: compare-hotspots.py <before-flat.txt> <after-flat.txt>")
        sys.exit(1)
    main(sys.argv[1], sys.argv[2])

三、自动识别形状特征

# tools/analyze-flamegraph.py <collapsed.txt>
"""
从 collapsed 格式分析火焰图的形状特征。

collapsed 格式：每个栈一行
  frame1;frame2;frame3 1234
  （分号分隔栈，最后的数字是采样数）
"""
import sys
from collections import Counter, defaultdict


def load(path):
    stacks = []
    with open(path, errors="ignore") as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            *frames, count = line.rsplit(" ", 1)
            try:
                stacks.append((frames[0].split(";"), int(count)))
            except ValueError:
                continue
    return stacks


def analyze(stacks):
    total = sum(c for _, c in stacks)
    if total == 0:
        print("❌ 没有采样数据")
        return

    print("═" * 76)
    print(f"火焰图形状分析（总采样 {total}，{len(stacks)} 条栈）")
    print("═" * 76)
    print()

    if total < 100:
        print("⚠️  采样数很少 —— 可能是：① 采样时长太短 ② 权限问题 ③ 服务空闲")
        print("    建议延长 -d 时长或确认采样时正在施压\n")

    # ① 自身耗时排名（叶子帧）
    self_time = Counter()
    for frames, count in stacks:
        self_time[frames[-1]] += count

    print("【① 自身耗时 Top 15】（叶子帧 = 真正在消耗时间的函数）")
    for frame, c in self_time.most_common(15):
        pct = c / total * 100
        bar = "█" * int(pct / 2)
        print(f"  {pct:5.1f}%  {bar} {frame[:60]}")
    print()

    # ② 栈深度分布
    depths = [len(frames) for frames, _ in stacks]
    avg_depth = sum(d * c for (f, c), d in zip(stacks, depths)) / total
    print(f"【② 栈深度】平均 {avg_depth:.1f} 层（最深 {max(depths)}）")
    if avg_depth > 60:
        print("  → 栈很深：可能是框架层级多，或递归")
    print()

    # ③ 关键模式检测
    print("【③ 关键模式检测】")
    patterns = {
        "socketRead/socketWrite（等网络）": ("socketRead", "socketWrite", "SocketInputStream"),
        "等数据库（JDBC/PG）": ("jdbc", "postgresql", "QueryExecutor", "PgConnection"),
        "等连接池": ("HikariPool", "getConnection"),
        "锁等待": ("park", "Unsafe.park", "LockSupport", "monitor"),
        "文件 IO（日志）": ("FileOutputStream", "FileDispatcher", "Files.write"),
        "序列化": ("Jackson", "serializ", "writeValue", "Json"),
        "正则": ("Pattern.compile", "Matcher", "Regex"),
        "GC": ("G1", "ZGC", "gc", "Collector"),
        "协程调度": ("kotlinx.coroutines", "DispatchedTask"),
        "字符串处理": ("StringBuilder", "String.format", "String.concat"),
    }
    for label, keywords in patterns.items():
        hits = [(f, c) for f, c in self_time.items() if any(k.lower() in f.lower() for k in keywords)]
        if hits:
            total_pct = sum(c for _, c in hits) / total * 100
            print(f"  {total_pct:5.1f}%  {label}")
    print()

    # ④ 形状判定
    print("【④ 形状判定】")
    top_frame, top_count = self_time.most_common(1)[0]
    top_pct = top_count / total * 100

    if top_pct > 25:
        print(f"  → 存在明显热点：{top_frame[:50]}（{top_pct:.1f}%）")
        print(f"     这是「宽而平」形状，是优化的好目标")
    elif avg_depth > 40:
        print(f"  → 深调用链（平均 {avg_depth:.0f} 层），时间分散")
        print(f"     如果底部是等待类调用（socketRead 等），问题在链的末端")
    else:
        print(f"  → 分布较均匀，无明显单点热点")
        print(f"     可能是多因素共同作用，或瓶颈在进程外（网络/网关/上游）")

    if total < 100:
        print(f"\n  ⚠️  采样太少（{total}），以上判定不可靠")

    print("═" * 76)


if __name__ == "__main__":
    load_path = sys.argv[1] if len(sys.argv) > 1 else "cpu.collapsed"
    analyze(load(load_path))

四、完整工作流

#!/usr/bin/env bash
# tools/flamegraph-workflow.sh <PID> <EXP_ID>
#
# 完整的火焰图分析工作流：采四类 + 分析 + 生成报告
set -uo pipefail

PID="${1:?usage: flamegraph-workflow.sh <pid> <exp_id>}"
EXP_ID="${2:?}"
DIR="docs/experiments/${EXP_ID}/results/flamegraph"
mkdir -p "$DIR"

echo "═══ 1. 采集四类火焰图（各 30 秒）═══"
for E in cpu wall alloc lock; do
  echo "  采集 $E ..."
  asprof -d 30 -e "$E" -f "$DIR/$E.html" "$PID" > /dev/null 2>&1
  asprof -d 30 -e "$E" -o collapsed -f "$DIR/$E.collapsed" "$PID" > /dev/null 2>&1
done

echo
echo "═══ 2. 形状分析 ═══"
for E in cpu wall alloc lock; do
  echo
  echo "───────── $E ─────────"
  python3 tools/analyze-flamegraph.py "$DIR/$E.collapsed" | head -40
done

echo
echo "═══ 3. 快速热点排名 ═══"
for E in cpu wall; do
  echo
  asprof -d 10 -e "$E" -o flat -f "$DIR/$E-flat.txt" "$PID" > /dev/null 2>&1
  echo "── $E Top 10 ──"
  head -12 "$DIR/$E-flat.txt"
done

echo
echo "✅ 完成 → $DIR"
echo
echo "下一步："
echo "  ① 打开 HTML 文件确认形状"
echo "  ② 用 compare-hotspots.py 对比优化前后"
echo "  ③ 填进实验档案的「证据」章节"

五、动手改造

改动	观察什么
对同一个接口采 cpu 和 wall 两份，都跑 `analyze-flamegraph.py`	对比两份的「关键模式检测」结果——这是"两类现象两条路径"的实证
在优化前后各采一份 flat 输出并对比	`compare-hotspots.py` 会显示哪条链路变短了
把 `analyze-flamegraph.py` 的 `patterns` 加上你自己的框架关键词	适配你的技术栈（比如你的 ORM、你的 HTTP 客户端）
用 `-e wall` 采一份，看「等连接池」的占比	印证第 6.5 节的池化瓶颈
故意在采样期间停止施压	`analyze-flamegraph.py` 会提示「采样数很少」——理解采样需要流量

六、这段代码的局限

analyze-flamegraph.py 的关键词匹配是启发式的：可能误报（比如类名里恰好含 “gc”）或漏报（你的框架名字不在列表里）。
collapsed 格式因 async-profiler 版本而异：本脚本用 frame;frame count 的通用格式，如果版本差异大需要调整解析。
flat 输出格式也不统一：不同版本的表头与列顺序可能不同，compare-hotspots.py 用了容错解析但仍可能不准。
形状判定只是辅助：真正的判读还是要看 HTML 图——脚本只能提示"哪里可能值得看"。

配套代码：稳健统计与异常值归因

Mon, 01 Jan 0001 00:00:00 +0000

5.3 配套代码：稳健统计与异常值归因

对应小节：5.3 重复、抖动与异常值核心：报中位数与四分位距，而不是平均值；异常值要归因，不能随手删。

一、稳健统计（纯 Python，无第三方依赖）

# tools/robust_stats.py <results_dir_or_files...>
"""
对多轮实验结果做稳健统计。

为什么不用平均值：
  - 平均值被异常轮拉动
  - 5 轮结果 93/96/94/210/95 的均值是 117.6，而真实"典型值"是 95
  - 中位数 95 + 四分位距能同时表达"典型值"与"波动范围"
"""
import json
import pathlib
import sys


def median(xs):
    s = sorted(xs)
    n = len(s)
    if n == 0:
        return float("nan")
    return s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2


def percentile(xs, q):
    s = sorted(xs)
    if not s:
        return float("nan")
    idx = (len(s) - 1) * q
    lo, hi = int(idx), min(int(idx) + 1, len(s) - 1)
    return s[lo] + (s[hi] - s[lo]) * (idx - lo)


def stdev(xs):
    n = len(xs)
    if n < 2:
        return 0.0
    m = sum(xs) / n
    return (sum((x - m) ** 2 for x in xs) / (n - 1)) ** 0.5


def load_rounds(paths):
    """从 k6 summary json 里加载每轮的关键指标"""
    rounds = []
    for p in paths:
        try:
            m = json.loads(pathlib.Path(p).read_text())["metrics"]
            d = m["http_req_duration"]
            rounds.append({
                "file": pathlib.Path(p).name,
                "qps": m["http_reqs"]["rate"],
                "p50": d.get("med", 0),
                "p95": d.get("p(95)", 0),
                "p99": d.get("p(99)", 0),
                "err": m["http_req_failed"]["rate"],
            })
        except Exception as e:
            print(f"⚠️  跳过 {p}: {e}")
    return rounds


def report(rounds):
    if len(rounds) < 2:
        print("❌ 至少需要 2 轮数据")
        return

    print("═" * 78)
    print(f"稳健统计（{len(rounds)} 轮）")
    print("═" * 78)
    print()

    # 逐轮列出
    print("逐轮结果：")
    print(f"{'轮次':<6}{'QPS':>10}{'P50':>10}{'P95':>10}{'P99':>10}{'错误率':>10}")
    for i, r in enumerate(rounds, 1):
        print(f"{i:<6}{r['qps']:>10.1f}{r['p50']:>10.1f}{r['p95']:>10.1f}{r['p99']:>10.1f}{r['err']:>10.2%}")
    print()

    # 各指标的稳健统计
    print(f"{'指标':<8}{'中位数':>10}{'Q1':>10}{'Q3':>10}{'IQR':>10}{'最小':>10}{'最大':>10}{'CV':>8}")
    print("-" * 78)

    stats = {}
    for key, label in [("qps", "QPS"), ("p50", "P50"), ("p95", "P95"), ("p99", "P99")]:
        vals = [r[key] for r in rounds]
        q1, q3 = percentile(vals, 0.25), percentile(vals, 0.75)
        med = median(vals)
        cv = (stdev(vals) / med * 100) if med else 0.0
        stats[key] = {"median": med, "q1": q1, "q3": q3, "iqr": q3 - q1,
                      "min": min(vals), "max": max(vals), "cv": cv, "values": vals}
        print(f"{label:<8}{med:>10.2f}{q1:>10.2f}{q3:>10.2f}{q3-q1:>10.2f}"
              f"{min(vals):>10.2f}{max(vals):>10.2f}{cv:>7.1f}%")
    print()

    # 异常值检测（Tukey 方法：超出 Q1-1.5*IQR 或 Q3+1.5*IQR）
    print("异常值检测（Tukey 方法，1.5 × IQR）：")
    found_any = False
    for key, label in [("qps", "QPS"), ("p50", "P50"), ("p95", "P95"), ("p99", "P99")]:
        s = stats[key]
        lo, hi = s["q1"] - 1.5 * s["iqr"], s["q3"] + 1.5 * s["iqr"]
        outliers = [(i + 1, v) for i, v in enumerate(s["values"]) if v < lo or v > hi]
        if outliers:
            found_any = True
            for idx, v in outliers:
                direction = "偏高" if v > hi else "偏低"
                print(f"  ⚠️  {label}: 第 {idx} 轮 = {v:.1f}（{direction}，正常范围 {lo:.1f}~{hi:.1f}）")
                print(f"      → 必须解释成因：查环境事件时间线（tools/events-*.log）")
                print(f"      → 不能只因为「不好看」就剔除")
    if not found_any:
        print("  ✅ 未发现异常值")
    print()

    # 与噪声底线的对比提示
    print("═" * 78)
    print("下一步：")
    print("  ① 把上面的 CV 与你的噪声底线对比（第 5.7 节）")
    print("  ② 如果有异常值，去查环境事件时间线，给出成因解释")
    print("  ③ 用 Mann-Whitney U 检验判断与基线的差异是否显著（tools/stats_test.py）")
    print("═" * 78)

    return stats


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("usage: robust_stats.py <round-*.json>... 或 <results_dir>")
        sys.exit(1)

    arg = sys.argv[1]
    if pathlib.Path(arg).is_dir():
        paths = sorted(pathlib.Path(arg).glob("round-*.json")) or sorted(pathlib.Path(arg).glob("*.json"))
    else:
        paths = [pathlib.Path(p) for p in sys.argv[1:]]

    report(load_rounds(paths))

二、异常值归因模板

## 异常值归因记录

### 异常概况
- 轮次：第 4 轮
- 异常指标：P99 = 210 ms（其余 4 轮 93–96 ms）
- 偏离幅度：+120%

### 排查过程
1. **环境事件时间线**（`events-4.log`）
   - T+2:15 检测到 `logrotate` 进程运行
   - T+2:18 磁盘写入速率从 5 MB/s 上升到 80 MB/s
   - T+2:40 logrotate 结束
   - ⚠️ 第 4 轮的压测窗口是 T+2:00 ~ T+3:00 → **时间吻合**

2. **服务端数据**
   - GC 日志：未见异常停顿（与正常轮一致）
   - wall 火焰图：大量栈停在 `FileOutputStream.write`（日志刷盘）
   - 连接池 pending：全程为 0（排除数据库方向）

3. **可复现性验证**
   - 重跑 3 次：异常未再出现
   - 手动触发 `logrotate` 再压测：**异常复现**

### 归因结论
**环境异常**（日志轮转导致的磁盘 IO 争抢）。已通过手动复现验证。

### 处理
- 剔除第 4 轮，用其余 4 轮的中位数（94.5 ms）
- 修正实验流程：实验期间临时调大 logrotate 阈值，或避开轮转时刻
- 记录进假设台账：H7「日志轮转会造成 P99 尖刺」→ **已验证（成立）**

关键：「手动复现」是归因的最强证据——它把「怀疑」变成了「确认」。

配套代码：集成基准与全链路压测

Mon, 01 Jan 0001 00:00:00 +0000

3.3 配套代码：集成基准与全链路压测

对应小节：3.3 集成基准与全链路两层各一份代码：集成基准（单服务完整启动）与全链路 k6（多进程/多机）。

一、集成基准：单服务完整启动

// src/test/kotlin/bench/IntegrationBenchmark.kt
package bench

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import kotlinx.coroutines.*
import kotlin.system.measureNanoTime

/**
 * 集成基准：把服务完整启动起来测。
 *
 * 与组件基准的区别：
 *   ✅ 覆盖 拦截器 → 鉴权 → 参数校验 → 事务 → 多 Repository → 序列化 的完整链路
 *   ✅ 能观察连接池在并发下的行为
 *   ❌ 不含网络与网关（那是全链路的事）
 *   ❌ 闭环模型会低估尾延迟（第 0 章 0.6 节）
 */
object IntegrationBenchmark {

    @JvmStatic
    fun main(args: Array<String>) = runBlocking {
        // ① 完整启动服务（真实端口，不用 testApplication —— 后者会略过一些真实开销）
        val server = embeddedServer(Netty, port = 8080) {
            app.module()                       // 你的 Application.module()
        }.start(wait = false)

        val client = HttpClient(CIO) {
            engine { maxConnectionsCount = 256 }
        }

        try {
            // ② 独立预热阶段：JIT + 连接池 + 缓存（数据不计入统计）
            println("预热中（60 秒，不计入统计）...")
            runLoad(client, concurrency = 8, durationMs = 60_000, record = false)

            // ③ 正式测量
            println("\n正式测量：并发 8，持续 30 秒")
            val latencies = runLoad(client, concurrency = 8, durationMs = 30_000, record = true)

            report(latencies)
        } finally {
            client.close()
            server.stop(1_000, 5_000)
        }
    }

    /**
     * 闭环并发压测（VU 模型）。
     * ⚠️ 已知局限：服务端变慢时会自动降压，尾延迟被低估。
     *    这里用它是因为「与组件基准做相对比较」足够，且实现简单。
     *    要测真实尾延迟请用 k6 的开环模型（见下方）。
     */
    private suspend fun runLoad(
        client: HttpClient,
        concurrency: Int,
        durationMs: Long,
        record: Boolean,
    ): LongArray = coroutineScope {
        val collector = if (record) java.util.concurrent.ConcurrentLinkedQueue<Long>() else null

        val jobs = (0 until concurrency).map {
            launch(Dispatchers.IO) {
                val deadline = System.currentTimeMillis() + durationMs
                while (System.currentTimeMillis() < deadline) {
                    val ns = measureNanoTime {
                        client.get("http://127.0.0.1:8080/orders/1")
                    }
                    collector?.add(ns)
                }
            }
        }
        jobs.joinAll()

        (collector?.toLongArray() ?: LongArray(0)).also { it.sort() }
    }

    private fun report(sorted: LongArray) {
        if (sorted.isEmpty()) return
        fun pct(q: Double) = sorted[((sorted.size - 1) * q).toInt()].toDouble() / 1000
        println("样本数: ${sorted.size}")
        println("P50 = %.1f us".format(pct(0.50)))
        println("P95 = %.1f us".format(pct(0.95)))
        println("P99 = %.1f us".format(pct(0.99)))
        println("max = %.1f us".format(sorted.last() / 1000.0))
        println()
        println("⚠️ 这是闭环模型的结果，只用于「与组件基准比较」，不能用于验收 SLO。")
    }
}

集成基准要观察的三件事：

配套代码：JFR 三种用法与 jcmd 应急手册

Mon, 01 Jan 0001 00:00:00 +0000

4.4 配套代码：JFR 三种用法与 jcmd 应急手册

对应小节：4.4 JFR 与 jcmd 这份文件是可以直接贴进生产配置的 JFR 参数，以及 jcmd 的实战用法。

一、JFR：生产推荐的启动配置

java \
  -XX:StartFlightRecording=name=rolling,settings=profile,maxsize=256m,maxage=1h,dumponexit=true,filename=/var/log/app/recording.jfr \
  -XX:FlightRecorderOptions=stackdepth=128 \
  -jar app.jar

每个参数的理由：

参数	理由
`name=rolling`	给录制起名，便于后续 `JFR.dump name=rolling`
`settings=profile`	记录更多事件（约 1–2% 开销），适合排障；长期生产可用 `default`
`maxsize=256m`	滚动上限，超出丢弃最旧事件（防止磁盘写满）
`maxage=1h`	只保留最近 1 小时（按你的业务周期调整）
`dumponexit=true`	⭐ 进程退出（含崩溃）时自动落盘——排查 OOM 的关键
`stackdepth=128`	栈深度，太浅会丢上下文，太深占空间
`filename=...`	落盘位置；放到独立分区避免写满根分区

验证是否生效：

jcmd <pid> JFR.check
# 应该看到类似：Recording: name=rolling, ... running

二、运行中控制（不用重启）

PID=$(jcmd | grep app.jar | awk '{print $1}')

# ── 出问题时：立刻保存过去 1 小时的事件 ──────────────────
jcmd "$PID" JFR.dump name=rolling filename=/tmp/incident-$(date +%Y%m%d-%H%M%S).jfr

# ── 临时录一段（不依赖启动参数）─────────────────────────
jcmd "$PID" JFR.start name=adhoc settings=profile duration=120s filename=/tmp/adhoc.jfr

# ── 查看正在运行的录制 ──────────────────────────────────
jcmd "$PID" JFR.check

# ── 停止某个录制 ────────────────────────────────────────
jcmd "$PID" JFR.stop name=adhoc

⭐ 最重要的一条：问题发生时立刻 dump。偶发问题的证据只存在于"过去"，等重启后再查就没了。

配套代码：Little's Law 容量计算器

Mon, 01 Jan 0001 00:00:00 +0000

0.4 配套代码：Little’s Law 容量计算器

对应小节：0.4 用 Little’s Law 估算容量要验证的结论：用平均值配置资源是危险的；峰值 QPS × 尾部延迟才是资源需求的上界。

一、公式回顾

L = λ × W
L：在途请求数（个）
λ：到达率（req/s）
W：驻留时间（秒）

二、代码：三个用法 + 一个危险演示

// src/main/kotlin/lesson00/LittlesLaw.kt
package lesson00

import kotlin.math.ceil

/**
 * 计算在途请求数（并发需求）。
 * @param qps 到达率，单位 req/s
 * @param latencyMs 驻留时间，单位毫秒
 */
fun inFlight(qps: Double, latencyMs: Double): Double = qps * (latencyMs / 1000.0)

/**
 * 反推：给定并发上限与单次处理时间，理论最大吞吐。
 * 注意这是"理论值"——它假设资源 100% 忙碌且没有排队。
 */
fun maxThroughput(concurrency: Int, latencyMs: Double): Double =
    concurrency / (latencyMs / 1000.0)

fun main() {
    // ═══════════════════════════════════════════════════════════
    // 用法一：算出需要多少连接/线程/协程
    // ═══════════════════════════════════════════════════════════
    println("=== 用法一：订单查询接口需要多少连接？===")
    val qps = 200.0
    val avgLatency = 30.0
    println("峰值 QPS = %.0f, 平均延迟 = %.1f ms".format(qps, avgLatency))
    println("→ 平均需要 %.1f 个连接".format(inFlight(qps, avgLatency)))
    println("→ 如果连接池设成 100，有 %.0f 个连接平时是闲置的（白占数据库内存）"
        .format(100 - inFlight(qps, avgLatency)))
    println()

    // ═══════════════════════════════════════════════════════════
    // 用法二：从资源上限反推吞吐天花板
    // ═══════════════════════════════════════════════════════════
    println("=== 用法二：数据库最多 50 个连接，单查询 20 ms，理论最大吞吐？===")
    val theoretical = maxThroughput(50, 20.0)
    println("→ 理论上限 %.0f req/s".format(theoretical))
    println("→ 但这是「50 个连接永远 100% 忙碌且零排队」的理想情况")
    println("→ 考虑排队效应（利用率不该超过 70%%），实际可稳定支撑约 %.0f req/s"
        .format(theoretical * 0.7))
    println()

    // ═══════════════════════════════════════════════════════════
    // 用法三：从"活跃请求数"反推实际延迟
    // ═══════════════════════════════════════════════════════════
    println("=== 用法三：观测到 100 个活跃请求，QPS 是 500，平均延迟是多少？===")
    val observedConcurrency = 100.0
    val observedQps = 500.0
    println("→ W = L / λ = %.0f / %.0f = %.3f s = %.0f ms"
        .format(observedConcurrency, observedQps, observedConcurrency / observedQps,
                observedConcurrency / observedQps * 1000))
    println("→ 如果这个数字远大于「服务端处理时间」，多出来的部分就是排队")
    println()

    // ═══════════════════════════════════════════════════════════
    // 危险演示：按平均值配置 vs 按尾部配置
    // ═══════════════════════════════════════════════════════════
    demonstrateTheDanger()

    // ═══════════════════════════════════════════════════════════
    // 敏感性分析：延迟变化对资源需求的影响
    // ═══════════════════════════════════════════════════════════
    sensitivityTable()
}

/**
 * 核心危险：同一份流量，按 P50 配置资源和按 P99 配置资源，需求差 7 倍以上。
 * 而系统恰恰在 P99 那个时刻最需要资源。
 */
fun demonstrateTheDanger() {
    val peakQps = 1000.0
    val p50 = 8.0
    val p99 = 60.0

    println("=== 危险演示：同一个接口，两种算法差多少？===")
    println("峰值 QPS = %.0f".format(peakQps))
    println("按 P50 计算：L = %.0f × %.3f = %5.1f 个".format(peakQps, p50 / 1000, inFlight(peakQps, p50)))
    println("按 P99 计算：L = %.0f × %.3f = %5.1f 个".format(peakQps, p99 / 1000, inFlight(peakQps, p99)))
    println()
    println("两个数字差 %.1f 倍。".format(inFlight(peakQps, p99) / inFlight(peakQps, p50)))
    println()
    println("如果把连接池按 P50 配置（8 个）：")
    println("  → 平时刚好够用（CPU 看着很健康）")
    println("  → 一旦进入那 1% 的慢时刻，60 个请求抢 8 个连接")
    println("  → 排队让延迟进一步上升 → 更多请求堆积 → 雪崩")
    println()
    println("如果把连接池按 P99 配置（%d 个）：".format(ceil(inFlight(peakQps, p99)).toInt()))
    println("  → 最坏时刻够用，但平时有 %.0f 个连接闲置（浪费数据库内存）"
        .format(inFlight(peakQps, p99) - inFlight(peakQps, p50)))
    println("  → 实践做法：取 P95 左右的值 + 排队上限（有界池）+ 快速失败")
    println()
}

/** 敏感性分析：延迟涨一点，资源需求涨多少 */
fun sensitivityTable() {
    val qps = 1000.0
    println("=== 敏感性分析（QPS = %.0f）：延迟 → 需要的并发数 ===".format(qps))
    println("平均延迟(ms) | 需要并发数 | 相对 10ms 的倍数")
    val baseline = inFlight(qps, 10.0)
    for (ms in listOf(10, 15, 20, 30, 50, 100, 200)) {
        val l = inFlight(qps, ms.toDouble())
        println("%11d | %10.1f | %14.1fx".format(ms, l, l / baseline))
    }
    println()
    println("注意：延迟从 10ms 涨到 100ms（10 倍），所需并发也涨 10 倍。")
    println("     但你的连接池是按 10ms 配的 → 延迟一涨，连接池立刻成为瓶颈。")
    println("     这就是「延迟恶化 → 资源耗尽 → 延迟更恶化」的正反馈。")
}

/**
 * 一个真实的容量规划表格生成器：
 * 给定 QPS 与目标延迟，输出每种资源该配多少。
 */
fun capacityPlan(peakQps: Double, p50Ms: Double, p95Ms: Double, p99Ms: Double) {
    println("=== 容量规划建议（峰值 QPS = %.0f）===".format(peakQps))
    println("场景        | 延迟   | 并发需求 | 建议配置（含 30% 余量）")
    println("乐观 (P50)  | %5.1fms | %7.1f  | %d".format(p50Ms, inFlight(peakQps, p50Ms),
        ceil(inFlight(peakQps, p50Ms) * 1.3).toInt()))
    println("典型 (P95)  | %5.1fms | %7.1f  | %d".format(p95Ms, inFlight(peakQps, p95Ms),
        ceil(inFlight(peakQps, p95Ms) * 1.3).toInt()))
    println("悲观 (P99)  | %5.1fms | %7.1f  | %d".format(p99Ms, inFlight(peakQps, p99Ms),
        ceil(inFlight(peakQps, p99Ms) * 1.3).toInt()))
    println()
    println("建议：以 P95 那一行为基准配置，用有界队列 + 限流保护住 P99 的极端情况。")
}

三、预期输出（关键部分）

=== 危险演示：同一个接口，两种算法差多少？===
峰值 QPS = 1000
按 P50 计算：L = 1000 × 0.008 =   8.0 个
按 P99 计算：L = 1000 × 0.060 =  60.0 个

两个数字差 7.5 倍。

四、四个必须记住的点

λ 和 W 必须来自同一段业务。 用「全站平均 QPS」乘「全站平均延迟」得到的数字没有意义——要么按接口算，要么按资源维度（都走数据库的算一组）算。
用峰值 QPS，不用平均 QPS。 系统是在峰值时刻垮掉的，不是平均时刻。
同时算 P50 版和 P99 版。 P50 版告诉你「平时需要多少」，P99 版告诉你「最坏时刻需要多少」。两者的差距就是你的风险敞口。
Little’s Law 只描述稳态平均，不含排队。 所以算出来的数字是下界，实际配置要考虑排队余量（第 5 节解释了为什么）。

五、动手改造

改动	观察什么
把 `peakQps` 从 1000 改成 10000	资源需求线性增长——但你的数据库连接上限是固定的，什么时候会撞墙？
把 P99 从 60ms 改成 300ms	需要的并发变成多少？这解释了为什么「一次 GC 停顿」能让连接池瞬间打满
在 `capacityPlan` 里把余量从 30% 改成 50%	成本增加多少？（把它换算成机器台数，就明白 headroom 是有代价的）
自己加一个「重试」参数：假设 5% 的请求会重试一次	λ 实际变成多少？资源需求涨多少？（这就是重试风暴的数学模型）

六、这段代码的局限

它假设到达率是恒定的，真实流量有波峰波谷，瞬时并发会远高于平均值。
它不包含排队模型，所以「需要 8 个连接」不代表「8 个连接就够了」。
它假设请求之间相互独立，而真实系统中慢请求会占用资源影响后续请求。

配套代码：SLI 采集与错误预算

Mon, 01 Jan 0001 00:00:00 +0000

8.4 配套代码：SLI 采集与错误预算

对应小节：8.4 生产观测：SLI 与错误预算三部分：① SLO 定义（可执行）；② 错误预算 PromQL；③ 看板与告警的数据源。

一、可执行的 SLO 定义

# slo/slos.yaml —— 机器可读的 SLO 定义
# 用于生成：Prometheus 记录规则、Grafana 看板、错误预算告警
slos:
  # ═══ 可用性 ═══
  - name: orders-availability
    title: "订单查询可用性"
    description: "订单查询接口的非 5xx 比例"
    sli:
      type: ratio
      good: 'sum(rate(http_requests_total{uri="/orders/{id}", status!~"5.."}[5m]))'
      total: 'sum(rate(http_requests_total{uri="/orders/{id}"}[5m]))'
    objective: 0.999
    window: 30d
    error_budget: 0.001

  # ═══ 延迟 ═══
  - name: orders-latency
    title: "订单查询延迟"
    description: "订单查询 P99 低于 200ms 的比例"
    sli:
      type: threshold
      metric: 'http_request_duration_seconds_bucket{uri="/orders/{id}"}'
      threshold: 0.2
      # good = 落在 200ms 桶内的请求数
      good: 'sum(rate(http_request_duration_seconds_bucket{uri="/orders/{id}", le="0.2"}[5m]))'
      total: 'sum(rate(http_request_duration_seconds_count{uri="/orders/{id}"}[5m]))'
    objective: 0.999
    window: 30d
    error_budget: 0.001
    # ⚠️ 负载前提：低流量时 P99 不稳定
    precondition: 'sum(rate(http_requests_total{uri="/orders/{id}"}[5m])) > 100'

  # ═══ 业务 SLI（比技术 SLI 更接近真实价值）═══
  - name: order-creation-success
    title: "下单成功率"
    description: "下单请求中业务成功的比例"
    sli:
      type: ratio
      good: 'sum(rate(business_orders_success_total[5m]))'
      total: 'sum(rate(business_orders_total[5m]))'
    objective: 0.995
    window: 30d
    error_budget: 0.005

注意三项的设计差异：

配套代码：三种负载曲线的 k6 脚本

Mon, 01 Jan 0001 00:00:00 +0000

3.4 配套代码：三种负载曲线的 k6 脚本

对应小节：3.4 负载曲线三份可直接运行的脚本：阶梯加压、恒定到达率、尖峰测试。

一、阶梯加压：找拐点

// loadtest/profile-staircase.js
import http from 'k6/http';
import { check } from 'k6';

const LEVELS = [100, 200, 400, 700, 1000, 1500, 2000];

const stages = [];
for (const target of LEVELS) {
  stages.push({ target, duration: '30s' });   // 爬升：让系统升到该级
  stages.push({ target, duration: '2m' });    // ⚠️ 稳态：采数据必须在这里，至少 2 分钟
}

export const options = {
  scenarios: {
    staircase: {
      executor: 'ramping-arrival-rate',
      startRate: 50,
      timeUnit: '1s',
      preAllocatedVUs: 500,
      maxVUs: 5000,
      stages,
    },
  },
  // 故意不设 thresholds：容量测试的目的是找拐点，不是判定通过/失败
  discardResponseBodies: true,
};

function zipf(max) {
  return Math.max(1, Math.floor(max * Math.pow(Math.random(), 3)) + 1);
}

export default function () {
  const res = http.get(`${__ENV.BASE_URL}/orders/${zipf(1_000_000)}`, {
    tags: { name: 'GET /orders/{id}' },
  });
  check(res, { ok: (r) => r.status === 200 });
}

关键检查：每级的稳态窗口（那 2 分钟）才是采数据的区间。如果只跑 30 秒的爬升段，你会得到一条平坦且偏低的曲线（见 3.4 节的解释）。

配套代码：基线与噪声底线

Mon, 01 Jan 0001 00:00:00 +0000

9.4 配套代码：基线与噪声底线

对应小节：9.4 步骤三：建立基线与噪声底线

一、先验证观测回路（不测性能，只验证"仪表能读数"）

#!/usr/bin/env bash
# tools/step3a-verify-observability.sh
#
# ═══ 为什么先做这一步 ═══
# 如果仪表本身不准，后面所有数字都是错的。
# 这一步【不关心性能好坏】，只关心「数字能不能对上」。
set -euo pipefail

BASE="${BASE_URL:-http://localhost:8080}"
PG="${PG_CONN:-postgresql://app:app@localhost:5432/shortlink}"

pass=0; fail=0
ok()   { echo "   ✅ $1"; pass=$((pass+1)); }
bad()  { echo "   ❌ $1"; fail=$((fail+1)); }

echo "═══ 观测回路验证 ═══"
echo

# ── ① 指标端点可用 ──
echo "① Prometheus 端点"
if curl -sf "$BASE/metrics" -o /tmp/m.txt; then
  ok "可访问，共 $(wc -l < /tmp/m.txt) 行指标"
else
  bad "无法访问 $BASE/metrics"
fi

# ── ② 四层指标都在 ──
echo
echo "② 四层指标覆盖"
check_metric() {
  if grep -q "^$1" /tmp/m.txt 2>/dev/null; then ok "$1"; else bad "$1 缺失"; fi
}
check_metric "http_server_requests_seconds"
check_metric "app_request_duration"
check_metric "jvm_memory_used_bytes"
check_metric "jvm_gc_pause_seconds"
check_metric "hikaricp_connections_active"
check_metric "db_pool_pending"
check_metric "app_cache_hit_rate"

# ── ③ 计数守恒：客户端请求数 ≈ 服务端请求数 ──
echo
echo "③ 计数守恒（测 100 次请求）"
before=$(grep '^http_server_requests_seconds_count' /tmp/m.txt | awk '{s+=$NF} END{print s+0}')
for i in $(seq 1 100); do
  curl -sf -o /dev/null "$BASE/health" || true
done
sleep 1
after=$(curl -sf "$BASE/metrics" | grep '^http_server_requests_seconds_count' | awk '{s+=$NF} END{print s+0}')
delta=$((after - before))
if [ "$delta" -ge 100 ]; then
  ok "客户端 100 次 / 服务端计数 +$delta（对得上）"
else
  bad "客户端 100 次 / 服务端只 +$delta（有丢失 —— 指标采样或中间件问题）"
fi

# ── ④ 延迟直方图有分布（不是全落在 +Inf）──
echo
echo "④ 延迟直方图分布"
buckets=$(curl -sf "$BASE/metrics" | grep -c 'app_request_duration_bucket' || true)
if [ "$buckets" -ge 5 ]; then
  ok "有 $buckets 个桶（分布可算分位数）"
else
  bad "只有 $buckets 个桶 —— 直方图配置有问题"
fi

# ── ⑤ 依赖计时与端到端能对上 ──
echo
echo "⑤ 依赖级 vs 端到端"
cat > /tmp/probe.js <<'JS'
import http from 'k6/http';
export const options = { vus: 2, duration: '15s', thresholds: {} };
const codes = open('../data/hot-codes.txt').split('\n').filter(Boolean);
export default function () {
  http.get(`http://localhost:8080/${codes[Math.floor(Math.random()*codes.length)]}`,
    { redirects: 0 });
}
JS
(cd perf/k6 && k6 run --quiet --no-summary /tmp/probe.js >/dev/null 2>&1) || true
sleep 2
e2e=$(curl -sf "$BASE/metrics" | grep '^app_request_duration_seconds_sum' | awk '{s+=$NF} END{print s+0}')
dep=$(curl -sf "$BASE/metrics" | grep '^app_db_query_seconds_sum' | awk '{s+=$NF} END{print s+0}')
if [ -n "$e2e" ] && [ -n "$dep" ]; then
  ratio=$(python3 -c "print(f'{$dep/$e2e*100:.0f}' if $e2e>0 else 'n/a')")
  ok "依赖总耗时占端到端 ${ratio}%（埋雷 ① 生效时应 > 80%）"
else
  bad "缺少 app_db_query_seconds 指标 —— 依赖级计时未埋"
fi

echo
echo "═════════════════════════════════════"
echo "通过 $pass 项 / 失败 $fail 项"
if [ "$fail" -gt 0 ]; then
  echo
  echo "❌ 观测回路不可信 —— 【不要】开始测性能"
  echo "   先修仪表：数字对不上的压测结果没有讨论价值"
  exit 1
fi
echo "✅ 观测回路可信，可以开始基线"

预期输出：

配套代码：把 SLO 写成代码

Mon, 01 Jan 0001 00:00:00 +0000

1.4 配套代码：把 SLO 写成代码

对应小节：1.4 SLO 的四要素写法核心思路：让「SLO 写得不完整」这件事在编译期或测试期就失败，而不是等到验收时才发现。

一、为什么要把 SLO 变成代码

写在文档里的 SLO 会腐烂：改代码的人不看文档，看文档的人不知道代码。

把四要素变成必填字段，就能得到两个好处：

无法遗漏：缺字段直接编译不过 / 测试失败。
可派生：从 SLO 自动生成直方图桶边界、告警表达式、验收脚本参数。

二、SLO 的数据结构

// src/main/kotlin/slo/Slo.kt
package slo

import java.time.Duration

/** 测量点：必须显式指定，不能默认 */
enum class MeasurementPoint(val label: String) {
    CLIENT("压测客户端 / 真实用户"),
    GATEWAY("网关 / 负载均衡"),
    IN_APP("应用内埋点（仅用于定位，不能用于验收）"),
}

/** 数据分布：必须写明，因为它会显著影响缓存命中率与锁竞争 */
enum class DataDistribution(val label: String) {
    UNIFORM("均匀分布"),
    ZIPF("幂律（齐夫）分布"),
    REAL_REPLAY("真实流量回放"),
}

data class Slo(
    // ① 指标 + 阈值
    val endpoint: String,
    val latencyP99Ms: Long,
    val latencyP999Ms: Long,          // 至少两个分位数
    val errorRateMax: Double,

    // ② 负载与数据前提
    val targetQps: Int,
    val dataRows: Long,
    val distribution: DataDistribution,
    val cacheState: String,           // "预热 5 分钟" / "冷缓存"

    // ③ 测量点
    val measurementPoint: MeasurementPoint,

    // ④ 持续时长与验收方式
    val warmup: Duration,
    val steadyState: Duration,
    val rounds: Int,                  // 跑几轮、取中位数

    // 附加：环境与崩溃线
    val environment: String,
    val crashLine: String,
)

三、校验：把「不完整」变成错误

// src/main/kotlin/slo/SloValidation.kt
package slo

fun Slo.validate(): List<String> {
    val problems = mutableListOf<String>()

    // ① 指标 + 阈值
    if (latencyP99Ms <= 0) problems += "P99 阈值必须为正数"
    if (latencyP999Ms <= latencyP99Ms) {
        problems += "P999 阈值(${latencyP999Ms}ms)必须大于 P99(${latencyP99Ms}ms)——否则不是长尾指标"
    }
    if (errorRateMax < 0 || errorRateMax > 1) problems += "错误率阈值必须在 0~1 之间"

    // ② 负载与数据前提
    if (targetQps <= 0) problems += "目标 QPS 必须为正数（不要留空或写 0）"
    if (dataRows <= 0) problems += "数据量必须明确（1 万行和 1 亿行的执行计划不同）"
    if (cacheState.isBlank()) problems += "缓存状态必须写明（冷缓存和热缓存的 P99 可以差几十倍）"

    // ③ 测量点
    if (measurementPoint == MeasurementPoint.IN_APP) {
        problems += "测量点不能是「应用内埋点」：它不含网络与排队，无法代表用户体验，只能用于定位"
    }

    // ④ 持续时长
    if (warmup.isZero) problems += "必须声明预热时长，且预热数据不计入统计"
    if (steadyState < Duration.ofMinutes(3)) {
        problems += "稳态时长 ${steadyState.toMinutes()} 分钟偏短：至少 3 分钟才能覆盖一个 GC/缓存周期"
    }
    if (rounds < 3) problems += "至少跑 3 轮，否则无法区分真实差异与噪声"

    // 附加
    if (environment.isBlank()) problems += "必须写明环境（实例规格、副本数、容器 CPU limit）"
    if (crashLine.isBlank()) problems += "必须定义崩溃线（压力测试的终止条件）"

    return problems
}

用法：写成单元测试，SLO 定义有问题时 CI 直接红。

配套代码：环境检查与事件时间线

Mon, 01 Jan 0001 00:00:00 +0000

5.4 配套代码：环境检查与事件时间线

对应小节：5.4 环境隔离清单两件事：① 实验前逐项检查环境；② 实验期间记录事件时间线（用于解释异常）。

一、环境检查脚本

#!/usr/bin/env bash
# tools/check-environment.sh <EXP_ID>
#
# 实验前运行，逐项检查环境是否"干净"。
set -uo pipefail

EXP_ID="${1:?usage: check-environment.sh <EXP_ID>}"
OUT="docs/experiments/${EXP_ID}/results/env-check.txt"
mkdir -p "$(dirname "$OUT")"

PASS=0; WARN=0; FAIL=0

ok()   { echo "  ✅ $1"; PASS=$((PASS+1)); }
warn() { echo "  ⚠️  $1"; WARN=$((WARN+1)); }
bad()  { echo "  ❌ $1"; FAIL=$((FAIL+1)); }

{
echo "═══ 环境检查 $(date -Iseconds) ═══"
echo

# ── ① CPU 状态 ──────────────────────────────────────────
echo "① CPU 状态"
GOV=$(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo "n/a")
if [ "$GOV" = "performance" ]; then ok "governor = performance"
elif [ "$GOV" = "n/a" ]; then warn "governor 不可读（非 Linux 或权限不足）"
else warn "governor = $GOV（非 performance，可能降频）：sudo cpupower frequency-set -g performance"; fi

echo "  可见核数: $(nproc)"
echo

# ── ② steal 时间（云主机邻居抢占）──────────────────────
echo "② steal 时间（连续采样 5 次）"
ST_VALUES=()
for i in $(seq 1 5); do
  ST=$(vmstat 1 2 2>/dev/null | tail -1 | awk '{print $17}')
  [ -n "$ST" ] && ST_VALUES+=("$ST")
  sleep 1
done
if [ ${#ST_VALUES[@]} -gt 0 ]; then
  MAX_ST=$(printf '%s\n' "${ST_VALUES[@]}" | sort -rn | head -1)
  echo "   采样值: ${ST_VALUES[*]}"
  if [ "$MAX_ST" -gt 3 ] 2>/dev/null; then
    bad "st 最高 $MAX_ST% > 3% —— 被邻居抢占 CPU，环境不可控"
  elif [ "$MAX_ST" -gt 1 ] 2>/dev/null; then
    warn "st 最高 $MAX_ST% —— 轻微抢占，记录下来"
  else
    ok "st 最高 $MAX_ST% —— 环境干净"
  fi
else
  warn "无法读取 st（非 Linux）"
fi
echo

# ── ③ 容器限制与节流 ────────────────────────────────────
echo "③ 容器资源限制"
if [ -f /sys/fs/cgroup/cpu.max ]; then
  read -r QUOTA PERIOD < /sys/fs/cgroup/cpu.max
  if [ "$QUOTA" = "max" ]; then
    bad "未设置 CPU limit —— 与生产不一致时，数据不可迁移（第 4.8 节）"
  else
    awk -v q="$QUOTA" -v p="$PERIOD" 'BEGIN{printf "  CPU limit = %.2f 核\n", q/p}'
  fi
  NR_P=$(awk '/nr_periods/{print $2}' /sys/fs/cgroup/cpu.stat 2>/dev/null || echo 0)
  NR_T=$(awk '/nr_throttled/{print $2}' /sys/fs/cgroup/cpu.stat 2>/dev/null || echo 0)
  if [ "$NR_P" -gt 0 ] 2>/dev/null; then
    RATIO=$(awk -v p="$NR_P" -v t="$NR_T" 'BEGIN{printf "%.2f", 100*t/p}')
    if awk -v r="$RATIO" 'BEGIN{exit !(r>25)}'; then bad "累计节流比例 ${RATIO}% > 25%"
    elif awk -v r="$RATIO" 'BEGIN{exit !(r>1)}'; then warn "累计节流比例 ${RATIO}%"
    else ok "累计节流比例 ${RATIO}%"; fi
  fi
else
  warn "未检测到 cgroup CPU 限制（非容器环境）"
fi
echo

# ── ④ 后台任务 ──────────────────────────────────────────
echo "④ 后台任务检查"
FOUND=0
for pat in "backup" "pg_dump" "logrotate" "updatedb" "apt" "yum" "dnf" "unattended"; do
  if pgrep -a -f "$pat" > /dev/null 2>&1; then
    bad "检测到进程: $pat"; pgrep -a -f "$pat" | head -2 | sed 's/^/      /'
    FOUND=1
  fi
done
[ "$FOUND" -eq 0 ] && ok "未检测到常见后台任务"
echo

# ── ⑤ 高 CPU 进程（可能有其他负载）─────────────────────
echo "⑤ 当前 CPU 占用 Top 5"
ps aux --sort=-%cpu 2>/dev/null | head -6 | tail -5 | awk '{printf "   %-20s %5s%% CPU  %5s%% MEM\n", substr($11,1,20), $3, $4}' || echo "   （ps 格式不同，跳过）"
echo

# ── ⑥ 数据库状态 ────────────────────────────────────────
echo "⑥ 数据库状态"
if command -v psql > /dev/null 2>&1 && [ -n "${PG_CONN:-}" ]; then
  echo "   长事务（> 30 秒）："
  psql "$PG_CONN" -tAc "
    SELECT count(*) FROM pg_stat_activity
    WHERE state <> 'idle' AND now() - query_start > interval '30 seconds';" 2>/dev/null | \
    sed 's/^/      数量: /' || warn "无法查询数据库"
  echo "   连接使用率："
  psql "$PG_CONN" -tAc "
    SELECT round(100.0*count(*)/current_setting('max_connections')::int, 1)
    FROM pg_stat_activity;" 2>/dev/null | sed 's/^/      /' || true
else
  warn "未设置 PG_CONN 或 psql 不可用，跳过数据库检查"
fi
echo

# ── ⑦ 压测客户端位置 ────────────────────────────────────
echo "⑦ 压测客户端位置"
echo "   ⚠️  需要人工确认：压测客户端必须【独立于】被测服务"
echo "      同机会互相抢 CPU，两个方向都失真（第 4 章 4.1）"
echo

# ── ⑧ 观测配置 ──────────────────────────────────────────
echo "⑧ 观测配置（必须与基线组一致）"
echo "   JFR: ${JFR_SETTINGS:-未设置}"
echo "   profiler: ${PROFILER:-未启用}"
echo "   日志级别: ${LOG_LEVEL:-未设置}"
echo "   ⚠️  基线组与实验组必须用【同样的观测配置】，否则差异可能来自观测开销"
echo

# ── 汇总 ────────────────────────────────────────────────
echo "═══════════════════════════════════════"
echo "通过 $PASS 项，警告 $WARN 项，失败 $FAIL 项"
if [ "$FAIL" -gt 0 ]; then
  echo "❌ 存在失败项 —— 请先修复环境，否则数据不可信"
  echo "   （仍可继续实验，但必须在报告里声明环境问题）"
elif [ "$WARN" -gt 0 ]; then
  echo "⚠️  存在警告项 —— 建议记录并评估影响"
else
  echo "✅ 环境检查通过"
fi
} | tee "$OUT"

echo
echo "结果已保存 → $OUT"

二、环境事件时间线记录

#!/usr/bin/env bash
# tools/record-events.sh <EXP_ID> [INTERVAL_SEC]
#
# 在实验期间后台运行，记录环境事件。
# 事后用它解释异常轮（第 5.3 节）。
set -uo pipefail

EXP_ID="${1:?usage: record-events.sh <EXP_ID> [interval]}"
INTERVAL="${2:-10}"
OUT="docs/experiments/${EXP_ID}/results/events.csv"
mkdir -p "$(dirname "$OUT")"

echo "开始记录环境事件（每 ${INTERVAL}s）→ $OUT"
echo "按 Ctrl-C 停止"

# CSV 表头
echo "timestamp,loadavg,steal_pct,ctx_switch,run_queue,throttled,top_proc,pg_active,pg_long_tx" > "$OUT"

cleanup() {
  echo
  echo "✅ 事件记录已保存 → $OUT"
  echo "   用它来解释异常轮："
  echo "     grep -E 'logrotate|backup' $OUT"
  exit 0
}
trap cleanup INT TERM

while true; do
  TS=$(date +%s)

  # 系统负载
  LOADAVG=$(cut -d' ' -f1 /proc/loadavg 2>/dev/null || echo "0")
  STEAL=$(vmstat 1 2 2>/dev/null | tail -1 | awk '{print $17}' || echo "0")
  CTX=$(vmstat 1 2 2>/dev/null | tail -1 | awk '{print $12}' || echo "0")
  RUNQ=$(vmstat 1 2 2>/dev/null | tail -1 | awk '{print $1}' || echo "0")

  # 节流计数
  THROTTLED=$(awk '/nr_throttled/{print $2}' /sys/fs/cgroup/cpu.stat 2>/dev/null || echo "0")

  # 占用最高的非 Java 进程（排除自己）
  TOPPROC=$(ps aux --sort=-%cpu 2>/dev/null | awk 'NR>1 && $11 !~ /java|ps|awk/ {print $11; exit}' || echo "none")

  # 数据库
  PG_ACTIVE="n/a"; PG_LONG="n/a"
  if command -v psql > /dev/null 2>&1 && [ -n "${PG_CONN:-}" ]; then
    PG_ACTIVE=$(psql "$PG_CONN" -tAc "SELECT count(*) FROM pg_stat_activity WHERE state='active';" 2>/dev/null || echo "n/a")
    PG_LONG=$(psql "$PG_CONN" -tAc "SELECT count(*) FROM pg_stat_activity WHERE state<>'idle' AND now()-query_start > interval '10 seconds';" 2>/dev/null || echo "n/a")
  fi

  echo "$TS,$LOADAVG,$STEAL,$CTX,$RUNQ,$THROTTLED,$TOPPROC,$PG_ACTIVE,$PG_LONG" >> "$OUT"

  sleep "$INTERVAL"
done

用法：

配套代码：用数据判定稳态 + 冷启动测量

Mon, 01 Jan 0001 00:00:00 +0000

2.4 配套代码：用数据判定稳态 + 冷启动测量

对应小节：2.4 预热、稳态与冷启动两个工具：① 滚动变异系数（CV）自动判定稳态；② 冷启动分段计时。

一、工具一：滚动 CV 判定稳态

// src/main/kotlin/lesson02/SteadyStateDetector.kt
package lesson02

import kotlin.math.sqrt
import kotlin.random.Random

private var sink = 0L

fun work(data: IntArray): Long {
    var s = 0L
    for (v in data) s += v
    return s
}

/**
 * 滚动统计窗口：记录最近 N 个采样点，计算均值与变异系数 CV = 标准差/均值。
 * CV 收敛到小值以下 → 认为进入稳态。
 */
class RollingStats(private val window: Int) {
    private val values = ArrayDeque<Double>()

    fun add(v: Double): Pair<Double, Double> {
        values.addLast(v)
        if (values.size > window) values.removeFirst()
        val mean = values.average()
        if (values.size < 2) return mean to Double.NaN
        val variance = values.sumOf { (it - mean) * (it - mean) } / (values.size - 1)
        val cv = sqrt(variance) / mean
        return mean to cv
    }

    val size: Int get() = values.size
}

/**
 * 每 `blockSize` 次调用采样一次，直到 CV 连续 `stableBlocks` 次低于阈值。
 *
 * @return 进入稳态所需的调用次数；若始终未达到则返回 -1
 */
fun findSteadyState(
    blockSize: Int = 2_000,
    maxBlocks: Int = 200,
    cvThreshold: Double = 0.05,
    stableBlocks: Int = 3,
    window: Int = 5,
): Pair<Int, List<Triple<Int, Double, Double>>> {
    val rnd = Random(42)
    val data = IntArray(4096) { rnd.nextInt() }
    val stats = RollingStats(window)
    val trace = mutableListOf<Triple<Int, Double, Double>>()
    var consecutiveStable = 0
    var totalCalls = 0

    repeat(maxBlocks) { block ->
        val t0 = System.nanoTime()
        repeat(blockSize) { sink += work(data) }
        val nsPerOp = (System.nanoTime() - t0).toDouble() / blockSize
        totalCalls += blockSize

        val (mean, cv) = stats.add(nsPerOp)
        trace += Triple(totalCalls, nsPerOp, cv)

        if (!cv.isNaN() && cv < cvThreshold) {
            consecutiveStable++
            if (consecutiveStable >= stableBlocks) {
                return totalCalls to trace
            }
        } else {
            consecutiveStable = 0
        }
    }
    return -1 to trace
}

fun main() {
    println("=== 用滚动 CV 判定稳态 ===")
    println("判据：连续 3 个采样窗口的 CV < 5%\n")
    println("累计调用次数      单次耗时(ns/op)     滚动CV     状态")
    println("-".repeat(64))

    val (steadyAt, trace) = findSteadyState()
    trace.take(20).forEachIndexed { i, (calls, ns, cv) ->
        val status = when {
            cv.isNaN() -> "采样中"
            cv > 0.10 -> "未稳"
            cv > 0.05 -> "接近"
            else -> "✅ 稳定"
        }
        println("%,14d   %12.1f   %10s   %s".format(
            calls, ns, if (cv.isNaN()) "—" else "%.1f%%".format(cv * 100), status))
    }

    println()
    if (steadyAt > 0) {
        println("✅ 在累计 %,d 次调用后进入稳态".format(steadyAt))
        println("   即使用固定预热策略，也应该至少预热这么多")
    } else {
        println("❌ 未能在 %d 个窗口内进入稳态".format(trace.size))
        println("   说明环境噪声过大——这本身就是重要发现（见第 5 章的噪声底线）")
    }
    println()
    println("sink = $sink")
}

二、预期输出形态

累计调用次数      单次耗时(ns/op)     滚动CV     状态
----------------------------------------------------------------
         2,000         1180.4         —       采样中
         4,000          612.1       45.2%     未稳
         6,000          391.7       52.8%     未稳
         8,000          310.2       41.3%     未稳
        10,000          265.4       26.7%     未稳
        12,000          248.9       14.2%     未稳
        14,000          239.1        7.8%     接近
        16,000          234.6        4.1%     ✅ 稳定
        18,000          232.8        2.9%     ✅ 稳定
        20,000          231.9        2.4%     ✅ 稳定

✅ 在累计 16,000 次调用后进入稳态

注意 CV 曲线是「从大到小收敛」，而不是突然达标。这就是为什么「固定预热 5 轮」不可靠——你不知道自己的程序需要几轮。

配套代码：线程与协程快照分析

Mon, 01 Jan 0001 00:00:00 +0000

6.4 配套代码：线程与协程快照分析

对应小节：6.4 线程与协程快照两件事：① 多份快照的对比分析；② 协程快照与协程泄漏检测。

一、多份快照的对比分析器

# tools/analyze-threads.py <threads-*.txt>...
"""
从多份线程快照里找出"持续存在"的问题。

核心思路：
  单张快照是瞬时状态，多张对比才能区分"路过"与"堵住"。
"""
import re
import sys
from collections import Counter, defaultdict


def parse_dump(path):
    """解析 jstack/jcmd Thread.print 输出"""
    threads = []
    current = None
    with open(path, errors="ignore") as f:
        for line in f:
            # 线程头："name" #id prio=... tid=... nid=...
            m = re.match(r'^"([^"]+)"\s+#(\d+)\s+.*nid=(\S+)', line)
            if m:
                if current:
                    threads.append(current)
                current = {"name": m.group(1), "id": m.group(2),
                           "nid": m.group(3), "state": None, "stack": []}
                continue
            if current is not None:
                ms = re.search(r"java\.lang\.Thread\.State:\s*([A-Z_]+)", line)
                if ms:
                    current["state"] = ms.group(1)
                    continue
                mt = re.match(r"^\s+at\s+(\S+)", line)
                if mt:
                    current["stack"].append(mt.group(1))
    if current:
        threads.append(current)
    return threads


def main(paths):
    dumps = [parse_dump(p) for p in paths]
    if not dumps:
        print("❌ 没有读到快照")
        return

    print("═" * 84)
    print(f"线程快照对比分析（{len(dumps)} 份）")
    print("═" * 84)
    print()

    # ① 每份的状态分布
    print("【① 状态分布（每份快照）】")
    for path, threads in zip(paths, dumps):
        states = Counter(t["state"] for t in threads if t["state"])
        total = sum(states.values())
        print(f"  {path}  线程数={len(threads)}")
        for st, c in states.most_common():
            pct = c / total * 100 if total else 0
            bar = "█" * int(pct / 3)
            print(f"     {st:<20}{c:>4}  {pct:5.1f}%  {bar}")
    print()

    # ② 持续存在的栈帧（在所有快照里都出现的）
    print("【② 持续存在的栈帧 Top 20】")
    print("    （在所有快照里都出现 → 不是「路过」，是「堵住」）")
    stack_sets = []
    for threads in dumps:
        frames = set()
        for t in threads:
            frames.update(t["stack"])
        stack_sets.append(frames)

    persistent = set.intersection(*stack_sets) if stack_sets else set()
    # 统计每个持续帧在多少线程里出现（取最后一份快照的数量）
    last_counts = Counter()
    for t in dumps[-1]:
        for f in t["stack"]:
            if f in persistent:
                last_counts[f] += 1

    for frame, _ in last_counts.most_common(20):
        # 在所有快照里的出现次数
        occurrences = sum(1 for ss in stack_sets if frame in ss)
        print(f"  [{occurrences}/{len(dumps)} 份]  {frame[:70]}")
    print()

    # ③ 关键模式检测
    print("【③ 关键模式检测】")
    patterns = {
        "连接池排队": ["HikariPool.getConnection", "getConnection"],
        "等网络 IO": ["socketRead0", "socketRead", "SocketInputStream"],
        "等锁（park）": ["Unsafe.park", "LockSupport.park"],
        "等队列/任务": ["LinkedBlockingQueue.take", "ArrayBlockingQueue"],
        "队列满（生产者阻塞）": ["ArrayBlockingQueue.put", "LinkedBlockingQueue.put"],
        "同步日志刷盘": ["FileOutputStream.write", "FileDispatcherImpl.write"],
        "主动 sleep": ["Thread.sleep"],
        "类加载锁": ["ClassLoader.loadClass", "defineClass"],
        "协程调度": ["DispatchedTask", "CoroutineScheduler"],
    }
    for label, keywords in patterns.items():
        count_by_dump = []
        for threads in dumps:
            c = sum(1 for t in threads
                    if any(any(k in f for k in keywords) for f in t["stack"]))
            count_by_dump.append(c)
        if any(count_by_dump):
            trend = "→".join(str(c) for c in count_by_dump)
            flag = " ⚠️ 持续" if all(c > 0 for c in count_by_dump) else ""
            print(f"  {label:<22}线程数: {trend}{flag}")
    print()

    # ④ BLOCKED 的详细信息
    blocked_in_last = [t for t in dumps[-1] if t["state"] == "BLOCKED"]
    if blocked_in_last:
        print(f"【④ BLOCKED 线程详情（{len(blocked_in_last)} 个）】")
        for t in blocked_in_last[:5]:
            print(f"  {t['name']} (nid={t['nid']})")
            for f in t["stack"][:5]:
                print(f"      at {f}")
            print()
    else:
        print("【④ 无 BLOCKED 线程】→ 排除锁竞争")
    print()

    # ⑤ 线程数趋势（是否泄漏）
    counts = [len(d) for d in dumps]
    print(f"【⑤ 线程数趋势】{' → '.join(map(str, counts))}")
    if len(counts) >= 3 and counts[-1] > counts[0] * 1.5:
        print("  ❌ 线程数持续增长 → 疑似线程泄漏")
    else:
        print("  ✅ 线程数稳定")
    print()

    print("═" * 84)
    print("判读要点：")
    print("  ① 大量 BLOCKED → 锁竞争")
    print("  ② 大量 RUNNABLE 且 CPU 高 → 真的在算")
    print("  ③ 「持续存在」的栈才是真问题（单份快照里的可能只是路过）")
    print("  ④ 栈特征比状态更有指示性（HikariPool → 池排队；socketRead → 等下游）")
    print("  ⑤ RUNNABLE 线程数 == CPU 核数 且 CPU 低 → 疑似调度器被占满")
    print("═" * 84)


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("usage: analyze-threads.py <threads-1.txt> [threads-2.txt ...]")
        sys.exit(1)
    main(sys.argv[1:])

二、自动采集多份快照并分析

#!/usr/bin/env bash
# tools/capture-threads.sh <EXP_ID> [COUNT] [INTERVAL]
set -uo pipefail

EXP_ID="${1:?usage: capture-threads.sh <exp_id> [count] [interval]}"
COUNT="${2:-5}"
INTERVAL="${3:-3}"
DIR="docs/experiments/${EXP_ID}/results/threads"
mkdir -p "$DIR"

PID=$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')
[ -z "$PID" ] && { echo "❌ 找不到应用进程"; exit 1; }

echo "采集 $COUNT 份线程快照（间隔 ${INTERVAL}s，PID=$PID）"
for i in $(seq 1 "$COUNT"); do
  jcmd "$PID" Thread.print > "$DIR/threads-$i.txt" 2>/dev/null
  echo "  threads-$i.txt"
  [ "$i" -lt "$COUNT" ] && sleep "$INTERVAL"
done

echo
python3 tools/analyze-threads.py "$DIR"/threads-*.txt | tee "$DIR/analysis.txt"

三、协程快照与泄漏检测

3.1 协程 dump（排障用）

// src/main/kotlin/debug/CoroutineDebug.kt
package debug

import kotlinx.coroutines.debug.DebugProbes

/**
 * 协程调试工具。
 *
 * ⚠️ 开销很大（10%~30%），只能在排障时临时启用。
 *    生产环境请用下面的 CoroutineMonitor（开销低）。
 */
object CoroutineDebug {

    fun install() {
        DebugProbes.install()
    }

    /** dump 所有活跃协程及挂起点 */
    fun dump() {
        DebugProbes.dumpCoroutines()
    }

    /**
     * 只打印摘要（协程数量 + 挂起点分布），比 dumpCoroutines 开销小。
     */
    fun summary() {
        val coroutines = DebugProbes.dumpCoroutinesInfo()
        println("活跃协程数: ${coroutines.size}")

        // 按挂起点分组统计
        val byLocation = coroutines
            .mapNotNull { it.lastObservedStackTrace().firstOrNull() }
            .groupingBy { it.toString().substringBefore("(") }
            .eachCount()
            .entries
            .sortedByDescending { it.value }
            .take(10)

        println("挂起点分布（Top 10）：")
        byLocation.forEach { (loc, count) ->
            val pct = count * 100.0 / coroutines.size
            println("  %6.1f%%  %4d 个  %s".format(pct, count, loc))
        }

        // 关键模式检测
        val stackTraces = coroutines.flatMap { it.lastObservedStackTrace() }.map { it.toString() }
        listOf(
            "连接池排队" to listOf("HikariPool", "getConnection"),
            "JDBC 阻塞" to listOf("jdbc", "QueryExecutor", "PgConnection"),
            "网络阻塞" to listOf("socketRead", "SocketInputStream"),
            "锁等待" to listOf("Mutex", "lock"),
            "队列等待" to listOf("Channel", "receive", "send"),
        ).forEach { (label, keywords) ->
            val c = stackTraces.count { st -> keywords.any { it in st } }
            if (c > 0) {
                println("  ⚠️  $label: $c 个协程（%.1f%%）".format(c * 100.0 / coroutines.size))
            }
        }
    }

    fun uninstall() {
        DebugProbes.uninstall()
    }
}

// build.gradle.kts
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.9.0")
}

3.2 低开销的协程监控（生产可用）

// src/main/kotlin/metrics/CoroutineMonitor.kt
package metrics

import io.micrometer.core.instrument.Gauge
import io.micrometer.core.instrument.MeterRegistry
import kotlinx.coroutines.Job
import kotlinx.coroutines.launch
import kotlinx.coroutines.CoroutineScope
import java.util.concurrent.atomic.AtomicInteger

/**
 * 低开销的协程监控：只统计数量，不采集栈。
 * 可以长期开启（生产环境可用）。
 */
class CoroutineMonitor(registry: MeterRegistry) {

    private val active = AtomicInteger(0)
    private val maxObserved = AtomicInteger(0)

    init {
        Gauge.builder("app.coroutines.active") { active.get().toDouble() }
            .description("当前活跃协程数")
            .register(registry)

        Gauge.builder("app.coroutines.max_observed") { maxObserved.get().toDouble() }
            .description("观测到的最大活跃协程数（用于判断是否堆积）")
            .register(registry)
    }

    /** 包装一个协程，统计它的活跃状态 */
    fun CoroutineScope.tracked(block: suspend () -> Unit): Job = launch {
        val n = active.incrementAndGet()
        maxObserved.updateAndGet { maxOf(it, n) }
        try {
            block()
        } finally {
            active.decrementAndGet()
        }
    }

    val activeCount: Int get() = active.get()
}

判读规则：

配套代码：缓存的三重防护与代价评估

Mon, 01 Jan 0001 00:00:00 +0000

7.4 配套代码：缓存的三重防护与代价评估

对应小节：7.4 缓存一份可直接抄用的 Caffeine 实现（含三重防护），以及缓存对 P99 影响的计算工具。

一、完整的缓存实现（含三重防护）

// src/main/kotlin/cache/OrderCache.kt
package cache

import com.github.benmanes.caffeine.cache.AsyncCache
import com.github.benmanes.caffeine.cache.Caffeine
import com.github.benmanes.caffeine.cache.Expiry
import com.github.benmanes.caffeine.cache.stats.CacheStats
import io.micrometer.core.instrument.Gauge
import io.micrometer.core.instrument.MeterRegistry
import kotlinx.coroutines.future.await
import java.time.Duration
import java.util.concurrent.CompletableFuture
import java.util.concurrent.Executor
import kotlin.random.Random

data class Order(val id: Long, val userId: Long, val amount: Long)

/** 空值哨兵：防穿透 */
private val NULL_SENTINEL = Order(id = -1, userId = -1, amount = -1)

class OrderCache(
    private val loader: (Long) -> Order?,          // 回源函数（阻塞）
    private val executor: Executor,                // 回源用的线程池
    registry: MeterRegistry,
) {
    /**
     * 用 AsyncCache 而不是同步 cache：
     *   ① get(key, mapping) 是原子的 → 天然「单飞」（防击穿）
     *   ② 通过 CompletableFuture.await() 桥接到协程
     *
     * 三重防护中的两重在这里：
     *   防护一（单飞）：Caffeine 的原子 get
     *   防护二（TTL 抖动）：下面的 Expiry 实现
     *   防护三（空值缓存）：NULL_SENTINEL
     */
    private val cache: AsyncCache<Long, Order> = Caffeine.newBuilder()
        .maximumSize(100_000)                       // ⭐ 必须有界（防 OOM）
        .expireAfter(expireWithJitter())            // ⭐ TTL + 抖动（防雪崩）
        .recordStats()                              // ⭐ 必须有指标
        .buildAsync()

    init {
        // 命中率（最核心的指标）
        Gauge.builder("app.cache.hit_rate") { cache.synchronous().stats().hitRate() }
            .description("缓存命中率")
            .register(registry)

        // 未命中时的延迟（关键：只看命中率不够）
        Gauge.builder("app.cache.miss_latency_p99") { missLatencyP99.get().toDouble() }
            .description("未命中时的 P99 延迟（ms）")
            .register(registry)

        // 缓存大小与驱逐
        Gauge.builder("app.cache.size") { cache.synchronous().estimatedSize().toDouble() }
            .register(registry)
        Gauge.builder("app.cache.evictions") { cache.synchronous().stats().evictionCount().toDouble() }
            .register(registry)
    }

    /** 防护二：TTL 加随机抖动（±20%），避免大批 key 同时失效 */
    private fun expireWithJitter(): Expiry<Long, Order> =
        object : Expiry<Long, Order> {
            private val baseMs = Duration.ofMinutes(10).toMillis()
            private fun ttl() = baseMs + Random.nextLong(-baseMs / 5, baseMs / 5)

            override fun expireAfterCreate(key: Long, value: Order, currentTime: Long) = ttl()
            override fun expireAfterUpdate(key: Long, value: Order, currentTime: Long, currentDuration: Long) = ttl()
            override fun expireAfterRead(key: Long, value: Order, currentTime: Long, currentDuration: Long) = currentDuration
        }

    private val missLatencyP99 = java.util.concurrent.atomic.AtomicLong(0)

    /**
     * 读（含三重防护）
     *
     * 防护一（单飞）：cache.get(key) { ... } 保证同一 key 的并发回源只执行一次
     */
    suspend fun get(id: Long): Order? {
        val result = cache.get(id) { k, _ ->
            CompletableFuture.supplyAsync({
                val t0 = System.nanoTime()
                val value = loader(k) ?: NULL_SENTINEL     // 防护三：缓存空值
                missLatencyP99.set((System.nanoTime() - t0) / 1_000_000)
                value
            }, executor)
        }.await()

        return if (result === NULL_SENTINEL) null else result
    }

    /** 写：先更新数据库，再删缓存（Cache-Aside 的正确顺序） */
    suspend fun invalidate(id: Long) {
        cache.synchronous().invalidate(id)
    }

    fun stats(): CacheStats = cache.synchronous().stats()

    /** 供测试/监控使用 */
    fun estimatedSize(): Long = cache.synchronous().estimatedSize()
}

使用示例：

配套代码：分配速率、GC 日志与 Humongous 对象

Mon, 01 Jan 0001 00:00:00 +0000

2.5 配套代码：分配速率、GC 日志与 Humongous 对象

对应小节：2.5 内存与 GC 三件事：① 亲眼看到「分配速率决定 GC 频率」② 读懂 GC 日志 ③ 复现 Humongous 对象的陷阱。

一、实验：分配速率与 GC 频率的关系

// src/main/kotlin/lesson02/AllocationRate.kt
package lesson02

import java.lang.management.ManagementFactory
import kotlin.random.Random

private val threadBean = ManagementFactory.getThreadMXBean() as com.sun.management.ThreadMXBean

fun allocatedMb(): Double =
    threadBean.getThreadAllocatedBytes(Thread.currentThread().threadId()) / 1024.0 / 1024.0

fun gcCount(): Long =
    ManagementFactory.getGarbageCollectorMXBeans().sumOf { it.collectionCount }

fun gcTimeMs(): Long =
    ManagementFactory.getGarbageCollectorMXBeans().sumOf { it.collectionTime }

/**
 * 分配指定大小的"垃圾"，观察 GC 频率。
 * @param bytesPerIteration 每次迭代分配的字节数
 */
fun allocateGarbage(bytesPerIteration: Int, iterations: Int) {
    val rnd = Random(42)
    for (i in 0 until iterations) {
        val arr = ByteArray(bytesPerIteration)
        arr[0] = rnd.nextInt().toByte()          // 防止整个分配被消除
        if (arr[0] == Byte.MAX_VALUE) println("never")   // 让 arr 有逃逸可能
    }
}

fun measureScenario(label: String, bytesPerIteration: Int, iterations: Int) {
    val gcBefore = gcCount()
    val gcTimeBefore = gcTimeMs()
    val allocBefore = allocatedMb()

    val t0 = System.nanoTime()
    allocateGarbage(bytesPerIteration, iterations)
    val elapsedMs = (System.nanoTime() - t0) / 1_000_000.0

    val allocMb = allocatedMb() - allocBefore
    val gcDelta = gcCount() - gcBefore
    val gcTimeDelta = gcTimeMs() - gcTimeBefore

    println("%-26s %10.1f MB  分配速率 %8.1f MB/s  GC次数 %3d  GC总停顿 %5d ms"
        .format(label, allocMb, allocMb / (elapsedMs / 1000), gcDelta, gcTimeDelta))
}

fun main() {
    println("=== 分配速率 → GC 频率 的关系 ===")
    println("（堆默认大小；如果想看得更明显，用 -Xmx256m 运行）\n")
    println("%-26s %13s  %21s  %14s  %18s".format("场景", "总分配量", "分配速率", "GC次数", "GC停顿"))

    // 同样的总分配量，但速率不同
    measureScenario("小对象慢速分配", 1_024, 200_000)          // 200 MB，分 20 万次
    measureScenario("小对象快速分配", 1_024, 2_000_000)        // 2 GB
    measureScenario("大对象分配", 1_048_576, 2_000)            // 2 GB，每次 1 MB

    println()
    println("预期观察：")
    println("  1. 分配速率越高，GC 次数越多（这就是「分配速率决定 GC 频率」）")
    println("  2. 大对象场景的 GC 行为不同——1MB 的数组在 G1 下可能触发 Humongous 分配")
    println()
    println("⚠️ 这个实验会占用较多内存和 CPU，建议用 -Xmx256m 限制堆，并在空闲机器上跑。")
}

运行建议：

配套代码：告警规则与有效率复盘

Mon, 01 Jan 0001 00:00:00 +0000

8.5 配套代码：告警规则与有效率复盘

对应小节：8.5 告警设计：燃烧率与领先指标两部分：① 完整的告警规则（含 runbook）；② 告警有效率复盘脚本。

一、完整的告警规则

# observability/alerts.yml
groups:

  # ═══════════════════════════════════════════════════════════
  # P0：page（立即叫人）
  # ═══════════════════════════════════════════════════════════
  - name: p0-burn-rate
    rules:
      - alert: ErrorBudgetBurnFast
        # 双窗口：长窗口抑制误报 + 短窗口保证灵敏
        expr: |
          slo:orders_availability:burn_rate_1h > 14.4
          and
          slo:orders_availability:burn_rate_5m > 14.4
        for: 2m
        labels:
          severity: page
          slo: orders-availability
        annotations:
          summary: "订单查询错误预算燃烧过快（1h + 5m 双窗口同时超标）"
          description: |
            当前燃烧率 {{ $value | humanize }}×，按此速度约
            {{ printf "%.1f" (div 30 (div 1 $value)) }} 天将耗尽 30 天预算。
          runbook: |
            【5 分钟内的动作】
            1. 打开 Grafana 的「SLO 与错误预算」看板，看「按接口分解」面板
               → 确定是哪个接口在消耗预算
            2. 查看最近 30 分钟的发布记录
               → 如果有发布，优先考虑回滚（见 runbook-rollback）
            3. 查看相邻的「饱和度」面板
               → 连接池 pending / 队列深度 / CPU 节流，哪一项在涨？
            4. 如果 5 分钟内无法定位 → 升级给值班负责人

  - name: p0-critical-unavailable
    rules:
      - alert: ServiceUnavailable
        expr: |
          sum(rate(http_requests_total{status!~"5.."}[2m]))
            / sum(rate(http_requests_total[2m])) < 0.9
        for: 2m
        labels:
          severity: page
        annotations:
          summary: "整体成功率低于 90%（持续 2 分钟）"
          runbook: |
            1. 确认是全局还是部分实例（看 per-instance 分解）
            2. 检查依赖：数据库可达？Redis 可达？下游可达？
            3. 检查最近的变更（发布/配置/DB 迁移）
            4. 考虑限流降级（保护核心链路）

  # ═══════════════════════════════════════════════════════════
  # P1：ticket（当天处理）
  # ═══════════════════════════════════════════════════════════
  - name: p1-leading-indicators
    rules:
      # ① 连接池排队 —— 最早的信号
      - alert: ConnectionPoolSaturated
        expr: max(db_pool_pending) > 5
        for: 10m
        labels:
          severity: ticket
        annotations:
          summary: "连接池排队（pending > 5 持续 10 分钟）"
          runbook: |
            ⚠️ 【先查慢查询，不要先加池】
            1. 查最贵的语句：
               psql -c "SELECT calls, mean_exec_time, total_exec_time, left(query,50)
                        FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;"
            2. 查长事务与锁等待：
               SELECT pid, now()-xact_start AS age, state, wait_event_type
               FROM pg_stat_activity WHERE xact_start IS NOT NULL
               ORDER BY age DESC LIMIT 10;
            3. 只有在【查询正常】且【并发确实高】时，才用 Little's Law 调整池大小
            详见第 6.5 节

      # ② 容器 CPU 节流 —— "本地好、上线慢"的头号原因
      - alert: ContainerCpuThrottled
        expr: |
          rate(container_cpu_cfs_throttled_periods_total{container="app"}[5m])
          / rate(container_cpu_cfs_periods_total{container="app"}[5m]) > 0.25
        for: 10m
        labels:
          severity: ticket
        annotations:
          summary: "容器被 CPU 配额节流 > 25%"
          runbook: |
            1. 确认 CPU limit：cat /sys/fs/cgroup/cpu.max
            2. 判断 CPU 需求是否合理（用火焰图找浪费，比如日志/序列化）
            3. 需求合理 → 提高 limit；需求不合理 → 优化代码
            详见第 4.8 节

      # ③ 线程池队列积压
      - alert: ExecutorQueueBacklog
        expr: executor_queue_depth > 100
        for: 10m
        labels:
          severity: ticket
        annotations:
          summary: "线程池队列积压 > 100"
          runbook: |
            1. 查线程在忙什么（是阻塞 IO 还是真的在算）：
               jcmd <pid> Thread.print | grep -A3 "BLOCKED\|socketRead\|HikariPool"
            2. 如果是阻塞 IO → 考虑异步化或增加隔离
            3. 如果是真的在算 → 考虑扩容或优化算法
            详见第 6.5 节

      # ④ 错误预算消耗过半
      - alert: ErrorBudgetHalfConsumed
        expr: slo:orders_availability:budget_remaining < 0.5
        for: 1h
        labels:
          severity: ticket
        annotations:
          summary: "错误预算已消耗 50%（30 天窗口）"
          runbook: |
            1. 看「按接口分解」确定主要消耗来源
            2. 如果是缓慢消耗 → 安排优化
            3. 如果是突发消耗 → 按 ErrorBudgetBurnFast 的 runbook 处理
            4. 考虑暂停非必要的功能发布（第 8.4 节的预算策略）

      # ⑤ 容量余量不足
      - alert: CapacityHeadroomLow
        expr: |
          max_over_time(sum(rate(http_requests_total[5m]))[1h:5m])
            / on() group_left capacity_safe_limit > 0.8
        for: 30m
        labels:
          severity: ticket
        annotations:
          summary: "峰值 QPS 已达到安全容量的 80%"
          runbook: |
            1. 确认流量趋势（是临时高峰还是持续增长）
            2. 持续增长 → 启动扩容流程（第 8.7 节的容量表）
            3. 检查是否有异常流量（爬虫、攻击、重试风暴）

  # ═══════════════════════════════════════════════════════════
  # P2：log（定期 review，不打扰人）
  # ═══════════════════════════════════════════════════════════
  - name: p2-observe-only
    rules:
      - alert: GcPauseHigh
        expr: |
          histogram_quantile(0.99,
            sum by (le) (rate(jvm_gc_pause_seconds_bucket[5m]))) > 0.2
        for: 10m
        labels:
          severity: log
        annotations:
          summary: "GC 停顿 P99 > 200ms（仅记录）"
          runbook: |
            ⚠️ 先观察，不要立刻行动：
            1. 把 GC 停顿时间戳与 P99 尖刺做时间对齐（第 6.6 节）
            2. 对齐 → 升级为 ticket 并处理
            3. 不对齐 → 考虑删除此告警（它经常不是真问题）

      - alert: SlowRequestCountHigh
        expr: increase(http_request_duration_seconds_count{le="1.0"}[10m]) == 0
        for: 10m
        labels:
          severity: log
        annotations:
          summary: "10 分钟内没有请求慢于 1 秒（分布过于干净，可能是采样问题）"

      - alert: FileDescriptorUsageHigh
        expr: process_open_fds / process_max_fds > 0.7
        for: 30m
        labels:
          severity: log
        annotations:
          summary: "文件描述符使用率 > 70%（可能是泄漏的前兆）"
          runbook: "观察趋势：如果持续上升，按第 3.5 节的浸泡分析方法排查"

二、告警有效率复盘脚本

# tools/alert-review.py <ALERTMANAGER_API> [DAYS]
"""
统计每条告警的触发次数与有效率，用于校准阈值。

有效率 = 需要人行动的触发次数 / 总触发次数

用法：
    python3 tools/alert-review.py http://alertmanager:9093 30
"""
import json
import sys
import urllib.parse
import urllib.request
from collections import defaultdict
from datetime import datetime, timedelta


def fetch_alerts(alertmanager_url, days):
    """从 Alertmanager 拉取历史告警"""
    since = (datetime.now() - timedelta(days=days)).isoformat()
    url = f"{alertmanager_url}/api/v2/alerts?" + urllib.parse.urlencode({
        "active": "false",
        "silenced": "false",
        "inhibited": "false",
    })
    try:
        with urllib.request.urlopen(url, timeout=10) as r:
            return json.load(r)
    except Exception as e:
        print(f"⚠️  无法从 Alertmanager 拉取数据：{e}", file=sys.stderr)
        return []


def main(url, days):
    alerts = fetch_alerts(url, days)

    print("═" * 88)
    print(f"告警复盘（最近 {days} 天）")
    print("═" * 88)
    print()

    if not alerts:
        print("（没有拉到数据 —— 请确认 Alertmanager 地址，或改用日志/工单系统统计）")
        print()
        print("替代方案：手工统计")
        print("  1. 从告警渠道（Slack/PagerDuty）导出历史")
        print("  2. 统计每条告警的触发次数")
        print("  3. 人工标注哪些需要行动（有效）、哪些是误报")
        print("  4. 填入下面的表格")
        print()
        print_alerts_template()
        return

    by_name = defaultdict(lambda: {"total": 0, "severity": ""})
    for a in alerts:
        name = a.get("labels", {}).get("alertname", "?")
        by_name[name]["total"] += 1
        by_name[name]["severity"] = a.get("labels", {}).get("severity", "?")

    print(f"{'告警名':<40}{'级别':>10}{'触发次数':>10}   建议")
    print("-" * 88)
    for name, info in sorted(by_name.items(), key=lambda x: -x[1]["total"]):
        n = info["total"]
        if n > 30:
            advice = "⚠️ 触发太频繁 —— 检查阈值是否太紧"
        elif n > 10:
            advice = "观察：确认有效率"
        else:
            advice = "✅ 频率合理"
        print(f"{name[:38]:<40}{info['severity']:>10}{n:>10}   {advice}")

    print()
    print("═" * 88)
    print("下一步：人工标注有效率")
    print()
    print_alerts_template()


def print_alerts_template():
    print("""统计模板：

| 告警名 | 触发次数 | 有效次数 | 有效率 | 处理 |
| --- | --- | --- | --- | --- |
| ErrorBudgetBurnFast | | | | 保持 |
| ConnectionPoolSaturated | | | | |
| GcPauseHigh | | | | |
| ... | | | | |

判断标准：
  有效率 > 80%  → 保持（甚至可以升级级别）
  有效率 30%~80% → 检查阈值与 for 持续时间
  有效率 < 30%  → 放宽阈值、降级、或删除

调整手段（按优先级）：
  ① 提高阈值（用第 5 章的噪声底线确定）
  ② 增加 for 持续时间（避免瞬时波动触发）
  ③ 改用双窗口（长窗口 + 短窗口）
  ④ 降级（page → ticket → log）
  ⑤ 删除（如果指标与真实问题不相关）

⚠️ 核心原则：宁可不告警，也不要每天误报。
   因为告警一旦被忽略，真实故障也会被一起忽略。""")
    print("═" * 88)


if __name__ == "__main__":
    url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:9093"
    days = int(sys.argv[2]) if len(sys.argv) > 2 else 30
    main(url, days)

三、runbook 模板

每条告警都应该有一个 runbook——它决定了「值班同学能不能独立处理」。

配套代码：容量曲线与拐点

Mon, 01 Jan 0001 00:00:00 +0000

9.5 配套代码：容量曲线与拐点

对应小节：9.5 步骤四：容量曲线与拐点

一、阶梯加压脚本

// perf/k6/capacity.js
import http from 'k6/http';
import { check } from 'k6';
import { SharedArray } from 'k6/data';
import { Trend } from 'k6/metrics';

const codes = new SharedArray('codes', function () {
  return open('../data/hot-codes.txt').split('\n').filter(Boolean);
});

export const options = {
  scenarios: {
    // ── 阶梯加压：每级 2 分钟稳态 ──
    // 为什么是 2 分钟而不是 30 秒：
    //   30 秒太短，还没进入稳态（JIT 预热、缓存填充、连接池稳定）
    //   2 分钟足够让每一级都"沉淀"下来
    staircase: {
      executor: 'ramping-arrival-rate',
      startRate: 0,
      timeUnit: '1s',
      preAllocatedVUs: 500,
      maxVUs: 4000,
      stages: [
        { target: 100,  duration: '30s' },   // 升温
        { target: 100,  duration: '2m'  },   // 级 1 稳态
        { target: 300,  duration: '15s' },
        { target: 300,  duration: '2m'  },   // 级 2
        { target: 500,  duration: '15s' },
        { target: 500,  duration: '2m'  },   // 级 3
        { target: 700,  duration: '15s' },
        { target: 700,  duration: '2m'  },   // 级 4 ← 预期接近拐点
        { target: 900,  duration: '15s' },
        { target: 900,  duration: '2m'  },   // 级 5 ← 预期已过拐点
        { target: 1100, duration: '15s' },
        { target: 1100, duration: '2m'  },   // 级 6 ← 预期严重排队
        { target: 300,  duration: '30s' },   // 回落（观察恢复能力）
        { target: 300,  duration: '1m'  },
      ],
    },
  },
  // ── 关键：不设 thresholds！──
  // 容量测试是"探索性"的，设阈值会让它提前中止，拿不到完整曲线
  thresholds: {},
  discardResponseBodies: true,
};

const latency = new Trend('redirect_latency', true);

export default function () {
  const code = codes[Math.floor(Math.random() * codes.length)];
  const res = http.get(`http://localhost:8080/${code}`, {
    redirects: 0,
    tags: { name: 'redirect' },
  });
  latency.add(res.timings.duration);
}

二、采集时间线（压测与服务端指标同步）

#!/usr/bin/env bash
# tools/step4a-capacity.sh —— 跑阶梯加压 + 同步采集服务端指标
set -euo pipefail

OUT="perf/results/step4-capacity"
mkdir -p "$OUT"

echo "═══ 容量曲线测试 ═══"

# ── 后台采集服务端指标（每 2 秒一个点）──
collect() {
  : > "$OUT/timeline.csv"
  echo "ts,cpu_pct,rps,p99_ms,pool_pending,pool_active,cache_hit,gc_pause_ms_sum,threads_runnable" \
    > "$OUT/timeline.csv"
  while true; do
    ts=$(date +%s)
    m=$(curl -sf http://localhost:8080/metrics 2>/dev/null || echo "")
    [ -z "$m" ] && { sleep 2; continue; }

    cpu=$(ps -A -o %cpu,comm 2>/dev/null \
          | grep -i java | awk '{s+=$1} END{printf "%.1f", s+0}')
    rps=$(echo "$m" | grep '^http_server_requests_seconds_count' \
          | awk '{s+=$NF} END{printf "%.1f", s+0}')
    p99=$(echo "$m" | grep '^app_request_duration_seconds{.*quantile="0.99"' \
          | awk '{print $NF}')
    pend=$(echo "$m" | grep '^db_pool_pending' | awk '{print $NF}')
    act=$(echo "$m"  | grep '^db_pool_active'  | awk '{print $NF}')
    hit=$(echo "$m"  | grep '^app_cache_hit_rate' | awk '{print $NF}')
    gc=$(echo "$m"   | grep '^jvm_gc_pause_seconds_sum' | awk '{s+=$NF} END{print s+0}')
    run=$(echo "$m"  | grep '^jvm_threads_states_threads{state="runnable"' | awk '{print $NF}')

    echo "$ts,${cpu:-0},${rps:-0},${p99:-0},${pend:-0},${act:-0},${hit:-0},${gc:-0},${run:-0}" \
      >> "$OUT/timeline.csv"
    sleep 2
  done
}
collect &
COLLECT_PID=$!
trap 'kill $COLLECT_PID 2>/dev/null || true' EXIT

# ── 跑阶梯 ──
cd perf/k6
k6 run --out json="$OLDPWD/$OUT/k6.json" capacity.js 2>&1 \
  | tee "$OLDPWD/$OUT/k6.log"
cd "$OLDPWD"

kill $COLLECT_PID 2>/dev/null || true
sleep 1

echo
echo "✅ 原始数据 → $OUT/"
echo "   服务端时间线：timeline.csv"
echo "   压测明细：k6.json"
echo
echo "下一步：python3 tools/step4b-find-knee.py"

三、从曲线找拐点

#!/usr/bin/env python3
"""tools/step4b-find-knee.py —— 从容量曲线找拐点

拐点（knee）= 延迟开始非线性上升的那个吞吐点。
它【不是】最大吞吐 —— 最大吞吐是曲线的最右端（此时延迟已经不可接受）。
容量规划要的是拐点，因为拐点之后延迟增长快于容量增长。
"""
import csv
import json
import pathlib
import sys


def load_timeline(path: pathlib.Path):
    rows = []
    with path.open() as f:
        for r in csv.DictReader(f):
            r["ts"] = int(r["ts"])
            rows.append(r)
    return rows


def main(d: str) -> int:
    d = pathlib.Path(d)
    tl = load_timeline(d / "timeline.csv")

    if len(tl) < 10:
        print("❌ 时间线数据太少")
        return 1

    # ── ① 算每段的「增量延迟 / 增量吞吐」＝ 边际延迟 ──
    # 稳态下的正常响应应该是常数 → 边际延迟 ≈ 0
    # 进入饱和后，每增加 1 RPS 都会让延迟明显上升 → 边际延迟陡增
    print("═══ 边际延迟分析 ═══\n")
    print(f"{'时刻':>6s} {'CPU%':>6s} {'累计请求':>12s} {'P99(ms)':>9s} "
          f"{'池等待':>7s} {'ΔP99/ΔRPS':>11s}")

    points = []
    for r in tl:
        try:
            p99 = float(r["p99_ms"] or 0)
            rps = float(r["rps"] or 0)
        except ValueError:
            continue
        if p99 <= 0 or rps <= 0:
            continue
        points.append((r["ts"], float(r["cpu_pct"] or 0), rps, p99,
                       float(r["pool_pending"] or 0)))

    # 降采样（每 5 个点取一个），避免刷屏
    prev = None
    knees = []
    for i, (ts, cpu, rps, p99, pend) in enumerate(points):
        if prev is None:
            prev = (rps, p99)
            continue
        drps = rps - prev[0]
        dp99 = p99 - prev[1]
        ratio = dp99 / drps if abs(drps) > 100 else None   # 累计计数增量太小则跳过
        prev = (rps, p99)

        # ── 拐点判据：CPU 高 && 池有等待 && P99 明显上升 ──
        if cpu > 70 and pend > 0 and p99 > 150:
            knees.append((ts, cpu, rps, p99, pend, ratio))

        if i % 5 == 0:
            rs = f"{ratio:11.3f}" if ratio is not None else f"{'-':>11s}"
            print(f"{ts:>6d} {cpu:6.1f} {rps:12.0f} {p99:9.1f} {pend:7.0f} {rs}")

    print()
    if knees:
        first = knees[0]
        print(f"🎯 拐点（首次满足 CPU>70% & 池等待>0 & P99>150ms）：")
        print(f"   时刻 {first[0]}  CPU {first[1]:.1f}%  "
              f"累计请求 {first[2]:.0f}  P99 {first[3]:.1f}ms  "
              f"池等待 {first[4]:.0f}")
    else:
        print("⚠️  未找到明显拐点 —— 加压力度可能不够")

    # ── ② 计算「最优工作点」──
    # 定义：延迟 <= SLO 的最大吞吐
    slo = 100.0
    ok_points = [(r, p) for _, _, r, p, _ in points if p <= slo]
    if ok_points:
        best = max(ok_points, key=lambda x: x[0])
        print()
        print(f"📊 满足 SLO(P99<{slo:.0f}ms) 的最大吞吐：{best[0]:.0f} 累计请求数"
              f"（对应 P99 {best[1]:.1f}ms）")
        print(f"   → 这是【优化前】的可用容量")
    else:
        print()
        print(f"❌ 所有测点的 P99 都超过 SLO({slo:.0f}ms) —— 当前完全不可用")

    # ── ③ 饱和度时间线（找"第一块倒下的多米诺"）──
    print()
    print("═══ 饱和度时间线（第一个越界的指标）═══\n")
    thresholds = [
        ("db_pool_pending",   lambda v: v > 0,    "连接池出现等待"),
        ("cpu_pct",           lambda v: v > 80,   "CPU > 80%"),
        ("p99_ms",            lambda v: v > 100,  "P99 超过 SLO(100ms)"),
        ("gc_pause_ms_sum",   None,               "GC 停顿快速累积"),
        ("threads_runnable",  lambda v: v > 8,    "RUNNABLE 线程数接近核数"),
    ]
    firsts = {}
    for name, pred, desc in thresholds:
        for r in tl:
            try:
                v = float(r.get(name) or 0)
            except ValueError:
                continue
            if pred and pred(v):
                firsts.setdefault(desc, r["ts"])
                break

    for desc, ts in sorted(firsts.items(), key=lambda kv: kv[1]):
        print(f"  t={ts}  {desc}")

    print()
    print("判读：")
    print("  第一个越界的指标就是【第一块倒下的多米诺】")
    print("  → 优化要打【第一块】，而不是最后一根稻草")

    (d / "capacity.md").write_text(
        "# 容量曲线结论\n\n"
        f"- 拐点：{'未找到' if not knees else str(knees[0][2]) + ' 累计请求'}\n"
        f"- 满足 SLO 的最大吞吐："
        f"{'无' if not ok_points else str(round(best[0]))}\n\n"
        "## 饱和度时间线\n\n"
        + "\n".join(f"- `t={ts}` {desc}" for desc, ts in
                    sorted(firsts.items(), key=lambda kv: kv[1]))
        + "\n"
    )
    print(f"\n✅ 已写入 {d}/capacity.md")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1
                  else "perf/results/step4-capacity"))

预期输出（关键部分）：

配套代码：延迟预算的自洽性检查与超时链推导

Mon, 01 Jan 0001 00:00:00 +0000

1.5 配套代码：延迟预算的自洽性检查与超时链推导

对应小节：1.5 延迟预算两份代码解决两个问题：① 预算表加起来超了没有？② 超时设置是不是逐层递减的？

一、预算表的数据结构

// src/main/kotlin/budget/LatencyBudget.kt
package budget

/**
 * 一个预算条目。
 * @param parallelGroup 非 null 表示"同组内的条目是并行执行的"（取最大值而非相加）
 */
data class BudgetEntry(
    val name: String,
    val p99Ms: Double,
    val parallelGroup: String? = null,
    val note: String = "",
)

class LatencyBudget(
    val sloP99Ms: Double,
    val reserveMs: Double,          // 余量（必须 > 0）
    val entries: List<BudgetEntry>,
) {
    /** 串行段之和 + 每个并行组的最大值 + 余量 */
    fun totalP99Ms(): Double {
        val serial = entries.filter { it.parallelGroup == null }.sumOf { it.p99Ms }
        val parallel = entries.filter { it.parallelGroup != null }
            .groupBy { it.parallelGroup!! }
            .map { (_, group) -> group.maxOf { it.p99Ms } }
            .sum()
        return serial + parallel + reserveMs
    }

    fun validate(): List<String> {
        val problems = mutableListOf<String>()
        val total = totalP99Ms()

        if (reserveMs <= 0) {
            problems += "余量必须为正数：没有余量的预算在流量波动时必然崩（见第 0 章 0.5 节）"
        }
        if (total > sloP99Ms) {
            problems += "预算合计 %.0fms 超过 SLO %.0fms，超出 %.0fms —— 必须砍掉某一跳或放宽 SLO"
                .format(total, sloP99Ms, total - sloP99Ms)
        }
        if (entries.none { it.name.contains("排队") }) {
            problems += "警告：预算表里没有「排队」这一项。请求在队列里等待的时间也必须计入预算"
        }
        val reserveRatio = reserveMs / sloP99Ms
        if (reserveRatio in 0.0001..0.05) {
            problems += "余量只占 %.1f%%，偏少（建议 10%%~20%%）".format(reserveRatio * 100)
        }
        return problems
    }

    fun report(): String = buildString {
        appendLine("延迟预算（SLO = %.0fms，余量 = %.0fms）".format(sloP99Ms, reserveMs))
        appendLine("-".repeat(64))
        val serial = entries.filter { it.parallelGroup == null }
        val parallelGroups = entries.filter { it.parallelGroup != null }.groupBy { it.parallelGroup!! }

        serial.forEach { appendLine("  %-32s %8.1fms".format(it.name, it.p99Ms)) }
        parallelGroups.forEach { (g, list) ->
            appendLine("  [并行组 $g]")
            list.forEach { appendLine("    %-30s %8.1fms".format(it.name, it.p99Ms)) }
            appendLine("    %-30s %8.1fms  ← 并行取最大值".format("小计", list.maxOf { it.p99Ms }))
        }
        appendLine("  %-32s %8.1fms".format("余量", reserveMs))
        appendLine("-".repeat(64))
        appendLine("  %-32s %8.1fms".format("合计", totalP99Ms()))
        appendLine("  %-32s %8.1fms".format("SLO", sloP99Ms))
        appendLine()
        val problems = validate()
        if (problems.isEmpty()) {
            appendLine("✅ 校验通过")
        } else {
            problems.forEach { appendLine("❌ $it") }
        }
    }
}

fun main() {
    // ── 反例：故意算错的预算（正文里的例子） ──────────────────
    val bad = LatencyBudget(
        sloP99Ms = 200.0, reserveMs = 0.0,
        entries = listOf(
            BudgetEntry("客户端 → 网关", 25.0),
            BudgetEntry("网关处理", 15.0),
            BudgetEntry("应用排队", 20.0),
            BudgetEntry("应用逻辑", 50.0),
            BudgetEntry("PostgreSQL", 60.0),
            BudgetEntry("Redis", 5.0),
            BudgetEntry("下游 HTTP", 40.0),
            BudgetEntry("响应传输", 10.0),
        ),
    )
    println("=== 反例：忘了做加法 ===")
    println(bad.report())
    println()

    // ── 正例：压缩后并留出余量 ────────────────────────────────
    val good = LatencyBudget(
        sloP99Ms = 200.0, reserveMs = 20.0,
        entries = listOf(
            BudgetEntry("客户端 → 网关", 25.0),
            BudgetEntry("网关处理", 15.0),
            BudgetEntry("应用排队", 20.0),
            BudgetEntry("应用逻辑", 45.0),
            BudgetEntry("PostgreSQL", 40.0),
            BudgetEntry("Redis", 5.0),
            BudgetEntry("下游 HTTP", 25.0),
            BudgetEntry("响应传输", 5.0),
        ),
    )
    println("=== 正例：压缩 + 留余量 ===")
    println(good.report())
    println()

    // ── 并行调用的写法 ────────────────────────────────────────
    val withParallel = LatencyBudget(
        sloP99Ms = 200.0, reserveMs = 20.0,
        entries = listOf(
            BudgetEntry("客户端 → 网关", 25.0),
            BudgetEntry("网关处理", 15.0),
            BudgetEntry("应用排队", 20.0),
            BudgetEntry("用户服务", 60.0, parallelGroup = "fanout"),
            BudgetEntry("商品服务", 80.0, parallelGroup = "fanout"),
            BudgetEntry("库存服务", 45.0, parallelGroup = "fanout"),
        ),
    )
    println("=== 并行扇出：取最大值，不是相加 ===")
    println(withParallel.report())
    println("说明：如果按相加算 = 185ms（早就超了），实际只需 80ms（最慢的那个）。")
}

二、预期输出

=== 反例：忘了做加法 ===
延迟预算（SLO = 200ms，余量 = 0ms）
----------------------------------------------------------------
  客户端 → 网关                        25.0ms
  网关处理                             15.0ms
  应用排队                             20.0ms
  应用逻辑                             50.0ms
  PostgreSQL                          60.0ms
  Redis                                5.0ms
  下游 HTTP                           40.0ms
  响应传输                             10.0ms
  余量                                  0.0ms
----------------------------------------------------------------
  合计                                225.0ms
  SLO                                 200.0ms

❌ 预算合计 225ms 超过 SLO 200ms，超出 25ms —— 必须砍掉某一跳或放宽 SLO
❌ 余量必须为正数：没有余量的预算在流量波动时必然崩

三、超时链推导（更救命的第二份代码）

规则只有一条：本层超时必须小于上游给的时间，且逐层递减。

配套代码：排队模拟——为什么 90% 利用率已经很危险

Mon, 01 Jan 0001 00:00:00 +0000

0.5 配套代码：排队模拟——为什么 90% 利用率已经很危险

对应小节：0.5 为什么 90% 利用率已经很危险要验证的三个结论：① 排队时间的非线性爆炸 ② 平均利用率掩盖高峰 ③ 30%–50% headroom 的数学依据

一、模拟设计

我们模拟一个最简单的排队系统（M/M/1）：

一个服务台（一个 CPU 核 / 一个数据库连接）；
请求随机到达（到达间隔服从指数分布）；
处理时间随机（服务时间服从指数分布）；
先到先服务，队列无上限。

参数只有两个：利用率 ρ（服务台有多忙）和样本量。所有时间都以「一次服务时间」为单位，这样结果可以直接和正文的公式对照：

理论平均排队时间 = ρ / (1 - ρ) × 服务时间

二、代码

// src/main/kotlin/lesson00/Queueing.kt
package lesson00

import kotlin.math.ln
import kotlin.random.Random

/**
 * 模拟 M/M/1 队列，返回「平均排队等待时间 / 服务时间」的比值。
 *
 * @param rho 利用率，0 < rho < 1
 * @param arrivals 生成的请求总数（前 10% 作为预热丢弃）
 */
fun simulateMm1(rho: Double, arrivals: Int = 1_000_000, seed: Int = 42): Double {
    val rnd = Random(seed)
    val meanService = 1.0
    val meanInterArrival = meanService / rho     // 到达率越高，间隔越短

    var now = 0.0            // 当前请求的到达时刻
    var serverFreeAt = 0.0   // 服务台何时空闲
    var totalWait = 0.0
    var counted = 0
    val warmup = arrivals / 10                    // 丢弃初始瞬态

    repeat(arrivals) { i ->
        // 指数分布的到达间隔：-mean * ln(1 - U)
        now += -meanInterArrival * ln(1.0 - rnd.nextDouble())

        // 如果服务台还在忙，就要排队
        val serviceStart = maxOf(now, serverFreeAt)
        val wait = serviceStart - now

        serverFreeAt = serviceStart + (-meanService * ln(1.0 - rnd.nextDouble()))

        if (i >= warmup) { totalWait += wait; counted++ }
    }
    return totalWait / counted
}

/** 理论值：ρ / (1 - ρ) */
fun theoreticalWait(rho: Double): Double = rho / (1.0 - rho)

fun main() {
    println("=== 实验一：排队时间随利用率的变化 ===")
    println()
    println("利用率 ρ |  理论倍数 |  模拟倍数 |  服务 10ms 时平均等多久")
    println("---------|-----------|-----------|------------------------")
    for (rho in listOf(0.3, 0.5, 0.7, 0.8, 0.9, 0.95, 0.98)) {
        val measured = simulateMm1(rho, arrivals = 500_000)
        val theory = theoreticalWait(rho)
        println("%8.2f | %9.2f | %9.2f | %6.1f ms"
            .format(rho, theory, measured, theory * 10))
    }
    println()
    println("关键观察：ρ 从 0.9 涨到 0.95（只多 5 个百分点），")
    println("          等待时间从 9 倍涨到 19 倍（翻了一倍多）。")
    println()

    // ── 实验二：平均利用率是骗人的 ──────────────────────────────
    demonstrateAverageUtilizationLie()

    // ── 实验三：headroom 换算成实际意义 ─────────────────────────
    demonstrateHeadroom()
}

/**
 * 两个系统的【平均】利用率都是 70%，但一个平稳、一个忽高忽低。
 * 结果：平均一样，体验差好几倍。
 */
fun simulateBursty(rhoLow: Double, rhoHigh: Double, segment: Int = 5_000,
                   arrivals: Int = 1_000_000, seed: Int = 7): Double {
    val rnd = Random(seed)
    var currentRho = rhoHigh
    var now = 0.0
    var serverFreeAt = 0.0
    var totalWait = 0.0
    var counted = 0
    val warmup = arrivals / 10

    repeat(arrivals) { i ->
        // 每 segment 个请求切换一次"忙/闲"状态
        if (i % segment == 0) {
            currentRho = if ((i / segment) % 2 == 0) rhoHigh else rhoLow
        }
        val meanInterArrival = 1.0 / currentRho
        now += -meanInterArrival * ln(1.0 - rnd.nextDouble())

        val serviceStart = maxOf(now, serverFreeAt)
        totalWait += (serviceStart - now)
        serverFreeAt = serviceStart + (-1.0 * ln(1.0 - rnd.nextDouble()))

        if (i >= warmup) counted++
    }
    return totalWait / counted
}

fun demonstrateAverageUtilizationLie() {
    println("=== 实验二：平均利用率都是 70%，但流量形态不同 ===")
    val steady = simulateMm1(0.70, arrivals = 500_000)
    val bursty = simulateBursty(rhoLow = 0.50, rhoHigh = 0.90)

    println("平稳流量（恒定 ρ=0.70）      : 平均等待 %.2f 个服务时间".format(steady))
    println("突发流量（ρ 在 0.5/0.9 间切换）: 平均等待 %.2f 个服务时间".format(bursty))
    println("→ 平均利用率完全相同，但突发流量的等待时间高了 %.1f 倍。"
        .format(bursty / steady))
    println()
    println("结论：只看平均利用率会严重低估风险。要看利用率的高峰（P95/P99），")
    println("      或者直接盯饱和度指标（队列深度、连接池 pending）。")
    println()
}

fun demonstrateHeadroom() {
    println("=== 实验三：headroom 到底买到了什么 ===")
    println()
    println("假设服务时间是 10 ms，我们比较不同水位下的平均延迟：")
    println("目标利用率 | 平均排队 | 总延迟(P50) | 一句话")
    for (rho in listOf(0.5, 0.6, 0.7, 0.8, 0.9, 0.95)) {
        val wait = theoreticalWait(rho) * 10
        val total = wait + 10
        val comment = when {
            rho <= 0.6 -> "很宽裕，能吸收突发"
            rho <= 0.7 -> "推荐区间"
            rho <= 0.8 -> "开始吃紧"
            rho <= 0.9 -> "危险，一次 GC 停顿就可能雪崩"
            else -> "已经在排队地狱里"
        }
        println("%9.2f | %7.1fms | %10.1fms | %s".format(rho, wait, total, comment))
    }
    println()
    println("注意最后两行：从 90% 提到 95%，只是「多榨出 5% 的 CPU」，")
    println("             但用户感知的延迟几乎翻倍。")
    println()
    println("这就是「容量规划要留 30%~50% 余量」的数学依据——")
    println("它不是为了保守，而是因为排队是非线性的：低水位买到的是「吸收波动的能力」。")
}

三、预期输出

=== 实验一：排队时间随利用率的变化 ===

利用率 ρ |  理论倍数 |  模拟倍数 |  服务 10ms 时平均等多久
---------|-----------|-----------|------------------------
    0.30 |      0.43 |      0.43 |    4.3 ms
    0.50 |      1.00 |      1.00 |   10.0 ms
    0.70 |      2.33 |      2.33 |   23.3 ms
    0.80 |      4.00 |      4.00 |   40.0 ms
    0.90 |      9.00 |      8.99 |   90.0 ms
    0.95 |     19.00 |     19.02 |  190.0 ms
    0.98 |     49.00 |     48.97 |  490.0 ms

模拟值与理论值几乎完全吻合——这说明排队公式不是玄学，是数学。

配套代码：数据集生成与分布验证

Mon, 01 Jan 0001 00:00:00 +0000

5.5 配套代码：数据集生成与分布验证

对应小节：5.5 数据集设计两件事：① 生成幂律分布的数据；② 验证你的数据集是否真的符合预期分布。

一、幂律（齐夫）数据生成

// src/main/kotlin/dataset/ZipfGenerator.kt
package dataset

import kotlin.math.pow
import kotlin.random.Random

/**
 * 近似齐夫分布采样器。
 *
 * alpha 的含义：
 *   alpha = 0    → 退化为均匀分布
 *   alpha ≈ 1    → 接近真实齐夫
 *   alpha = 3    → 更集中（前 1% 承担绝大多数访问）
 *
 * 真实业务的 alpha 通常通过生产访问日志的 log-log 图斜率估算。
 */
class ZipfSampler(
    private val n: Int,
    private val alpha: Double = 1.2,
    seed: Int = 42,
) {
    private val rnd = Random(seed)

    fun next(): Int {
        val u = rnd.nextDouble()
        return (1 + (n * u.pow(alpha)).toInt()).coerceIn(1, n)
    }
}

/**
 * 让数据分布可控的生成器：可以指定「前 x% 的 key 承担 y% 的访问」。
 * 比直接用 alpha 更直观——因为业务方通常用这种方式描述热点。
 */
class HotspotSampler(
    private val totalKeys: Int,
    private val hotKeyRatio: Double = 0.01,      // 前 1% 的 key
    private val hotTrafficRatio: Double = 0.40,  // 承担 40% 的访问
    seed: Int = 42,
) {
    private val rnd = Random(seed)
    private val hotKeyCount = (totalKeys * hotKeyRatio).toInt().coerceAtLeast(1)

    fun next(): Int = if (rnd.nextDouble() < hotTrafficRatio) {
        // 热点区（前 hotKeyRatio 的 key）
        rnd.nextInt(1, hotKeyCount + 1)
    } else {
        // 长尾区（其余 key）
        rnd.nextInt(hotKeyCount + 1, totalKeys + 1)
    }
}

fun main() {
    val N = 1_000_000
    val SAMPLES = 200_000

    println("═══ 分布对比（%d 个 key，%d 次采样）═══".format(N, SAMPLES))
    println()

    for ((label, sampler) in listOf(
        "均匀分布（alpha=0）" to ZipfSampler(N, alpha = 0.0),
        "轻微集中（alpha=1.0）" to ZipfSampler(N, alpha = 1.0),
        "强热点（alpha=3.0）" to ZipfSampler(N, alpha = 3.0),
    )) {
        val counts = IntArray(10)      // 把 key 空间分成 10 段，统计各段访问占比
        repeat(SAMPLES) {
            val key = sampler.next()
            val segment = ((key - 1).toLong() * 10 / N).toInt().coerceIn(0, 9)
            counts[segment]++
        }
        println("%-22s 前10%%的key承担 %5.1f%% 的访问".format(
            label, counts[0] * 100.0 / SAMPLES))
        println("  各段分布: " + counts.joinToString(" ") { "%5.1f%%".format(it * 100.0 / SAMPLES) })
        println()
    }

    // 用 HotspotSampler 精确控制热点
    println("═══ 精确控制热点 ═══")
    val hs = HotspotSampler(totalKeys = N, hotKeyRatio = 0.01, hotTrafficRatio = 0.40)
    val hot = IntArray(1)
    val cold = IntArray(1)
    repeat(SAMPLES) {
        if (hs.next() <= N / 100) hot[0]++ else cold[0]++
    }
    println("HotspotSampler(前1%%的key, 40%%流量):")
    println("  实测：前 1%% 的 key 承担 %.1f%% 的访问（目标 40%%）".format(hot[0] * 100.0 / SAMPLES))
}

二、分布验证（Python）

# tools/verify_distribution.py <access_log.csv> [--top-pct 1]
"""
验证数据集的分布是否符合预期。

输入格式：CSV，每行一个被访问的 key（或 key 的哈希）
输出：热点集中度报告 + log-log 斜率估计（alpha）
"""
import csv
import math
import sys
from collections import Counter


def load_keys(path):
    keys = []
    with open(path) as f:
        reader = csv.reader(f)
        for row in reader:
            if row:
                keys.append(row[0].strip())
    return keys


def concentration_report(counter, top_pcts=(0.001, 0.01, 0.1)):
    total = sum(counter.values())
    distinct = len(counter)
    print(f"总访问次数 : {total:,}")
    print(f"不同 key 数 : {distinct:,}")
    print()

    print("热点集中度：")
    sorted_counts = sorted(counter.values(), reverse=True)
    for pct in top_pcts:
        k = max(1, int(distinct * pct))
        top_sum = sum(sorted_counts[:k])
        print(f"  前 {pct*100:5.1f}% 的 key 承担 {top_sum/total*100:5.1f}% 的访问"
              f"  （{k:,} 个 key）")
    print()


def estimate_alpha(counter):
    """
    用 log-log 回归估计齐夫指数 alpha。
    齐夫分布：freq(rank) ∝ rank^(-alpha)
    取对数后是直线，斜率 = -alpha
    """
    sorted_counts = sorted(counter.values(), reverse=True)
    # 取前 1000 个（尾部噪声大）
    points = [(math.log(i + 1), math.log(c)) for i, c in enumerate(sorted_counts[:1000]) if c > 0]
    if len(points) < 10:
        return None

    n = len(points)
    mx = sum(p[0] for p in points) / n
    my = sum(p[1] for p in points) / n
    num = sum((p[0] - mx) * (p[1] - my) for p in points)
    den = sum((p[0] - mx) ** 2 for p in points)
    slope = num / den if den else 0
    return -slope


def main():
    if len(sys.argv) < 2:
        print("usage: verify_distribution.py <access_log.csv> [--top-pct N]")
        sys.exit(1)

    path = sys.argv[1]
    keys = load_keys(path)
    if not keys:
        print("❌ 没有读到数据")
        return

    counter = Counter(keys)

    print("═" * 70)
    print(f"分布验证：{path}")
    print("═" * 70)
    print()

    concentration_report(counter)

    alpha = estimate_alpha(counter)
    print("齐夫指数估计：")
    if alpha:
        print(f"  alpha ≈ {alpha:.2f}")
        if alpha < 0.3:
            print("  → 接近均匀分布（不像真实业务）")
        elif alpha < 0.8:
            print("  → 轻微集中")
        elif alpha < 1.5:
            print("  → 接近真实齐夫分布 ✅")
        else:
            print("  → 高度集中（热点极强）")
    else:
        print("  样本不足，无法估计")
    print()

    print("判读要点：")
    print("  ① 前 1% 的 key 承担 30%~50% 的访问 → 接近真实业务")
    print("  ② 如果前 1% 只承担 1%~2% → 这是均匀分布，不真实")
    print("  ③ 用这个 alpha 配置你的压测脚本（不要用均匀随机）")
    print("═" * 70)


if __name__ == "__main__":
    main()

三、从生产日志提取真实分布（最推荐的做法）

# ① 从 PostgreSQL 统计真实的 ID 访问分布（如果有访问日志表）
psql -c "
SELECT user_id, count(*) AS freq
FROM request_log
WHERE created_at > now() - interval '1 day'
GROUP BY user_id
ORDER BY freq DESC
LIMIT 1000;" > docs/experiments/E0x/results/top-keys.csv

# ② 直接导出为压测脚本用的 ID 列表（含重复，保持真实频率）
psql -tAc "
SELECT user_id FROM request_log
WHERE created_at > now() - interval '1 day'
ORDER BY random()
LIMIT 100000;" > docs/experiments/E0x/results/sampled-ids.txt

# ③ 在 k6 里从这个列表里随机取（保持真实分布）
# export default function () {
#   const ids = open('./sampled-ids.txt').split('\n');
#   const id = ids[Math.floor(Math.random() * ids.length)];
#   http.get(`${__BASE_URL}/users/${id}`);
# }

这是最真实的做法：直接从生产访问日志里采样，而不是用公式模拟。

配套代码：池化类瓶颈三合一诊断

Mon, 01 Jan 0001 00:00:00 +0000

6.5 配套代码：池化类瓶颈三合一诊断

对应小节：6.5 瓶颈模式库（一）：池化类一条命令同时检查连接池 / 线程池 / 调度器三种池化瓶颈。

一、三合一诊断脚本

#!/usr/bin/env bash
# tools/diagnose-pools.sh <METRICS_URL> [PID]
#
# 同时检查三种池化瓶颈：
#   ① 连接池耗尽
#   ② 线程池饥饿
#   ③ 协程调度器污染
set -uo pipefail

URL="${1:-http://127.0.0.1:8080/metrics}"
PID="${2:-$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')}"

M=$(curl -s --max-time 5 "$URL" 2>/dev/null)
[ -z "$M" ] && { echo "❌ 无法获取指标（$URL）"; exit 1; }

get() { echo "$M" | awk -v k="^$1" '$0 ~ k {printf "%.0f", $2; exit}'; }

echo "═══════════════════════════════════════════════════════════════"
echo "池化类瓶颈诊断"
echo "═══════════════════════════════════════════════════════════════"
echo

# ── ① 连接池 ────────────────────────────────────────────────
echo "【① 数据库连接池】"
ACTIVE=$(get "db_pool_active")
IDLE=$(get "db_pool_idle")
PENDING=$(get "db_pool_pending")
TOTAL=$(get "db_pool_total")

echo "  active  = ${ACTIVE:-n/a}"
echo "  idle    = ${IDLE:-n/a}"
echo "  pending = ${PENDING:-n/a}   ← 关键指标"
echo "  total   = ${TOTAL:-n/a}"

if [ "${PENDING:-0}" -gt 0 ] 2>/dev/null; then
  echo "  ❌ 存在排队 → 连接池耗尽（模式一）"
  echo "     下一步：先查慢查询（不要先加池）"
  echo "       psql -c \"SELECT calls, mean_exec_time, total_exec_time, left(query,50)"
  echo "                FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;\""
elif [ "${ACTIVE:-0}" -ge "${TOTAL:-1}" ] 2>/dev/null && [ "${TOTAL:-0}" -gt 0 ]; then
  echo "  ⚠️  active == total（池已满但无排队）→ 没有余量，需观察"
else
  echo "  ✅ 无排队"
fi
echo

# ── ② 线程池 ────────────────────────────────────────────────
echo "【② 线程池 / 队列】"
Q_DEPTH=$(get "executor_queue_depth")
Q_REMAIN=$(get "executor_queue_remaining")
E_ACTIVE=$(get "executor_active")

echo "  active         = ${E_ACTIVE:-n/a}"
echo "  queue_depth    = ${Q_DEPTH:-n/a}   ← 关键指标"
echo "  queue_remaining= ${Q_REMAIN:-n/a}"

if [ "${Q_DEPTH:-0}" -gt 100 ] 2>/dev/null; then
  echo "  ❌ 队列积压 → 线程池饥饿（模式二）"
  echo "     下一步：查线程在忙什么（可能是在等 IO，而不是在算）"
  echo "       jcmd \$PID Thread.print | grep -c HikariPool"
  echo "       jcmd \$PID Thread.print | grep -c socketRead"
elif [ "${Q_DEPTH:-0}" -gt 0 ] 2>/dev/null; then
  echo "  ⚠️  队列有少量积压"
else
  echo "  ✅ 队列空"
fi
echo

# ── ③ 协程调度器 ────────────────────────────────────────────
echo "【③ 协程调度器】"
C_ACTIVE=$(get "app_coroutines_active")
echo "  active_coroutines = ${C_ACTIVE:-n/a（需埋点）}"

# 关键判据：RUNNABLE 线程数 vs CPU 核数
CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo "?")
echo "  CPU 核数          = $CORES"

if [ -n "$PID" ] && [ "$PID" != "" ]; then
  RUNNABLE=$(jcmd "$PID" Thread.print 2>/dev/null | grep -c "java.lang.Thread.State: RUNNABLE" || echo "?")
  echo "  RUNNABLE 线程数    = $RUNNABLE"

  CPU_PCT=$(ps -p "$PID" -o %cpu= 2>/dev/null | tr -d ' ' || echo "?")
  echo "  进程 CPU          = ${CPU_PCT}%"

  if [ "$RUNNABLE" = "$CORES" ] 2>/dev/null && [ -n "$CPU_PCT" ]; then
    if awk -v c="$CPU_PCT" 'BEGIN{exit !(c < 50)}'; then
      echo "  ❌ RUNNABLE == 核数 且 CPU < 50%"
      echo "     → 高度怀疑：Dispatchers.Default 被阻塞调用占满（模式三）"
      echo "     验证：asprof -d 60 -e wall -f wall.html $PID"
      echo "           （CPU 火焰图看不出这个问题！）"
    fi
  fi

  # 额外检查：Default worker 是否都在阻塞
  DEFAULT_BLOCKED=$(jcmd "$PID" Thread.print 2>/dev/null | \
    awk '/DefaultDispatcher-worker/{f=1} f&&/socketRead|jdbc|HikariPool|Thread.sleep/{c++} /^$/{f=0} END{print c+0}')
  [ "${DEFAULT_BLOCKED:-0}" -gt 0 ] && echo "  ⚠️  $DEFAULT_BLOCKED 个 Default worker 停在阻塞调用上"
else
  echo "  （未提供 PID，跳过线程检查）"
fi
echo

# ── 汇总 ────────────────────────────────────────────────────
echo "═══════════════════════════════════════════════════════════════"
echo "判别速查："
echo
echo "  连接池 pending > 0        → 模式一：连接池耗尽"
echo "  线程池队列持续增长         → 模式二：线程池饥饿"
echo "  RUNNABLE == 核数 且 CPU 低 → 模式三：调度器污染 ⚠️ 最难查"
echo
echo "  三种模式的共同点：CPU 不高但延迟高（时间花在排队上）"
echo "  三种模式的鉴别：看哪个池的饱和度指标异常"
echo "═══════════════════════════════════════════════════════════════"

二、调度器污染的专项验证

#!/usr/bin/env bash
# tools/verify-dispatcher-pollution.sh <PID>
#
# 专项验证"Dispatchers.Default 被阻塞调用占满"。
# 这是 Kotlin 后端最隐蔽的瓶颈，值得一个专门的脚本。
set -uo pipefail

PID="${1:?usage: verify-dispatcher-pollution.sh <pid>}"
CORES=$(nproc 2>/dev/null || echo "?")

echo "═══════════════════════════════════════════════════════════════"
echo "调度器污染验证（PID=$PID，CPU 核数=$CORES）"
echo "═══════════════════════════════════════════════════════════════"
echo

# ── 证据 1：CPU 利用率（应该很低）────────────────────────────
echo "【证据 1】进程 CPU 利用率"
CPU=$(top -b -n 1 -p "$PID" 2>/dev/null | tail -1 | awk '{print $9}' || echo "?")
echo "  CPU = ${CPU}%"
echo "  → 如果 < 40%，符合「等待类问题」的特征"
echo

# ── 证据 2：RUNNABLE 线程数 ────────────────────────────────
echo "【证据 2】线程状态统计"
TMP=$(mktemp)
jcmd "$PID" Thread.print > "$TMP" 2>/dev/null

for st in RUNNABLE BLOCKED WAITING TIMED_WAITING; do
  C=$(grep -c "java.lang.Thread.State: $st" "$TMP" || echo 0)
  printf "  %-16s %s\n" "$st" "$C"
done

RUNNABLE=$(grep -c "java.lang.Thread.State: RUNNABLE" "$TMP" || echo 0)
echo "  → RUNNABLE($RUNNABLE) 是否等于核数($CORES)？"
[ "$RUNNABLE" = "$CORES" ] && echo "     ⚠️  相等！这是调度器污染的强信号" || echo "     不相等，可能不是这个模式"
echo

# ── 证据 3：Default worker 在做什么 ────────────────────────
echo "【证据 3】DefaultDispatcher-worker 的栈顶"
awk '/^"DefaultDispatcher-worker/{name=$1; inworker=1; next}
     inworker && /java.lang.Thread.State:/{state=$0; next}
     inworker && /^\s+at /{if (!printed) {print "  " name " " state; print "      " $0; printed=1}}
     /^$/{inworker=0; printed=0}' "$TMP" | head -30
echo

# ── 证据 4：阻塞调用统计 ───────────────────────────────────
echo "【证据 4】阻塞调用计数（所有线程）"
for pat in "socketRead0" "HikariPool.getConnection" "jdbc" "Thread.sleep" "Unsafe.park"; do
  C=$(grep -c "$pat" "$TMP" || echo 0)
  [ "$C" -gt 0 ] && printf "  %-32s %s\n" "$pat" "$C"
done
echo

rm -f "$TMP"

# ── 结论引导 ────────────────────────────────────────────────
echo "═══════════════════════════════════════════════════════════════"
echo "判据组合（三条同时满足 → 基本确认）："
echo "  ① CPU 利用率低（< 40%）"
echo "  ② RUNNABLE 线程数 == CPU 核数"
echo "  ③ 这些 RUNNABLE 线程的栈停在阻塞调用上"
echo
echo "补充验证（更强）："
echo "  asprof -d 60 -e wall -f wall.html $PID"
echo "  → wall 火焰图会显示 Default worker 全停在阻塞栈"
echo
echo "修复方向："
echo "  ① 把阻塞调用切到 Dispatchers.IO"
echo "  ② 或用异步驱动（R2DBC 等）"
echo "  ③ 并用 Semaphore 限制对下游的并发"
echo "═══════════════════════════════════════════════════════════════"

三、连接池「先查什么」的决策脚本

#!/usr/bin/env bash
# tools/diagnose-pool-cause.sh <PG_CONN>
#
# pending > 0 时，判断根因是"查询慢"还是"池太小"。
set -uo pipefail

PG="${1:-${PG_CONN:-}}"
[ -z "$PG" ] && { echo "❌ 需要 PG_CONN（例如 postgresql://user:pass@host/db）"; exit 1; }

echo "═══════════════════════════════════════════════════════════════"
echo "连接池排队：根因判别"
echo "═══════════════════════════════════════════════════════════════"
echo

# ── 检查 1：是否有慢查询 ───────────────────────────────────
echo "【检查 1】最贵的语句"
psql "$PG" -tAc "
SELECT calls || ' 次 | mean ' || round(mean_exec_time::numeric,1) || 'ms'
       || ' | total ' || round(total_exec_time::numeric,0) || 'ms | '
       || left(regexp_replace(query, '\s+', ' ', 'g'), 50)
FROM pg_stat_statements
WHERE query NOT LIKE '%pg_stat_statements%'
ORDER BY total_exec_time DESC LIMIT 5;" 2>/dev/null | sed 's/^/  /' || echo "  （无法查询）"
echo

# ── 检查 2：当前活跃查询 ───────────────────────────────────
echo "【检查 2】当前活跃查询（是否有长事务）"
psql "$PG" -tAc "
SELECT pid || ' | ' || round(extract(epoch from (now()-query_start))::numeric,1) || 's | '
       || COALESCE(wait_event_type,'-') || ' | ' || left(regexp_replace(query,'\s+',' ','g'),50)
FROM pg_stat_activity
WHERE state='active' AND pid <> pg_backend_pid()
ORDER BY query_start LIMIT 10;" 2>/dev/null | sed 's/^/  /' || echo "  （无法查询）"
echo

# ── 检查 3：连接使用率 ─────────────────────────────────────
echo "【检查 3】连接使用率"
psql "$PG" -tAc "
SELECT 'used=' || count(*) || ' / max=' || current_setting('max_connections')
       || ' (' || round(100.0*count(*)/current_setting('max_connections')::int,1) || '%)'
FROM pg_stat_activity;" 2>/dev/null | sed 's/^/  /' || echo "  （无法查询）"
echo

# ── 结论引导 ────────────────────────────────────────────────
cat <<'EOF'
═══════════════════════════════════════════════════════════════
判别规则：

  检查 1 有慢查询（mean 高或 total 大）
      → 根因是【查询慢】，连接被长时间占用
      → 先优化 SQL / 加索引，不要先加池

  检查 1 查询都快，检查 3 连接使用率高
      → 根因是【并发量确实高】或【池太小】
      → 用 Little's Law 计算：所需连接 = 峰值QPS × 单次查询P99

  检查 2 有长事务（duration 很大）
      → 根因是【事务范围过大】，连接被事务持有
      → 缩小事务范围，或检查是否有忘记提交的事务

  三项都正常
      → pending 可能是瞬时的，或者问题不在数据库侧
      → 检查应用侧：是否有连接泄漏？是否有连接未归还？
═══════════════════════════════════════════════════════════════
EOF

四、动手改造

改动	观察什么
在 Lab 6 的 `/slow-db` 压测期间跑 `diagnose-pools.sh`	看它能否识别出「查询次数异常」
在 Lab 6 的 `/slow-io` 压测期间跑 `verify-dispatcher-pollution.sh`	三条判据应该同时满足
故意把连接池调到 2 并压测	`pending` 上升，`diagnose-pool-cause.sh` 会引导你查 SQL（此时 SQL 是快的，所以会指向"池太小"）
把三个脚本接进监控告警的 runbook	出问题时值班同学能直接跑
在正常运行时跑一次	建立「健康基线」的输出，便于对比

五、这段代码的局限

diagnose-pools.sh 依赖指标命名规范：如果你的指标名不同（如 hikaricp_connections_pending），需要改脚本。
「RUNNABLE == 核数」只是强信号，不是证据：也可能恰好有 8 个线程在做健康检查。必须配合 wall 火焰图确认。
diagnose-pool-cause.sh 需要 pg_stat_statements：如果没启用，检查 1 会失败。
脚本只能给方向，不能给结论：它们的价值在于「不遗漏要检查的项目」，而不是替代分析。
DebugProbes 相关的部分需要改代码：生产环境无法临时启用——所以更好的做法是提前埋一个低开销的协程数指标（第 4 节）。

配套代码：浸泡测试与泄漏判定

Mon, 01 Jan 0001 00:00:00 +0000

3.5 配套代码：浸泡测试与泄漏判定

对应小节：3.5 浸泡测试两份东西：① 浸泡压测 + 指标采样脚本；② 判定「是泄漏还是正常锯齿」的分析脚本。

一、浸泡测试脚本

// loadtest/soak.js
import http from 'k6/http';
import { check } from 'k6';

/**
 * 浸泡测试：恒定中高负载长时间运行。
 *
 * 三条关键设计：
 *   1. 负载用目标容量的 60%~80%，不要用满负载（否则排队会掩盖泄漏信号）
 *   2. 恒定到达率，不要做阶梯
 *   3. 时长至少 1 小时；覆盖一个业务周期 + 一个缓存过期周期
 */
export const options = {
  scenarios: {
    soak: {
      executor: 'constant-arrival-rate',
      rate: Number(__ENV.RATE || 400),      // = 目标容量的约 70%
      timeUnit: '1s',
      duration: __ENV.DURATION || '1h',
      preAllocatedVUs: 500,
      maxVUs: 3000,
    },
  },
  discardResponseBodies: true,
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
};

function zipf(max) {
  return Math.max(1, Math.floor(max * Math.pow(Math.random(), 3)) + 1);
}

export default function () {
  const res = http.get(`${__ENV.BASE_URL}/orders/${zipf(1_000_000)}`, {
    tags: { name: 'GET /orders/{id}' },
  });
  check(res, { ok: (r) => r.status === 200 });
}

#!/usr/bin/env bash
# tools/run-soak.sh <EXP_ID> [duration]
set -euo pipefail

EXP_ID="${1:?usage: run-soak.sh <EXP_ID> [duration]}"
DURATION="${2:-1h}"
DIR="docs/experiments/${EXP_ID}"
mkdir -p "$DIR/results"

# ① 环境元数据（第 1 章 1.7 节）
tools/collect-env.sh "$EXP_ID"

# ② 指标采样：每 30 秒记录一次资源与延迟（浸泡的价值全在趋势）
echo "开始采样资源指标（每 30 秒一个点）..."
(
  echo "timestamp,heap_used_mb,heap_max_mb,gc_count,gc_time_ms,pool_active,pool_idle,pool_pending,pool_total,threads,fd_count,p99_ms"
  while true; do
    TS=$(date +%s)
    M=$(curl -s --max-time 5 http://127.0.0.1:8080/metrics 2>/dev/null || echo "")
    HEAP_USED=$(echo "$M" | awk '/jvm_memory_used_bytes.*heap/{printf "%.0f", $2/1048576; exit}')
    HEAP_MAX=$(echo "$M"  | awk '/jvm_memory_max_bytes.*heap/{printf "%.0f", $2/1048576; exit}')
    GC_COUNT=$(echo "$M" | awk '/jvm_gc_pause_seconds_count/{s+=$2} END{printf "%.0f", s}')
    GC_TIME=$(echo "$M"  | awk '/jvm_gc_pause_seconds_sum/{s+=$2} END{printf "%.0f", s*1000}')
    P_ACT=$(echo "$M" | awk '/db_pool_active/{printf "%.0f", $2; exit}')
    P_IDLE=$(echo "$M" | awk '/db_pool_idle/{printf "%.0f", $2; exit}')
    P_PEND=$(echo "$M" | awk '/db_pool_pending/{printf "%.0f", $2; exit}')
    P_TOT=$(echo "$M" | awk '/db_pool_total/{printf "%.0f", $2; exit}')
    THREADS=$(echo "$M" | awk '/jvm_threads_live_threads/{printf "%.0f", $2; exit}')
    FD=$(ls /proc/$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')/fd 2>/dev/null | wc -l | tr -d ' ')
    P99=$(echo "$M" | awk '/app_request_duration_seconds/{v=$2} END{printf "%.0f", v*1000}')
    echo "$TS,$HEAP_USED,$HEAP_MAX,$GC_COUNT,$GC_TIME,$P_ACT,$P_IDLE,$P_PEND,$P_TOT,$THREADS,$FD,$P99"
    sleep 30
  done
) > "$DIR/results/soak-metrics.csv" &
MONITOR_PID=$!

# ③ 压测
BASE_URL=http://127.0.0.1:8080 \
k6 run --out json="$DIR/results/k6-soak-raw.json" \
       --summary-export="$DIR/results/k6-soak-summary.json" \
       loadtest/soak.js

kill "$MONITOR_PID" 2>/dev/null || true
echo "✅ 浸泡完成 → $DIR/results/soak-metrics.csv"

FD 那一行的 /proc/<pid>/fd 只适用于 Linux。macOS 上可以改用 lsof -p <pid> | wc -l。

配套代码：系统级观测命令与快照脚本

Mon, 01 Jan 0001 00:00:00 +0000

4.5 配套代码：系统级观测命令与快照脚本

对应小节：4.5 系统级观测一条命令采集完整的系统快照——比逐个敲命令更不容易漏项。

一、一键系统快照脚本

#!/usr/bin/env bash
# tools/system-snapshot.sh <OUTPUT_FILE> [PID]
#
# 采集完整的系统级快照。适合在压测进行中或故障排查时运行。
set -uo pipefail

OUT="${1:?usage: system-snapshot.sh <output_file> [pid]}"
PID="${2:-}"
mkdir -p "$(dirname "$OUT")"

{
  echo "═══ 系统快照 $(date -Iseconds) ═══"
  echo

  # ── CPU 总体与五段分解 ─────────────────────────────────
  echo "───── CPU 总体（重点看 sy / wa / st）─────"
  if command -v mpstat > /dev/null 2>&1; then
    mpstat 1 3 | tail -4
  else
    top -b -n 1 | head -5
  fi
  echo

  echo "───── CPU 频率（是否降频）─────"
  if [ -f /proc/cpuinfo ]; then
    grep -m4 "MHz" /proc/cpuinfo
    echo "governor: $(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo n/a)"
  else
    echo "（非 Linux，跳过）"
  fi
  echo

  # ── 上下文切换 ────────────────────────────────────────
  echo "───── 上下文切换（cswch=自愿/锁竞争, nvcswch=被抢占/线程过多）─────"
  if [ -n "$PID" ]; then
    pidstat -w -p "$PID" 1 3 2>/dev/null | tail -4
  else
    echo "（未指定 PID，显示系统级）"
  fi
  vmstat 1 3 | tail -3
  echo

  # ── 进程级 CPU ────────────────────────────────────────
  if [ -n "$PID" ]; then
    echo "───── 进程 CPU（PID=$PID）─────"
    pidstat -u -p "$PID" 1 3 2>/dev/null | tail -4
    echo
  fi

  # ── 内存 ──────────────────────────────────────────────
  echo "───── 内存 ─────"
  free -h 2>/dev/null || vm_stat 2>/dev/null | head -6
  echo

  # ── 磁盘 IO（看 await，不是 %util）────────────────────
  echo "───── 磁盘 IO（关键：await）─────"
  if command -v iostat > /dev/null 2>&1; then
    iostat -x 1 2 | grep -E "Device|^sd|^nvme|^dm-" | head -10
  else
    echo "（iostat 不可用，请安装 sysstat）"
  fi
  echo

  # ── 网络 ──────────────────────────────────────────────
  echo "───── 网络连接状态 ─────"
  if command -v ss > /dev/null 2>&1; then
    ss -s
    echo
    echo "连接状态分布："
    ss -tan | awk 'NR>1 {print $1}' | sort | uniq -c | sort -rn | head -8
    echo
    echo "TIME_WAIT 数量: $(ss -tan | grep -c TIME-WAIT || echo 0)"
  fi
  echo

  echo "───── 网络重传与错误 ─────"
  if [ -f /proc/net/snmp ]; then
    grep -A1 "^Tcp:" /proc/net/snmp | tail -1 | awk '{
      printf "重传段数=%s  错误段数=%s\n", $13, $14
    }' 2>/dev/null || echo "（解析失败，请手工查看 /proc/net/snmp）"
  else
    netstat -s 2>/dev/null | grep -E "retransmit|error|drop" | head -5
  fi
  echo

  # ── 容器限制 ──────────────────────────────────────────
  echo "───── 容器资源限制 ⭐ ─────"
  if [ -f /sys/fs/cgroup/cpu.max ]; then
    echo "cpu.max: $(cat /sys/fs/cgroup/cpu.max)"
    echo "--- cpu.stat（重点看 nr_throttled）---"
    head -5 /sys/fs/cgroup/cpu.stat
    # 计算节流比例
    awk '/nr_periods/{p=$2} /nr_throttled/{t=$2} END{
      if (p>0) printf "节流比例: %.1f%%%s\n", 100*t/p, (t/p>0.25 ? "  ⚠️ 严重" : "")
    }' /sys/fs/cgroup/cpu.stat
  elif [ -f /sys/fs/cgroup/cpu/cpu.cfs_quota_us ]; then
    echo "cgroup v1:"
    echo "  quota: $(cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us)"
    echo "  period: $(cat /sys/fs/cgroup/cpu/cpu.cfs_period_us)"
  else
    echo "（非容器环境或 cgroup 不可见）"
  fi
  echo "memory.max: $(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo n/a)"
  echo

  # ── 文件描述符 ────────────────────────────────────────
  echo "───── 文件描述符 ─────"
  echo "ulimit -n: $(ulimit -n)"
  if [ -n "$PID" ] && [ -d "/proc/$PID/fd" ]; then
    echo "当前进程 FD 数: $(ls /proc/"$PID"/fd | wc -l)"
  fi
  echo

  # ── NUMA 与超线程 ─────────────────────────────────────
  echo "───── 硬件拓扑 ─────"
  if command -v lscpu > /dev/null 2>&1; then
    lscpu | grep -E "^CPU\(s\)|Thread|Core|Socket|NUMA|Model name"
  fi

} > "$OUT" 2>&1

echo "✅ 系统快照 → $OUT"
echo
echo "快速判读入口："
echo "  grep -A3 'CPU 总体' '$OUT'        # 看 sy / st 是否偏高"
echo "  grep -A2 '上下文切换' '$OUT'      # 看切换次数"
echo "  grep -A3 '容器资源限制' '$OUT'    # 看节流比例"
echo "  grep -A2 '磁盘 IO' '$OUT'         # 看 await"

二、关键指标的判读标准

指标	正常范围	偏高意味着	下一步
`us`	视业务	应用真在算	采 CPU 火焰图
`sy`	< 15%	系统调用/锁竞争/页错误	采火焰图看内核栈；查锁
`wa`	< 5%	等磁盘	看 `iostat -x` 的 await
`st`	< 1%	被邻居抢 CPU	换环境，优化代码无效
`cswch/s`	几千–几万	锁竞争或 IO 等待	线程快照 + lock 火焰图
`nvcswch/s`	几百–几千	线程数远超核数	减少线程/改协程
`iostat await`	< 10 ms	磁盘慢或 IO 密集	看具体设备与卷类型
`TIME_WAIT`	< 2 万	连接复用不足	开启 keep-alive
节流比例	< 1%	CPU limit 太小	见第 4.8 节

三个最容易被忽略的（加粗项）：sy 高、st 高、nvcswch/s 高。

配套代码：韧性客户端与超时审计

Mon, 01 Jan 0001 00:00:00 +0000

7.5 配套代码：韧性客户端与超时审计

对应小节：7.5 背压与韧性三部分：① 完整的韧性客户端；② 超时预算审计；③ 受限重试的实现。

一、完整的韧性客户端

// src/main/kotlin/resilience/ResilientClient.kt
package resilience

import io.micrometer.core.instrument.Counter
import io.micrometer.core.instrument.MeterRegistry
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.delay
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit
import kotlinx.coroutines.withTimeout
import java.util.concurrent.atomic.AtomicInteger
import java.util.concurrent.atomic.AtomicLong
import kotlin.math.min
import kotlin.random.Random

/**
 * 五种韧性手段的组合实现：
 *   ① 限流（RateLimiter）—— 防止自己被打垮
 *   ② 熔断（CircuitBreaker）—— 防止被下游拖垮
 *   ③ 隔板（Semaphore）—— 防止一个依赖拖垮全部
 *   ④ 超时（withTimeout）—— 及时放弃，释放资源
 *   ⑤ 重试（带退避与上限）—— 应对偶发失败
 */
class ResilientClient(
    private val name: String,
    private val call: suspend (String) -> String,

    // ① 限流：每秒最多 N 个请求
    private val maxQps: Int = 1000,

    // ③ 隔板：最多 N 个并发
    private val maxConcurrent: Int = 32,

    // ④ 超时：单次调用的超时
    private val timeoutMs: Long = 100,

    // ⑤ 重试
    private val maxAttempts: Int = 3,
    private val initialBackoffMs: Long = 50,

    // ② 熔断
    private val failureThreshold: Double = 0.5,   // 错误率阈值
    private val minRequestsForCircuit: Int = 20,  // 样本不足不触发
    private val openDurationMs: Long = 20_000,    // 打开时长
    private val halfOpenProbes: Int = 3,          // 半开探测数

    registry: MeterRegistry,
) {
    // ── 限流（令牌桶的简化实现）──────────────────────────────
    private val tokens = AtomicInteger(maxQps)
    private val lastRefill = AtomicLong(System.currentTimeMillis())

    // ── 隔板 ────────────────────────────────────────────────
    private val semaphore = Semaphore(maxConcurrent)

    // ── 熔断状态 ────────────────────────────────────────────
    private enum class State { CLOSED, OPEN, HALF_OPEN }
    @Volatile private var circuitState = State.CLOSED
    @Volatile private var openedAt = 0L
    private val totalRequests = AtomicLong(0)
    private val failedRequests = AtomicLong(0)
    private val halfOpenSuccess = AtomicInteger(0)

    // ── 指标 ────────────────────────────────────────────────
    private val callsTotal = Counter.builder("client.calls.total").tag("downstream", name).register(registry)
    private val callsFailed = Counter.builder("client.calls.failed").tag("downstream", name).register(registry)
    private val callsRejected = Counter.builder("client.calls.rejected").tag("downstream", name).register(registry)
    private val callsTimedOut = Counter.builder("client.calls.timeout").tag("downstream", name).register(registry)
    private val callsRetried = Counter.builder("client.calls.retried").tag("downstream", name).register(registry)
    private val circuitOpened = Counter.builder("client.circuit.opened").tag("downstream", name).register(registry)

    private fun tryAcquireToken(): Boolean {
        val now = System.currentTimeMillis()
        val elapsed = now - lastRefill.get()
        if (elapsed >= 1000) {                          // 每秒补充
            tokens.set(maxQps)
            lastRefill.set(now)
        }
        return tokens.getAndUpdate { if (it > 0) it - 1 else 0 } > 0
    }

    suspend fun fetch(id: String): Result<String> {
        // ① 限流
        if (!tryAcquireToken()) {
            callsRejected.increment()
            return Result.failure(RejectedException("$name 超过速率限制"))
        }

        // ② 熔断检查
        if (isCircuitOpen()) {
            callsRejected.increment()
            return Result.failure(CircuitOpenException("$name 熔断中"))
        }

        callsTotal.increment()

        return try {
            val value = withRetry {
                // ③ 隔板 + ④ 超时
                semaphore.withPermit {
                    withTimeout(timeoutMs) { call(id) }
                }
            }
            recordSuccess()
            Result.success(value)
        } catch (e: TimeoutCancellationException) {
            callsTimedOut.increment()
            recordFailure()
            Result.failure(TimeoutException("$name 超时（${timeoutMs}ms）", e))
        } catch (e: Exception) {
            callsFailed.increment()
            recordFailure()
            Result.failure(e)
        }
    }

    /** ⑤ 重试：指数退避 + 抖动 + 次数上限 */
    private suspend fun <T> withRetry(block: suspend () -> T): T {
        var lastError: Throwable? = null
        repeat(maxAttempts) { attempt ->
            try {
                return block()
            } catch (e: TimeoutCancellationException) {
                lastError = e
                if (attempt < maxAttempts - 1) {
                    callsRetried.increment()
                    val base = min(initialBackoffMs shl attempt, 2_000)
                    delay(base + Random.nextLong(0, base / 2))       // 抖动：避免惊群
                }
            } catch (e: NonRetryableException) {
                throw e                                                  // 不重试不可重试的异常
            } catch (e: Exception) {
                lastError = e
                if (attempt < maxAttempts - 1) {
                    callsRetried.increment()
                    val base = min(initialBackoffMs shl attempt, 2_000)
                    delay(base + Random.nextLong(0, base / 2))
                }
            }
        }
        throw lastError ?: IllegalStateException("unreachable")
    }

    // ── 熔断状态机 ──────────────────────────────────────────
    private fun isCircuitOpen(): Boolean = when (circuitState) {
        State.CLOSED -> false
        State.OPEN -> {
            if (System.currentTimeMillis() - openedAt > openDurationMs) {
                circuitState = State.HALF_OPEN
                halfOpenSuccess.set(0)
                false
            } else true
        }
        State.HALF_OPEN -> false
    }

    private fun recordSuccess() {
        if (circuitState == State.HALF_OPEN) {
            if (halfOpenSuccess.incrementAndGet() >= halfOpenProbes) {
                circuitState = State.CLOSED
                totalRequests.set(0)
                failedRequests.set(0)
            }
        } else {
            totalRequests.incrementAndGet()
        }
    }

    private fun recordFailure() {
        if (circuitState == State.HALF_OPEN) {
            circuitState = State.OPEN
            openedAt = System.currentTimeMillis()
            circuitOpened.increment()
            return
        }
        val total = totalRequests.incrementAndGet()
        val failed = failedRequests.incrementAndGet()
        if (total >= minRequestsForCircuit && failed.toDouble() / total > failureThreshold) {
            circuitState = State.OPEN
            openedAt = System.currentTimeMillis()
            circuitOpened.increment()
        }
    }
}

class RejectedException(message: String) : RuntimeException(message)
class CircuitOpenException(message: String) : RuntimeException(message)
class TimeoutException(message: String, cause: Throwable?) : RuntimeException(message, cause)
class NonRetryableException(message: String) : RuntimeException(message)

二、超时预算审计

// src/main/kotlin/resilience/TimeoutAudit.kt
package resilience

/**
 * 超时链审计：找出「本层超时 > 上游给的预算」的配置。
 *
 * 这是决定「系统崩溃后能否自愈」的关键（第 3 章 3.6 节）：
 *   如果应用给数据库的超时（30s）远大于网关给应用的超时（1s），
 *   那么网关超时返回后，应用线程仍然被占住 30 秒 → 连接池持续满 → 无法自愈。
 */
data class TimeoutLayer(
    val name: String,
    val upstreamBudgetMs: Long,     // 上游给这一层的时间
    val selfTimeoutMs: Long,        // 这一层设置的超时
    val note: String = "",
)

data class AuditResult(
    val problems: List<String>,
    val warnings: List<String>,
    val chain: List<Pair<String, Long>>,    // (层名, 留给下游的时间)
)

fun auditTimeouts(layers: List<TimeoutLayer>): AuditResult {
    val problems = mutableListOf<String>()
    val warnings = mutableListOf<String>()
    val chain = mutableListOf<Pair<String, Long>>()

    var remainingBudget = layers.firstOrNull()?.upstreamBudgetMs ?: Long.MAX_VALUE

    layers.forEach { layer ->
        // ① 本层超时不应超过上游给的预算
        if (layer.selfTimeoutMs > layer.upstreamBudgetMs) {
            problems += buildString {
                append("❌ ${layer.name}: 本层超时 ${layer.selfTimeoutMs}ms > 上游预算 ${layer.upstreamBudgetMs}ms")
                append("\n     后果：上游已超时返回，本层的调用仍在继续，资源被占住 → 可能无法自愈")
                if (layer.note.isNotEmpty()) append("\n     备注：${layer.note}")
            }
        }

        // ② 上游预算不应超过更上游给的预算（逐层递减）
        if (layer.upstreamBudgetMs > remainingBudget) {
            problems += "❌ ${layer.name}: 上游给了 ${layer.upstreamBudgetMs}ms，" +
                        "但更上游只剩 ${remainingBudget}ms（超时链未递减）"
        }

        // ③ 检查余量是否合理
        val margin = layer.upstreamBudgetMs - layer.selfTimeoutMs
        if (margin in 1..5) {
            warnings += "⚠️  ${layer.name}: 余量只有 ${margin}ms，可能不足以处理上游的开销"
        }
        if (layer.selfTimeoutMs <= 0) {
            problems += "❌ ${layer.name}: 超时为 ${layer.selfTimeoutMs}ms（无效值）"
        }

        remainingBudget = layer.selfTimeoutMs
        chain += layer.name to layer.selfTimeoutMs
    }

    // ④ 检查是否所有层都配置了超时
    if (layers.any { it.selfTimeoutMs <= 0 }) {
        warnings += "⚠️  存在未配置超时的层（默认超时可能非常长，如 30 秒）"
    }

    return AuditResult(problems, warnings, chain)
}

fun main() {
    println("═══ 反例：会导致无法自愈的配置 ═══")
    println()
    val bad = auditTimeouts(listOf(
        TimeoutLayer("客户端 → 网关", upstreamBudgetMs = 5_000, selfTimeoutMs = 3_000),
        TimeoutLayer("网关 → 应用", upstreamBudgetMs = 3_000, selfTimeoutMs = 1_000),
        TimeoutLayer("应用 → 数据库", upstreamBudgetMs = 30_000, selfTimeoutMs = 30_000,
            note = "默认值，没人改过 —— 这是最常见的坑"),
        TimeoutLayer("应用 → Redis", upstreamBudgetMs = 30_000, selfTimeoutMs = 5_000),
    ))
    bad.problems.forEach { println(it); println() }
    bad.warnings.forEach { println(it) }
    println()
    println("超时链：")
    bad.chain.forEachIndexed { i, (name, ms) ->
        println("  ${"  ".repeat(i)}└─ $name: ${ms}ms")
    }

    println()
    println("═".repeat(70))
    println()
    println("═══ 正例：逐层递减，可自愈 ═══")
    println()
    val good = auditTimeouts(listOf(
        TimeoutLayer("客户端 → 网关", upstreamBudgetMs = 5_000, selfTimeoutMs = 500),
        TimeoutLayer("网关 → 应用", upstreamBudgetMs = 500, selfTimeoutMs = 300),
        TimeoutLayer("应用 → 数据库", upstreamBudgetMs = 300, selfTimeoutMs = 60),
        TimeoutLayer("应用 → Redis", upstreamBudgetMs = 300, selfTimeoutMs = 10),
        TimeoutLayer("应用 → 下游", upstreamBudgetMs = 300, selfTimeoutMs = 100),
    ))
    if (good.problems.isEmpty()) {
        println("✅ 超时链自洽，逐层递减")
    } else {
        good.problems.forEach { println(it) }
    }
    good.warnings.forEach { println(it) }
    println()
    println("超时链：")
    good.chain.forEachIndexed { i, (name, ms) ->
        println("  ${"  ".repeat(i)}└─ $name: ${ms}ms")
    }

    println()
    println("核心规则：本层超时必须小于上游预算，且逐层递减。")
    println("超时不是「容忍时间」，而是「放弃的时机」—— 放弃得早，系统才能自愈。")
}

预期输出（反例部分）：

配套代码：剖析定位与假设台账

Mon, 01 Jan 0001 00:00:00 +0000

9.6 配套代码：剖析定位与假设台账

对应小节：9.6 步骤五：剖析定位

一、在拐点处取证（五步法的前四步）

#!/usr/bin/env bash
# tools/step5a-collect-at-knee.sh
#
# ═══ 关键纪律 ═══
# 取证必须在【拐点负载下】做，不能停压测再取。
# 因为：停压测后线程池空了、GC 停了、锁不争了 ——
#       你看到的是一个"没有压力的系统"，什么都看不出来。
set -euo pipefail

OUT="perf/results/step5-diagnose"
mkdir -p "$OUT"

PID="${APP_PID:?请设置 APP_PID（服务进程号）}"
KNEE_RPS="${KNEE_RPS:-600}"       # 步骤四测出的拐点

echo "═══ 在拐点负载（${KNEE_RPS} RPS）下取证 ═══"
echo

# ── 0. 先把压测跑起来，并保持压力 ──
cat > /tmp/knee-load.js <<JS
import http from 'k6/http';
import { SharedArray } from 'k6/data';
export const options = {
  scenarios: { knee: {
    executor: 'constant-arrival-rate',
    rate: ${KNEE_RPS}, timeUnit: '1s',
    duration: '3m', preAllocatedVUs: 500, maxVUs: 2000,
  }},
  thresholds: {},
};
const codes = new SharedArray('codes', () =>
  open('/tmp/hot-codes-copy.txt').split('\n').filter(Boolean));
export default function () {
  const c = codes[Math.floor(Math.random() * codes.length)];
  http.get(\`http://localhost:8080/\${c}\`, { redirects: 0 });
}
JS
cp perf/data/hot-codes.txt /tmp/hot-codes-copy.txt
(cd perf/k6 && k6 run --quiet /tmp/knee-load.js > "$OLDPWD/$OUT/k6-knee.log" 2>&1) &
LOAD_PID=$!
echo "压测已启动（PID $LOAD_PID），等待 40s 让它进入稳态..."
sleep 40

# ══════════════════════════════════════════════
# 第 1 步：看「整体形态」—— 哪一层慢？
# ══════════════════════════════════════════════
echo
echo "① 四层指标快照"
curl -sf http://localhost:8080/metrics > "$OUT/metrics-knee.txt"

python3 - "$OUT/metrics-knee.txt" <<'PY'
import re, sys, pathlib

txt = pathlib.Path(sys.argv[1]).read_text()

def g(pat, default=0.0):
    m = re.search(pat, txt, re.M)
    return float(m.group(1)) if m else default

# ── 计算「时间都花在哪」──
e2e_sum = g(r'^app_request_duration_seconds_sum\s+([\d.eE+-]+)')
dep_sum = g(r'^app_db_query_seconds_sum\s+([\d.eE+-]+)')
req_cnt = g(r'^app_request_duration_seconds_count\s+([\d.eE+-]+)')
dep_cnt = g(r'^app_db_query_seconds_count\s+([\d.eE+-]+)')

print(f"  请求数              {req_cnt:,.0f}")
print(f"  端到端总耗时        {e2e_sum*1000:,.0f} ms")
print(f"  依赖（DB）总耗时    {dep_sum*1000:,.0f} ms")
if e2e_sum > 0:
    print(f"  依赖占比            {dep_sum/e2e_sum*100:.1f}%  "
          f"{'← 瓶颈在依赖层' if dep_sum/e2e_sum > 0.6 else ''}")
if req_cnt > 0:
    print(f"  平均端到端          {e2e_sum/req_cnt*1000:,.1f} ms")
print()

# ── 饱和度信号 ──
pend = g(r'^db_pool_pending\s+([\d.eE+-]+)')
act  = g(r'^db_pool_active\s+([\d.eE+-]+)')
tot  = g(r'^db_pool_total\s+([\d.eE+-]+)')
run  = g(r'^jvm_threads_states_threads\{state="runnable"\}\s+([\d.eE+-]+)')
cpu  = g(r'^process_cpu_usage\s+([\d.eE+-]+)')

print("  饱和度信号：")
print(f"    连接池 等待/活跃/总数  {pend:.0f} / {act:.0f} / {tot:.0f}")
print(f"    RUNNABLE 线程数        {run:.0f}")
print(f"    进程 CPU               {cpu*100:.1f}%")
print()
print("  判读：")
if pend > 0 and act >= tot:
    print("    ⚠️  池已满且有等待 —— 但【不要马上加池】")
    print("        先回答：为什么每个请求占用连接这么久？")
    print("        如果根因是慢查询，加池只是让更多慢查询并发去抢 DB")
if run > 0:
    import os
    ncpu = os.cpu_count() or 8
    if abs(run - ncpu) <= 1:
        print(f"    ⚠️  RUNNABLE ≈ 核数({ncpu}) —— 调度器污染的典型信号")
        print("        说明 Default 调度器被阻塞调用占满（埋雷 ④）")
PY

# ══════════════════════════════════════════════
# 第 2 步：wall-clock 火焰图（找「时间花在哪」）
# ══════════════════════════════════════════════
echo
echo "② wall-clock 火焰图（30s）"
asprof -d 30 -e wall -t -o collapsed -f "$OUT/flame-wall.collapsed" "$PID"
echo "   ✅ $OUT/flame-wall.collapsed"
echo "   用 https://www.speedscope.app 打开，或："
echo "   asprof -o flamegraph.html -f $OUT/flame-wall.html ..."

# ══════════════════════════════════════════════
# 第 3 步：CPU 火焰图（对照：如果 wall 有内容但 cpu 很空 → 是等待）
# ══════════════════════════════════════════════
echo
echo "③ CPU 火焰图（30s）"
asprof -d 30 -e cpu -t -o collapsed -f "$OUT/flame-cpu.collapsed" "$PID"
echo "   ✅ $OUT/flame-cpu.collapsed"

# ══════════════════════════════════════════════
# 第 4 步：分类火焰图（锁 / 分配 / IO）
# ══════════════════════════════════════════════
echo
echo "④ 分类火焰图"
for ev in lock alloc; do
  echo "   - $ev"
  asprof -d 20 -e "$ev" -t -o collapsed -f "$OUT/flame-$ev.collapsed" "$PID" \
    2>/dev/null && echo "     ✅ flame-$ev.collapsed" \
    || echo "     ⚠️  $ev 事件不可用（需要 -XX:+UnlockDiagnosticVMOptions）"
done

# ══════════════════════════════════════════════
# 第 5 步：线程 / 协程快照
# ══════════════════════════════════════════════
echo
echo "⑤ 线程快照"
jcmd "$PID" Thread.dump_to_file -format=json "$OUT/threads.json" 2>/dev/null \
  && echo "   ✅ threads.json" \
  || { jstack "$PID" > "$OUT/threads.txt"; echo "   ✅ threads.txt"; }

echo
echo "⑥ JFR 采样（60s，含 FileWrite / SocketRead 事件）"
jcmd "$PID" JFR.start name=diag settings=profile duration=60s \
  filename="$OUT/diag.jfr" 2>/dev/null \
  && echo "   ✅ diag.jfr（60s 后完成，可稍后分析）" \
  || echo "   ⚠️  JFR 启动失败"

# ── 数据库侧取证（与 JVM 侧同时进行）──
echo
echo "⑦ 数据库侧"
{
  echo "## pg_stat_statements 慢查询 TOP 10"
  psql "$PG_CONN" -c "
    SELECT round(total_exec_time::numeric,1) AS total_ms,
           calls,
           round(mean_exec_time::numeric,2)  AS mean_ms,
           round((100*total_exec_time/sum(total_exec_time) OVER ())::numeric,1) AS pct,
           left(query, 70) AS query
    FROM pg_stat_statements
    ORDER BY total_exec_time DESC LIMIT 10;" 2>/dev/null \
    || echo "（需要 CREATE EXTENSION pg_stat_statements）"
  echo
  echo "## 当前等待事件"
  psql "$PG_CONN" -c "
    SELECT wait_event_type, wait_event, count(*)
    FROM pg_stat_activity
    WHERE state <> 'idle'
    GROUP BY 1,2 ORDER BY 3 DESC;" 2>/dev/null
  echo
  echo "## 表大小"
  psql "$PG_CONN" -c "
    SELECT pg_size_pretty(pg_total_relation_size('links')) AS total_size;" 2>/dev/null
} > "$OUT/db-snapshot.md"
echo "   ✅ db-snapshot.md"

# ── 收尾：停压测 ──
echo
echo "取证完成，停止压测..."
kill $LOAD_PID 2>/dev/null || true
wait $LOAD_PID 2>/dev/null || true

echo
echo "═══ 取证完成 ═══"
echo "产出物 → $OUT/"
ls -1 "$OUT/" | sed 's/^/  /'
echo
echo "下一步：python3 tools/step5b-analyze-flame.py"

二、火焰图的自动初筛

#!/usr/bin/env python3
"""tools/step5b-analyze-flame.py —— 从 collapsed 火焰图提取热点

collapsed 格式：a;b;c 123   （分号分隔的调用栈 + 采样数）
"""
import pathlib
import sys
from collections import defaultdict


def load(path: pathlib.Path):
    stacks = []
    total = 0
    for line in path.read_text().splitlines():
        line = line.strip()
        if not line:
            continue
        parts = line.rsplit(" ", 1)
        if len(parts) != 2:
            continue
        stack, cnt = parts
        try:
            cnt = int(cnt)
        except ValueError:
            continue
        stacks.append((stack.split(";"), cnt))
        total += cnt
    return stacks, total


def main(d: str) -> int:
    d = pathlib.Path(d)

    for name, desc in [
        ("flame-wall.collapsed", "wall（墙钟：时间到底花在哪）"),
        ("flame-cpu.collapsed", "cpu（CPU：真正在算什么）"),
        ("flame-lock.collapsed", "lock（锁：在等什么锁）"),
        ("flame-alloc.collapsed", "alloc（分配：谁在造垃圾）"),
    ]:
        p = d / name
        if not p.exists():
            continue

        stacks, total = load(p)
        if total == 0:
            print(f"⚠️  {name} 为空 —— {desc}")
            print(f"    空就有意义：说明这类事件在采样窗口内没发生")
            print()
            continue

        print(f"═══ {desc} ═══")
        print(f"总采样 {total:,}")
        print()

        # ── 顶层帧聚合（谁是最外层的等待者）──
        by_top = defaultdict(int)
        for stack, cnt in stacks:
            if stack:
                by_top[stack[0]] += cnt
        print("  最外层帧 TOP 5：")
        for frame, cnt in sorted(by_top.items(), key=lambda kv: -kv[1])[:5]:
            print(f"    {cnt/total*100:6.1f}%  {frame}")
        print()

        # ── 叶子帧聚合（真正在执行的代码）──
        by_leaf = defaultdict(int)
        for stack, cnt in stacks:
            if stack:
                by_leaf[stack[-1]] += cnt
        print("  叶子帧 TOP 10（真正的热点）：")
        for frame, cnt in sorted(by_leaf.items(), key=lambda kv: -kv[1])[:10]:
            print(f"    {cnt/total*100:6.1f}%  {frame[:110]}")
        print()

        # ── 关键类别的出现频率 ──
        cats = {
            "JDBC / PG 驱动": ("org.postgresql", "java.sql", "PgConnection"),
            "socket 读等待": ("SocketRead", "socketRead", "read0", "epollWait"),
            "文件写入（日志）": ("FileOutputStream", "FileChannel", "Log4j", "Logback"),
            "锁竞争": ("ReentrantLock", "synchronized", "Unsafe.park", "AQS"),
            "缓存 / Caffeine": ("caffeine", "BoundedLocalCache"),
            "协程调度": ("Dispatchers", "CoroutineScheduler", "runBlocking"),
            "GC / 分配": ("G1", "gc", "allocate", "TLAB"),
        }
        print("  类别占比（按包含匹配整栈）：")
        for cat, keys in cats.items():
            hit = sum(c for stack, c in stacks
                      if any(k in f for f in stack for k in keys))
            if hit:
                print(f"    {hit/total*100:6.1f}%  {cat}")
        print()
        print("─" * 60)
        print()


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1
                  else "perf/results/step5-diagnose"))

预期输出（关键部分）：

配套代码：并发原语成本表与伪共享

Mon, 01 Jan 0001 00:00:00 +0000

2.6 配套代码：并发原语成本表与伪共享

对应小节：2.6 并发原语成本与伪共享两个实验：① 测出你自己的并发成本表；② 复现伪共享并验证修法。

一、实验一：并发原语成本表

// src/main/kotlin/lesson02/PrimitiveCosts.kt
package lesson02

import java.util.concurrent.CountDownLatch
import java.util.concurrent.atomic.AtomicLong
import java.util.concurrent.atomic.LongAdder
import kotlin.concurrent.thread

private val lock = Any()
private var sharedCounter = 0L

fun bench(label: String, iterations: Int, body: () -> Unit): Double {
    repeat(iterations / 4) { body() }                 // 粗略预热
    val t0 = System.nanoTime()
    repeat(iterations) { body() }
    val t1 = System.nanoTime()
    val ns = (t1 - t0).toDouble() / iterations
    println("%-40s %10.1f ns/op".format(label, ns))
    return ns
}

/** 多线程版本的测量：N 个线程各自跑 iterations 次，返回每个线程的平均耗时 */
fun benchThreads(label: String, threads: Int, iterationsPerThread: Int, body: (Int) -> Unit): Double {
    repeat(2) {   // 预热两轮
        val start = CountDownLatch(1); val done = CountDownLatch(threads)
        repeat(threads) { t ->
            thread { start.await(); repeat(iterationsPerThread) { body(t) }; done.countDown() }
        }
        start.countDown(); done.await()
    }
    val start = CountDownLatch(1); val done = CountDownLatch(threads)
    val t0 = System.nanoTime()
    repeat(threads) { t ->
        thread { start.await(); repeat(iterationsPerThread) { body(t) }; done.countDown() }
    }
    start.countDown(); done.await()
    val elapsed = System.nanoTime() - t0
    val ns = elapsed.toDouble() / iterationsPerThread   // 每线程的"墙上时间"摊到每次操作
    println("%-40s %10.1f ns/op".format(label, ns))
    return ns
}

fun main() {
    val n = 2_000_000

    println("=== 单线程：无竞争 ===")
    val uncontended = bench("synchronized（无竞争）", n) {
        synchronized(lock) { sharedCounter++ }
    }

    val atomic = AtomicLong()
    bench("AtomicLong.incrementAndGet（无竞争）", n) {
        atomic.incrementAndGet()
    }

    val adder = LongAdder()
    bench("LongAdder.increment（无竞争）", n) {
        adder.increment()
    }

    println()
    println("=== 4 线程：有竞争 ===")
    val contendedLock = benchThreads("synchronized（4 线程竞争）", 4, n / 4) {
        synchronized(lock) { sharedCounter++ }
    }
    val contendedAtomic = AtomicLong()
    benchThreads("AtomicLong（4 线程竞争）", 4, n / 4) {
        contendedAtomic.incrementAndGet()
    }
    val contendedAdder = LongAdder()
    benchThreads("LongAdder（4 线程竞争）", 4, n / 4) {
        contendedAdder.increment()
    }

    println()
    println("=== 线程创建成本 ===")
    bench("Thread 创建 + join", 20_000) {
        val t = thread { }
        t.join()
    }

    println()
    println("=== 结论对照 ===")
    println("无竞争 vs 有竞争        : %.1f 倍".format(contendedLock / uncontended))
    println("LongAdder vs synchronized: %.1f 倍（竞争下）".format(contendedLock / contendedAdder))
    println()
    println("预期：无竞争的锁很便宜（几十 ns），有竞争时贵一个数量级；")
    println("      LongAdder 通过分片把竞争打散，在高竞争下明显更快。")
    println()
    println("⚠️ 并发基准对线程调度极其敏感，请跑 3 次看稳定性。")
}

二、预期输出形态

=== 单线程：无竞争 ===
synchronized（无竞争）                         18.4 ns/op
AtomicLong.incrementAndGet（无竞争）           11.2 ns/op
LongAdder.increment（无竞争）                   9.8 ns/op

=== 4 线程：有竞争 ===
synchronized（4 线程竞争）                     94.7 ns/op
AtomicLong（4 线程竞争）                      112.3 ns/op
LongAdder（4 线程竞争）                        23.6 ns/op

=== 线程创建成本 ===
Thread 创建 + join                         41250.0 ns/op     ← 约 41 微秒

=== 结论对照 ===
无竞争 vs 有竞争        : 5.1 倍
LongAdder vs synchronized: 4.0 倍（竞争下）

四个关键量级：

配套代码：数据与算法类瓶颈诊断

Mon, 01 Jan 0001 00:00:00 +0000

6.6 配套代码：数据与算法类瓶颈诊断

对应小节：6.6 瓶颈模式库（二）：数据与算法类八种模式各有对应的诊断查询——这份文件把它们集中起来，一条命令全查一遍。

一、八合一诊断脚本

#!/usr/bin/env bash
# tools/diagnose-data-bottlenecks.sh <PG_CONN> [METRICS_URL] [PID]
set -uo pipefail

PG="${1:-${PG_CONN:-}}"
URL="${2:-http://127.0.0.1:8080/metrics}"
PID="${3:-$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')}"

echo "═══════════════════════════════════════════════════════════════"
echo "数据与算法类瓶颈诊断"
echo "═══════════════════════════════════════════════════════════════"
echo

# ═══ 模式一：N+1 查询 ═══════════════════════════════════════
echo "【模式一：N+1 查询】"
echo "  判据：某简单查询的 calls 远大于接口 QPS"
if [ -n "$PG" ]; then
  psql "$PG" -tAc "
  SELECT '  calls=' || calls || ' | mean=' || round(mean_exec_time::numeric,2) || 'ms'
         || ' | total=' || round(total_exec_time::numeric,0) || 'ms | '
         || left(regexp_replace(query,'\s+',' ','g'), 55)
  FROM pg_stat_statements
  WHERE query NOT LIKE '%pg_stat_statements%'
  ORDER BY calls DESC LIMIT 8;" 2>/dev/null || echo "  （无法查询）"
  echo
  echo "  ⭐ 关键：如果某个「单次很快」的查询 calls 极高 → N+1"
  echo "     修法：改成批量查询（where id = any(?)）"
else
  echo "  （未提供 PG_CONN，跳过）"
fi
echo

# ═══ 模式二：缺索引 / 全表扫描 ══════════════════════════════
echo "【模式二：缺索引 / 全表扫描】"
if [ -n "$PG" ]; then
  psql "$PG" -tAc "
  SELECT '  ' || relname || ': seq_scan=' || seq_scan || ' idx_scan=' || COALESCE(idx_scan,0)
         || ' rows=' || n_live_tup
  FROM pg_stat_user_tables
  WHERE seq_scan > 1000 AND n_live_tup > 10000
  ORDER BY seq_scan DESC LIMIT 5;" 2>/dev/null || echo "  （无法查询）"
  echo
  echo "  ⭐ 高 seq_scan + 大表 → 可能有查询没走索引"
  echo "     验证：EXPLAIN (ANALYZE, BUFFERS) <你的查询>"
  echo "     危险信号：Seq Scan / Rows Removed by Filter 很大 / 行数估计偏差大"
else
  echo "  （未提供 PG_CONN，跳过）"
fi
echo

# ═══ 模式三：锁竞争 ═════════════════════════════════════════
echo "【模式三：锁竞争】"
if [ -n "$PG" ]; then
  echo "  数据库侧的阻塞链："
  psql "$PG" -tAc "
  SELECT '    blocked=' || blocked.pid || ' by=' || blocking.pid
         || ' | ' || left(regexp_replace(blocked.query,'\s+',' ','g'), 40)
  FROM pg_stat_activity blocked
  JOIN pg_stat_activity blocking ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
  LIMIT 5;" 2>/dev/null || echo "    （无法查询）"
fi
if [ -n "$PID" ]; then
  TMP=$(mktemp)
  jcmd "$PID" Thread.print > "$TMP" 2>/dev/null
  BLOCKED=$(grep -c "java.lang.Thread.State: BLOCKED" "$TMP" || echo 0)
  echo "  应用侧的 BLOCKED 线程数: $BLOCKED"
  [ "$BLOCKED" -gt 5 ] && echo "    ❌ 大量 BLOCKED → 应用内锁竞争" || echo "    ✅ 无明显锁竞争"
  rm -f "$TMP"
fi
echo

# ═══ 模式四：GC 停顿 ════════════════════════════════════════
echo "【模式四：GC 停顿】"
M=$(curl -s --max-time 5 "$URL" 2>/dev/null || echo "")
if [ -n "$M" ]; then
  GC_P99=$(echo "$M" | awk '/jvm_gc_pause_seconds/{print $2}' | sort -rn | head -1)
  ALLOC=$(echo "$M" | awk '/jvm_gc_memory_allocated_bytes_total/{printf "%.1f", $2/1048576; exit}')
  echo "  GC 暂停相关指标: ${GC_P99:-n/a}"
  echo "  累计分配: ${ALLOC:-n/a} MB"
  echo
  echo "  ⭐ 唯一确定的验证：把 gc.log 的停顿时间戳与 P99 尖刺时间戳【对齐】"
  echo "     对齐 → GC 是根因；不对齐 → 排除 GC（能省大量时间）"
else
  echo "  （无法获取指标）"
fi
echo

# ═══ 模式五：缓存击穿/雪崩 ══════════════════════════════════
echo "【模式五：缓存击穿 / 雪崩】"
if command -v redis-cli > /dev/null 2>&1; then
  redis-cli INFO stats 2>/dev/null | grep -E "keyspace_(hits|misses)" | sed 's/^/  /' || true
  echo "  ⭐ 判据：DB QPS 出现周期性脉冲，且与缓存过期时间吻合"
  echo "     修法：TTL 加抖动（防雪崩）+ 单飞（防击穿）+ 缓存空值（防穿透）"
else
  echo "  （redis-cli 不可用）"
fi
echo

# ═══ 模式六：序列化开销 ═════════════════════════════════════
echo "【模式六：序列化开销】"
echo "  验证：采 CPU 火焰图，看顶部是否有很宽的序列化栈"
echo "    asprof -d 60 -e cpu -f cpu.html ${PID:-<pid>}"
echo "  常见栈帧：Jackson.writeValue / StringBuilder / String.format / Integer.valueOf"
echo "  ⭐ 优先考虑「减少传输的数据量」，而不是「换序列化器」"
echo

# ═══ 模式七：日志同步 IO ════════════════════════════════════
echo "【模式七：日志同步 IO】"
if [ -n "$PID" ]; then
  TMP=$(mktemp)
  jcmd "$PID" Thread.print > "$TMP" 2>/dev/null
  FILEIO=$(grep -c -E "FileOutputStream.write|FileDispatcherImpl.write" "$TMP" || echo 0)
  echo "  停在文件写入的线程数: $FILEIO"
  [ "$FILEIO" -gt 0 ] && echo "    ⚠️  有线程在写文件 → 检查是否同步日志" || echo "    ✅ 无"
  rm -f "$TMP"
fi
echo "  ⭐ 最确定的验证：JFR 的 jdk.FileWrite 事件"
echo "    jfr print --events jdk.FileWrite recording.jfr | grep -c app.log"
echo "  对照实验：把日志级别降到 ERROR，看 P99 是否回落"
echo

# ═══ 模式八：无界队列 OOM ═══════════════════════════════════
echo "【模式八：无界队列 OOM】"
if [ -n "$M" ]; then
  Q=$(echo "$M" | awk '/executor_queue_depth/{printf "%.0f", $2; exit}')
  HEAP=$(echo "$M" | awk '/jvm_memory_used_bytes.*heap/{printf "%.0f", $2/1048576; exit}')
  echo "  队列深度: ${Q:-n/a}"
  echo "  堆使用  : ${HEAP:-n/a} MB"
  echo "  ⭐ 判据：堆的「GC 后基线」单调上升（不是瞬时值）"
  echo "     用第 3 章 3.5 的 analyze_soak.py 判断趋势"
fi
echo

echo "═══════════════════════════════════════════════════════════════"
echo "八种模式的「一个指标区分」速查："
echo "  N+1 vs 缺索引     ：看 calls（高频）还是 mean（单次慢）"
echo "  锁竞争 vs CPU 饱和 ：sys 占比高 + BLOCKED 多 → 锁"
echo "  GC vs 其他周期性   ：时间戳对齐（唯一确定的方法）"
echo "  缓存击穿 vs 雪崩   ：单 key 脉冲 vs 大批 key 同时失效"
echo "  日志 IO vs 网络 IO ：JFR 的 FileWrite vs SocketWrite"
echo "═══════════════════════════════════════════════════════════════"

二、N+1 的专项检测（代码侧）

// src/main/kotlin/metrics/QueryCounter.kt
package metrics

import io.micrometer.core.instrument.Counter
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Timer
import kotlinx.coroutines.ThreadContextElement
import kotlin.coroutines.AbstractCoroutineContextElement
import kotlin.coroutines.CoroutineContext

/**
 * 统计"每个请求执行了多少次数据库查询"。
 * 这是发现 N+1 最直接的手段——比看 pg_stat_statements 更早、更准。
 *
 * 用法：
 *   withQueryCounting { handleRequest() }   // 返回 (结果, 查询次数)
 *   或者把计数作为指标暴露出去
 */
class QueryCounter(registry: MeterRegistry) {

    private val queriesPerRequest = Timer.builder("app.db.queries.per.request")
        .description("每个请求的数据库查询次数（N+1 检测）")
        .publishPercentileHistogram(false)
        .register(registry)

    // 用一个可变的 holder 在协程/线程上下文中传递
    class Holder : AbstractCoroutineContextElement(Holder) {
        companion object Key : CoroutineContext.Key<Holder>
        var count: Int = 0
    }

    /** 在数据库调用处调用这个方法 */
    fun countQuery() {
        // 在协程场景下，通过上下文传递；在线程场景下用 ThreadLocal
    }

    /** 包装一次请求处理，记录查询次数 */
    suspend fun <T> countQueries(block: suspend () -> T): Pair<T, Int> {
        val holder = Holder()
        val result = kotlinx.coroutines.withContext(holder) { block() }
        queriesPerRequest.record(holder.count.toDouble())
        return result to holder.count
    }
}

/**
 * 更简单的实现：用 ThreadLocal（如果不用协程）
 */
object SimpleQueryCounter {
    private val counter = ThreadLocal.withInitial { intArrayOf(0) }

    fun reset() { counter.get()[0] = 0 }
    fun increment() { counter.get()[0]++ }
    fun get(): Int = counter.get()[0]
}

在 Repository 层埋点：

配套代码：流量回放、副作用阻断与金丝雀

Mon, 01 Jan 0001 00:00:00 +0000

8.6 配套代码：流量回放、副作用阻断与金丝雀

对应小节：8.6 流量回放与金丝雀发布四部分：① 日志脱敏；② 副作用阻断；③ 影子流量配置；④ 金丝雀监控。

一、日志脱敏

# tools/sanitize_logs.py
"""
脱敏生产日志，准备用于流量回放。

两个原则：
  ① 保持格式（否则测不到校验逻辑）
  ② 保持关联（同一用户的请求要映射到同一新 ID，否则破坏缓存命中率）
"""
import hashlib
import json
import sys

# 需要脱敏的字段
ID_FIELDS = {"user_id", "order_id", "session_id", "account_id", "customer_id"}
PHONE_FIELDS = {"phone", "mobile", "phone_number"}
EMAIL_FIELDS = {"email", "user_email"}
TOKEN_FIELDS = {"token", "authorization", "api_key", "access_token", "refresh_token"}
NAME_FIELDS = {"name", "user_name", "real_name", "full_name"}


class Sanitizer:
    def __init__(self, salt="replay-salt-v1"):
        self.salt = salt
        self.id_map = {}
        self.stats = {"id": 0, "phone": 0, "email": 0, "token": 0, "name": 0}

    def stable_id(self, original: str, prefix: str = "replay") -> str:
        """保持关联的映射：同一输入 → 同一输出"""
        key = (prefix, original)
        if key not in self.id_map:
            h = hashlib.sha256((self.salt + prefix + original).encode()).hexdigest()[:12]
            self.id_map[key] = f"{prefix}-{h}"
        return self.id_map[key]

    def phone(self, value: str) -> str:
        """保持格式：11 位数字 → 11 位数字（避免影响校验逻辑）"""
        digits = "".join(c for c in str(value) if c.isdigit())
        if len(digits) == 11:
            return f"139{digits[-8:].rjust(8, '0')}"
        return "13900000000"

    def email(self, value: str) -> str:
        return "user@example.com"

    def name(self, value: str) -> str:
        return "测试用户"

    def token(self, value: str) -> str:
        return "replay-token-placeholder"

    def sanitize(self, obj):
        if isinstance(obj, dict):
            out = {}
            for k, v in obj.items():
                kl = k.lower()
                if kl in ID_FIELDS and v is not None:
                    out[k] = self.stable_id(str(v), prefix=kl.replace("_id", ""))
                    self.stats["id"] += 1
                elif kl in PHONE_FIELDS and v is not None:
                    out[k] = self.phone(str(v))
                    self.stats["phone"] += 1
                elif kl in EMAIL_FIELDS and v is not None:
                    out[k] = self.email(str(v))
                    self.stats["email"] += 1
                elif kl in TOKEN_FIELDS and v is not None:
                    out[k] = self.token(str(v))
                    self.stats["token"] += 1
                elif kl in NAME_FIELDS and v is not None:
                    out[k] = self.name(str(v))
                    self.stats["name"] += 1
                else:
                    out[k] = self.sanitize(v)
            return out
        elif isinstance(obj, list):
            return [self.sanitize(x) for x in obj]
        return obj


def main(in_path, out_path):
    s = Sanitizer()
    n_lines = 0

    with open(in_path, encoding="utf-8", errors="ignore") as fin, \
         open(out_path, "w", encoding="utf-8") as fout:
        for line in fin:
            if not line.strip():
                continue
            try:
                obj = json.loads(line)
            except json.JSONDecodeError:
                continue        # 跳过无法解析的行
            fout.write(json.dumps(s.sanitize(obj), ensure_ascii=False) + "\n")
            n_lines += 1

    print("═" * 70)
    print("脱敏完成")
    print("═" * 70)
    print(f"  输入: {in_path}")
    print(f"  输出: {out_path}")
    print(f"  处理行数: {n_lines}")
    print(f"  ID 映射数: {len(s.id_map)}（保持关联关系）")
    print()
    print("  字段统计:")
    for k, v in s.stats.items():
        print(f"    {k:<8}: {v}")
    print()
    print("⚠️  回放前必须人工检查:")
    print("  ① 随机抽样 20 行，确认没有遗漏的敏感字段")
    print("  ② 确认 ID 映射是稳定的（同输入 → 同输出）")
    print("  ③ 确认格式没变（手机号还是 11 位、邮箱还有 @）")
    print("═" * 70)


if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("usage: sanitize_logs.py <input.jsonl> <output.jsonl>")
        sys.exit(1)
    main(sys.argv[1], sys.argv[2])

二、副作用阻断

// src/main/kotlin/safety/SideEffectGuard.kt
package safety

import io.micrometer.core.instrument.Counter
import io.micrometer.core.instrument.MeterRegistry
import org.slf4j.LoggerFactory

/**
 * 副作用阻断开关。
 *
 * 用途：在流量回放/影子环境中，阻止短信、邮件、支付、推送等真实副作用。
 *
 * ⚠️ 关键设计：
 *   ① 默认值必须是「启用副作用」——安全的默认是"不改变现有行为"
 *   ② 被阻断时必须【记录指标】——否则你不知道开关是否生效
 *   ③ 支持按类型精细控制（比如只允许邮件、阻断支付）
 */
object SideEffectGuard {
    private val log = LoggerFactory.getLogger(SideEffectGuard::class.java)
    private lateinit var registry: MeterRegistry

    /** 总开关：影子环境必须设为 false */
    @Volatile
    var enabled: Boolean = System.getenv("ENABLE_SIDE_EFFECTS")?.toBoolean() ?: true
        private set

    /** 精细控制：允许的副作用类型（空集合表示全部允许） */
    @Volatile
    private var allowedTypes: Set<String> = emptySet()

    private val blockedCounters = mutableMapOf<String, Counter>()

    fun init(registry: MeterRegistry) {
        this.registry = registry
    }

    fun configure(enabled: Boolean, allowed: Set<String> = emptySet()) {
        this.enabled = enabled
        this.allowedTypes = allowed
        log.warn("副作用开关已变更：enabled={}, allowed={}", enabled, allowed)
    }

    /**
     * 包裹一个有副作用的操作。
     *
     * @param type 副作用类型（sms / email / payment / push / external_api）
     * @return 被阻断时返回 null；否则返回操作结果
     */
    fun <T> guarded(type: String, description: String, block: () -> T): T? {
        val allowed = enabled && (allowedTypes.isEmpty() || type in allowedTypes)
        if (!allowed) {
            val counter = blockedCounters.computeIfAbsent(type) {
                Counter.builder("side_effect.blocked")
                    .tag("type", type)
                    .description("被阻断的副作用次数")
                    .register(registry)
            }
            counter.increment()
            log.warn("⛔ 副作用已阻断 [{}] {}（影子环境）", type, description)
            return null
        }
        return block()
    }

    /** 熔断式的保护：如果被阻断的比例过高，抛出异常（防止逻辑依赖副作用结果） */
    fun requireEnabled(type: String) {
        if (!enabled || (allowedTypes.isNotEmpty() && type !in allowedTypes)) {
            throw IllegalStateException("副作用 [$type] 在影子环境中被禁用，但代码依赖它的结果")
        }
    }
}

在真实业务代码里使用：

配套代码：破坏性测试的取证与恢复测量

Mon, 01 Jan 0001 00:00:00 +0000

3.6 配套代码：破坏性测试的取证与恢复测量

对应小节：3.6 破坏性测试核心：崩溃形态比崩溃点更重要，而崩溃现场无法事后复现，必须当场采集。

一、压到崩溃：带终止条件的加压脚本

// loadtest/breakdown.js
import http from 'k6/http';
import { check } from 'k6';

/**
 * 破坏性测试：持续加压直到满足终止条件。
 *
 * ⚠️ 这不是"找拐点"，而是"找崩溃形态"。所以：
 *   - 每级稳态时间短（30 秒），因为不关心精确的拐点
 *   - 终止条件由外部脚本判断（k6 自己不会因为错误率高就停）
 *   - 必须有人在旁边盯着，随时准备中止
 */
export const options = {
  scenarios: {
    breakdown: {
      executor: 'ramping-arrival-rate',
      startRate: 200,
      timeUnit: '1s',
      preAllocatedVUs: 3000,
      maxVUs: 20000,
      stages: [
        { target: 200,  duration: '30s' },
        { target: 500,  duration: '30s' },
        { target: 1000, duration: '30s' },
        { target: 2000, duration: '30s' },
        { target: 3000, duration: '30s' },
        { target: 4000, duration: '30s' },
        { target: 5000, duration: '60s' },   // 通常到这里已经崩了
      ],
    },
  },
  discardResponseBodies: true,
  // 不要设会在中途失败的 thresholds —— 我们就是要让它崩
};

export default function () {
  const res = http.get(`${__ENV.BASE_URL}/orders/1`, {
    tags: { name: 'GET /orders/{id}' },
    timeout: '10s',
  });
  check(res, {
    'status 200': (r) => r.status === 200,
    'not timeout': (r) => r.status !== 0,
  });
}

二、现场取证脚本（最关键的部分）

#!/usr/bin/env bash
# tools/crash-forensics.sh <EXP_ID> <APP_PID> [interval_seconds] [max_samples]
#
# 在破坏性测试期间持续采集"崩溃现场"。
# 崩溃后的线程栈是最有价值的证据，而且【无法事后复现】。
set -uo pipefail

EXP_ID="${1:?usage: crash-forensics.sh <EXP_ID> <PID> [interval] [max]}"
PID="${2:?}"
INTERVAL="${3:-5}"
MAX="${4:-120}"
DIR="docs/experiments/${EXP_ID}/results/forensics"
mkdir -p "$DIR"

echo "开始取证：PID=$PID，每 ${INTERVAL}s 一次，最多 ${MAX} 次"
echo "输出目录：$DIR"

for i in $(seq 1 "$MAX"); do
  TS=$(date +%s)
  STAMP="$(date -Iseconds)"

  # ① 线程快照 —— 回答"线程都卡在哪里"
  jcmd "$PID" Thread.print > "$DIR/threads-$TS.txt" 2>/dev/null || {
    echo "[$STAMP] ❌ 进程已不可用（可能崩溃或 OOM），停止取证"
    break
  }

  # ② 关键指标 —— 回答"哪类资源先耗尽"
  {
    echo "# $STAMP"
    curl -s --max-time 3 http://127.0.0.1:8080/metrics 2>/dev/null \
      | grep -E "db_pool_(active|idle|pending|total)|executor_queue|jvm_memory_used_bytes|jvm_threads_live"
  } > "$DIR/metrics-$TS.txt" 2>/dev/null

  # ③ 简要摘要：打印一次，方便实时观察趋势
  QUEUE=$(grep executor_queue_depth "$DIR/metrics-$TS.txt" 2>/dev/null | awk '{printf "%.0f", $2}')
  PEND=$(grep db_pool_pending "$DIR/metrics-$TS.txt" 2>/dev/null | awk '{printf "%.0f", $2}')
  BLOCKED=$(grep -c "BLOCKED" "$DIR/threads-$TS.txt" 2>/dev/null || echo 0)
  echo "[$STAMP] 队列=${QUEUE:-?} 连接池pending=${PEND:-?} BLOCKED线程=${BLOCKED}"

  # ④ 自动判断是否已进入崩溃状态
  if [ "${PEND:-0}" -gt 20 ] 2>/dev/null; then
    echo "[$STAMP] ⚠️  连接池 pending=${PEND} —— 已进入连接池雪崩迹象"
  fi

  sleep "$INTERVAL"
done

echo
echo "✅ 取证结束。分析要点："
echo "   1. 崩溃时刻最后几份 threads-*.txt 里，线程都停在哪里？"
echo "      - socketRead0 / 等数据库 → 数据库慢或连接池耗尽"
echo "      - BLOCKED (on object monitor) → 锁竞争"
echo "      - 等连接池 (HikariPool.getConnection) → 连接池雪崩"
echo "   2. metrics-*.txt 里，哪一类饱和度指标最先上升？"
echo "   3. 队列深度是否持续增长（无界队列 OOM 的前兆）？"

三、恢复能力测量（最容易被忽略的一步）

#!/usr/bin/env bash
# tools/measure-recovery.sh <EXP_ID>
#
# 破坏性测试结束后，持续打低负载，测量"多久恢复"。
# 这一步决定了故障的严重程度，比崩溃点本身更重要。
set -uo pipefail

EXP_ID="${1:?usage: measure-recovery.sh <EXP_ID>}"
DIR="docs/experiments/${EXP_ID}/results"
mkdir -p "$DIR"

echo "开始测量恢复能力（低负载 50 req/s，持续 10 分钟）..."
echo "判据：P99 回到崩溃前基线的 1.2 倍以内，且 pending 回到 0"
echo
echo "elapsed_s,p99_ms,error_rate,pending,queue_depth"

START=$(date +%s)
RECOVERED_AT=""
for i in $(seq 1 120); do
  ELAPSED=$(( $(date +%s) - START ))

  # 用 curl 做一次简单测量（真实场景应该用 k6 短跑）
  RESULT=$(curl -s -o /dev/null -w "%{time_total}" --max-time 5 http://127.0.0.1:8080/orders/1 2>/dev/null || echo "5.0")
  P99_MS=$(echo "$RESULT * 1000 / 1" | bc 2>/dev/null || echo "0")

  METRICS=$(curl -s --max-time 3 http://127.0.0.1:8080/metrics 2>/dev/null || echo "")
  PEND=$(echo "$METRICS" | awk '/db_pool_pending/{printf "%.0f", $2; exit}')
  QUEUE=$(echo "$METRICS" | awk '/executor_queue_depth/{printf "%.0f", $2; exit}')

  echo "$ELAPSED,$P99_MS,,${PEND:-0},${QUEUE:-0}"

  # 判定恢复
  if [ -z "$RECOVERED_AT" ] && [ "${PEND:-1}" = "0" ] && [ "${P99_MS%%.*}" -lt 100 ] 2>/dev/null; then
    RECOVERED_AT="$ELAPSED"
  fi

  sleep 5
done

echo
if [ -n "$RECOVERED_AT" ]; then
  echo "✅ 恢复时间：约 ${RECOVERED_AT} 秒（pending 归零且延迟回到 100ms 以内）"
else
  echo "❌ 10 分钟内未恢复 —— 系统【无法自愈】，需要人工介入或重启"
  echo "   重点检查：超时配置是否过长？连接是否被长期占用？"
fi

四、超时链自检（决定能否自愈）

// src/main/kotlin/resilience/TimeoutAudit.kt
package resilience

/**
 * 超时链审计：找出"本层超时 > 上游超时"的配置。
 *
 * 这是决定"系统崩溃后能否自愈"的关键：
 *   如果应用给数据库的超时（30s）远大于网关给应用的超时（1s），
 *   那么网关超时返回后，应用线程仍然被占住 30 秒 → 连接池持续满 → 无法自愈。
 */
data class TimeoutLayer(
    val name: String,
    val upstreamBudgetMs: Long,      // 上游给这一层的时间
    val selfTimeoutMs: Long,         // 这一层给下游/自己的超时
)

fun auditTimeouts(layers: List<TimeoutLayer>): List<String> {
    val problems = mutableListOf<String>()
    var previousBudget = Long.MAX_VALUE

    layers.forEach { layer ->
        // ① 本层超时不应超过上游给的预算
        if (layer.selfTimeoutMs > layer.upstreamBudgetMs) {
            problems += buildString {
                append("❌ ${layer.name}: 本层超时 ${layer.selfTimeoutMs}ms > 上游预算 ${layer.upstreamBudgetMs}ms")
                append("\n     后果：上游已超时返回，本层的调用仍在继续，资源被占住 → 可能无法自愈")
            }
        }
        // ② 上游预算不应超过更上游给的预算（逐层递减）
        if (layer.upstreamBudgetMs > previousBudget) {
            problems += "❌ ${layer.name}: 上游预算 ${layer.upstreamBudgetMs}ms 大于再上游的 ${previousBudget}ms（超时链未递减）"
        }
        previousBudget = layer.selfTimeoutMs
    }

    return problems
}

fun main() {
    println("=== 反例：会导致无法自愈的配置 ===")
    auditTimeouts(listOf(
        TimeoutLayer("客户端 → 网关", upstreamBudgetMs = 5_000, selfTimeoutMs = 3_000),
        TimeoutLayer("网关 → 应用",   upstreamBudgetMs = 3_000, selfTimeoutMs = 1_000),
        TimeoutLayer("应用 → 数据库", upstreamBudgetMs = 30_000, selfTimeoutMs = 30_000),  // ← 灾难
        TimeoutLayer("应用 → Redis",  upstreamBudgetMs = 30_000, selfTimeoutMs = 5_000),
    )).forEach { println(it); println() }

    println("=== 正例：逐层递减，可自愈 ===")
    val ok = auditTimeouts(listOf(
        TimeoutLayer("客户端 → 网关", upstreamBudgetMs = 5_000, selfTimeoutMs = 500),
        TimeoutLayer("网关 → 应用",   upstreamBudgetMs = 500,   selfTimeoutMs = 300),
        TimeoutLayer("应用 → 数据库", upstreamBudgetMs = 300,   selfTimeoutMs = 60),
        TimeoutLayer("应用 → Redis",  upstreamBudgetMs = 300,   selfTimeoutMs = 10),
    ))
    if (ok.isEmpty()) println("✅ 超时链自洽，逐层递减")
    else ok.forEach { println(it) }

    println()
    println("核心规则：本层超时必须小于上游预算，且逐层递减。")
    println("超时不是『容忍时间』，而是『放弃的时机』——放弃得早，系统才能自愈。")
}

五、崩溃形态的记录模板

## 破坏性测试记录

### 时间线
| 时刻 | 事件 |
| --- | --- |
| T+0 | 开始加压（200 req/s） |
| T+2:30 | 到达 2000 req/s，P99 = 320 ms |
| T+3:10 | P99 开始非线性上升（>1s），**连接池 pending 从 0 → 18** |
| T+3:40 | 错误率超过 5%，触发终止条件，停止加压 |
| T+4:05 | 负载回落到基线，但 P99 仍 >2s |
| T+8:30 | P99 回到基线 1.2 倍以内，pending = 0 |

### 崩溃点
- 崩溃负载：约 **3000 req/s**（P99 > 1s，错误率 > 5%）

### 崩溃形态 ⭐（比崩溃点更重要）
- **首要形态**：连接池雪崩
  - 证据：`forensics/metrics-*.txt` 显示 pending 从 0 涨到 18，同时 active 触顶在 10
  - 证据：`forensics/threads-*.txt` 中 47 个线程停在 `HikariPool.getConnection`
- **次要形态**：无界队列积压（队列深度从 0 涨到 1200）
- **是否级联**：是 —— 所有接口（包括不查数据库的）都开始超时

### 恢复能力 ⭐
- **恢复时间**：约 4 分 25 秒
- **能否自愈**：⚠️ 否 —— pending 在负载回落后仍 >0 达 3 分钟
- **根因**：应用给数据库的超时是 30 秒（默认值），负载回落后这些连接仍在等待
- **改进**：把数据库超时改为 3 秒（见 `TimeoutAudit`），预计恢复时间降到 10 秒内

### 记录到的证据文件
- `results/forensics/threads-*.txt`（崩溃瞬间线程栈）
- `results/forensics/metrics-*.txt`（连接池与队列趋势）

六、动手改造

改动	观察什么
把数据库超时从 30 秒改成 3 秒，重跑	恢复时间是否大幅缩短？（这是「超时决定自愈能力」的验证）
把取证间隔从 5 秒改成 1 秒	能看到更细的崩溃过程，但会产生大量文件
在崩溃时把连接池从 10 加到 50	崩溃点会后移，但崩溃形态会变成"数据库被打垮"——问题只是被转移了
给队列加上界 + 拒绝策略，重跑	崩溃形态从「OOM」变成「快速失败（503）」——这就是优雅降级
去掉「恢复测量」这一步	你会以为「停止加压就恢复了」，而事实可能相反

七、这段代码的局限

measure-recovery.sh 的延迟测量非常粗糙（用 curl 单次请求），只能判断量级。严谨的做法是用 k6 短跑取 P99。
崩溃状态有时不可复现：同样的负载，第二次可能不会崩（因为缓存、连接池状态不同）。这正是为什么必须当场取证。
不要在生产做这些测试。即使在测试环境，也要确保：有终止条件、能重启、数据可重置。
TimeoutAudit 只检查了链路中的静态配置，实际的超时行为还受重试、连接获取超时、DNS 解析等影响。

配套代码：连接池计算与对象池成本对比

Mon, 01 Jan 0001 00:00:00 +0000

7.6 配套代码：连接池计算与对象池成本对比

对应小节：7.6 池化与复用两件事：① 用 Little’s Law 算连接池大小；② 用实验证明「对象池在 JVM 上常是负优化」。

一、连接池大小计算器

# tools/pool-size-calculator.py
"""
用 Little's Law 推导连接池大小。

核心公式：所需连接数 = 目标 QPS × 单次操作耗时（秒）
"""
import sys


def calculate(
    peak_qps: int,
    p50_ms: float,
    p99_ms: float,
    instances: int,
    db_max_connections: int,
    headroom: float = 0.3,
):
    print("═" * 78)
    print("连接池大小计算（Little's Law）")
    print("═" * 78)
    print()
    print(f"输入：")
    print(f"  峰值 QPS            : {peak_qps}")
    print(f"  单次查询 P50/P99    : {p50_ms} / {p99_ms} ms")
    print(f"  应用实例数           : {instances}")
    print(f"  数据库 max_connections: {db_max_connections}")
    print(f"  headroom            : {headroom:.0%}")
    print()

    # ① 用 P50 和 P99 分别计算
    l_optimistic = peak_qps * (p50_ms / 1000)
    l_pessimistic = peak_qps * (p99_ms / 1000)

    print("【所需连接数（全集群）】")
    print(f"  按 P50（乐观）      : {l_optimistic:8.1f}")
    print(f"  按 P99（悲观）      : {l_pessimistic:8.1f}")
    print(f"  差距                : {l_pessimistic / l_optimistic:.1f} 倍")
    print()

    # ② 每实例
    per_instance_opt = l_optimistic / instances
    per_instance_pess = l_pessimistic / instances

    print("【每实例所需连接数】")
    print(f"  按 P50               : {per_instance_opt:8.1f}")
    print(f"  按 P99               : {per_instance_pess:8.1f}")
    print()

    # ③ 建议值：取 P95 附近 + headroom
    # 用对数插值近似 P95
    p95_ms = p50_ms + (p99_ms - p50_ms) * 0.7
    l_p95 = peak_qps * (p95_ms / 1000)
    per_instance_suggested = l_p95 / instances * (1 + headroom)

    print("【建议配置】")
    print(f"  取 P95（≈{p95_ms:.1f}ms）并加 {headroom:.0%} headroom：")
    print(f"    全集群            : {l_p95 * (1 + headroom):8.1f}")
    print(f"    每实例            : {per_instance_suggested:8.1f} → 取整 {int(per_instance_suggested) + 1}")
    print()

    # ④ 检查数据库上限
    recommended_per_instance = int(per_instance_suggested) + 1
    total_needed = recommended_per_instance * instances

    print("【数据库侧检查】")
    print(f"  总连接需求          : {recommended_per_instance} × {instances} = {total_needed}")
    print(f"  数据库上限          : {db_max_connections}")
    # 留 5 个给运维/监控
    available = db_max_connections - 5
    if total_needed > available:
        print(f"  ❌ 超出上限（可用 {available}）")
        print()
        print("  解决方案：")
        print(f"    ① 降低每实例池大小到 {available // instances}（{available // instances} × {instances} = {available // instances * instances}）")
        print("    ② 或引入 PgBouncer 等连接池代理")
        print("    ③ 或减少实例数、提高单实例能力")
        print("    ④ ⭐ 最优：优化查询本身（让 P99 降低，所需连接数自然下降）")
    else:
        print(f"  ✅ 在上限内（余量 {available - total_needed}）")
    print()

    # ⑤ 关键提醒
    print("═" * 78)
    print("配置时必做的三件事：")
    print("  ① 设置【获取连接超时】（如 3 秒）—— 避免无限等待（第 7.5 节）")
    print("  ② 监控 pending —— 它是判断「池是否足够」的直接指标")
    print("  ③ 先确认查询合理（有索引、无 N+1）—— 否则加大池只是转移压力")
    print()
    print("⚠️  最重要的一条：")
    print("  连接池是数据库的【并发闸门】—— 它决定了最多有多少个查询同时在数据库上执行。")
    print("  池设小了 → 应用排队（延迟高，但数据库健康）")
    print("  池设大了 → 数据库排队（锁竞争加剧、IO 队列变长）→ 所有查询都变慢")
    print("  所以「池越大越好」是错的。")
    print("═" * 78)


if __name__ == "__main__":
    calculate(
        peak_qps=1000,
        p50_ms=8.0,
        p99_ms=60.0,
        instances=6,
        db_max_connections=100,
    )

预期输出（节选）：

配套代码：追踪、日志与基数控制

Mon, 01 Jan 0001 00:00:00 +0000

4.6 配套代码：追踪、日志与基数控制

对应小节：4.6 应用可观测性三部分：① OpenTelemetry 追踪接入；② 日志异步化与降开销；③ 指标基数控制。

一、OpenTelemetry 追踪接入

// build.gradle.kts
dependencies {
    implementation("io.opentelemetry:opentelemetry-api:1.43.0")
    implementation("io.opentelemetry:opentelemetry-sdk:1.43.0")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.43.0")
    implementation("io.opentelemetry:opentelemetry-extension-kotlin:1.43.0")
    implementation("io.opentelemetry.instrumentation:opentelemetry-kotlin-coroutines:1.32.0-alpha")
}

// src/main/kotlin/tracing/Tracing.kt
package tracing

import io.opentelemetry.api.OpenTelemetry
import io.opentelemetry.api.common.AttributeKey
import io.opentelemetry.api.trace.Span
import io.opentelemetry.api.trace.SpanKind
import io.opentelemetry.api.trace.StatusCode
import io.opentelemetry.api.trace.Tracer
import io.opentelemetry.sdk.OpenTelemetrySdk
import io.opentelemetry.sdk.trace.SdkTracerProvider
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter
import io.opentelemetry.sdk.trace.samplers.Sampler
import kotlinx.coroutines.withContext
import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.coroutineContext

object Tracing {
    lateinit var tracer: Tracer
        private set

    fun init(samplingRatio: Double = 0.1) {
        val exporter = OtlpHttpSpanExporter.builder()
            .setEndpoint("http://localhost:4318/v1/traces")
            .build()

        val provider = SdkTracerProvider.builder()
            // ⚠️ Head sampling：按比例采样。已知局限：会漏掉慢请求（见下方说明）
            .setSampler(Sampler.traceIdRatioBased(samplingRatio))
            .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
            .build()

        tracer = OpenTelemetrySdk.builder()
            .setTracerProvider(provider)
            .build()
            .getTracer("app")
    }
}

/**
 * 给一段挂起代码加 Span。
 * 注意：必须保证 Span 在【所有挂起点】都处于当前上下文，
 * 所以要用 withContext(span.asContextElement())（需要 otel-kotlin 扩展）。
 */
suspend fun <T> traced(
    name: String,
    kind: SpanKind = SpanKind.INTERNAL,
    attributes: Map<String, String> = emptyMap(),
    block: suspend () -> T,
): T {
    val span = Tracing.tracer.spanBuilder(name).setSpanKind(kind).apply {
        attributes.forEach { (k, v) -> setAttribute(AttributeKey.stringKey(k), v) }
    }.startSpan()

    return try {
        withContext(span.asContextElement()) {     // 让挂起点也继承这个 Span
            block()
        }
    } catch (e: Throwable) {
        span.setStatus(StatusCode.ERROR, e.message ?: "error")
        span.recordException(e)
        throw e
    } finally {
        span.end()
    }
}

在路由里使用：

配套代码：闭环 vs 开环——P99 差 500 倍的实验

Mon, 01 Jan 0001 00:00:00 +0000

0.6 配套代码：闭环 vs 开环——P99 差 500 倍的实验

对应小节：0.6 协调遗漏：压测报告的最大谎言要验证的结论：同一个服务、同一段卡顿，闭环压测报告的 P99 可能只有真实值的 1/500。

一、实验设计

我们做一个「服务端卡顿」的实验，然后分别用两种压测方式去测它：

服务端模型：

单线程处理，每次处理耗时 2 ms（串行，所以基线吞吐 = 500 req/s）；
在第 4000 ms 到 5000 ms 之间发生一次卡顿，卡顿期间每个请求额外多花 1000 ms。

两种压测方式：

方式	机制	对应现实
开环（恒定到达率）	每 2 ms 发一个请求，不等响应	真实用户/真实流量，按自己的节奏来
闭环（虚拟用户）	1 个虚拟用户，收到响应才发下一个	大多数压测工具的默认模型

关键设计：闭环用 1 个虚拟用户，这样它的基线吞吐也是 500 req/s——两种方式在正常情况下表现完全一样，唯一的差别只出现在卡顿发生的那一秒。

二、代码

// src/main/kotlin/lesson00/CoordinatedOmission.kt
package lesson00

import kotlin.math.max

/**
 * 服务端模型：单线程串行处理。
 * 如果某个请求的【开始处理时刻】落在 [stallFrom, stallTo) 之间，
 * 它的处理时间就额外增加 stallExtraMs（模拟一次 GC 停顿或锁等待）。
 */
class ServerModel(
    private val serviceMs: Double,
    private val stallFrom: Double,
    private val stallTo: Double,
    private val stallExtraMs: Double,
) {
    private var freeAt = 0.0

    /** 处理一个请求，返回它的完成时刻 */
    fun handle(arrivalMs: Double): Double {
        val start = max(arrivalMs, freeAt)               // 服务台忙就要等
        val extra = if (start >= stallFrom && start < stallTo) stallExtraMs else 0.0
        val done = start + serviceMs + extra
        freeAt = done
        return done
    }
}

fun percentile(sorted: DoubleArray, q: Double): Double =
    sorted[((sorted.size - 1) * q).toInt().coerceIn(0, sorted.size - 1)]

/**
 * 开环压测：按恒定到达率发请求，不管上一个有没有回来。
 * 延迟按「收到响应 − 计划发送时刻」计算（这才是正确的算法）。
 */
fun openLoop(rate: Double, durationMs: Double, server: ServerModel): DoubleArray {
    val total = (rate * durationMs / 1000.0).toInt()
    val latencies = DoubleArray(total)
    for (i in 0 until total) {
        val scheduled = i * (1000.0 / rate)              // 计划发送时刻
        val done = server.handle(scheduled)
        latencies[i] = done - scheduled
    }
    return latencies
}

/**
 * 闭环压测：N 个虚拟用户，每个收到响应后立刻发下一个请求。
 * 延迟按「收到响应 − 实际发送时刻」计算（工具通常这么算）。
 */
fun closedLoop(workers: Int, durationMs: Double, server: ServerModel): DoubleArray {
    val nextSend = DoubleArray(workers) { 0.0 }          // 每个"发令员"下次能发的时刻
    val latencies = ArrayList<Double>()

    while (true) {
        // 找到最早能发的那个用户
        var w = -1
        var earliest = Double.MAX_VALUE
        for (i in nextSend.indices) {
            if (nextSend[i] < earliest) { earliest = nextSend[i]; w = i }
        }
        if (earliest >= durationMs) break

        val done = server.handle(earliest)
        latencies.add(done - earliest)
        nextSend[w] = done                                // 收到响应，立刻发下一个
    }
    return latencies.toDoubleArray()
}

fun report(name: String, latencies: DoubleArray, expectedCount: Int) {
    val sorted = latencies.sortedArray()
    val actual = latencies.size
    val missing = expectedCount - actual

    println("--- %s ---".format(name))
    println("  请求数：实际 %d / 期望 %d  %s".format(
        actual, expectedCount,
        if (missing > expectedCount * 0.01)
            "← 少了 %.1f%%，这是协调遗漏的证据！".format(100.0 * missing / expectedCount)
        else "（基本一致）"
    ))
    println("  P50  : %8.2f ms".format(percentile(sorted, 0.50)))
    println("  P95  : %8.2f ms".format(percentile(sorted, 0.95)))
    println("  P99  : %8.2f ms".format(percentile(sorted, 0.99)))
    println("  P999 : %8.2f ms".format(percentile(sorted, 0.999)))
    println("  max  : %8.2f ms".format(sorted.last()))
    println()
}

fun main() {
    // 服务端参数
    val serviceMs = 2.0
    val stallFrom = 4000.0
    val stallTo = 5000.0
    val stallExtra = 1000.0
    val durationMs = 10_000.0
    val rate = 500.0                                     // 500 req/s

    println("=== 服务端：500 req/s 基线，第 4~5 秒发生一次 1 秒的卡顿 ===\n")

    val openResult = openLoop(rate, durationMs, ServerModel(serviceMs, stallFrom, stallTo, stallExtra))
    report("开环（恒定到达率 500/s）", openResult, (rate * durationMs / 1000).toInt())

    // 闭环：1 个虚拟用户，基线吞吐也是 500 req/s
    val closedResult = closedLoop(1, durationMs, ServerModel(serviceMs, stallFrom, stallTo, stallExtra))
    report("闭环（1 个虚拟用户）", closedResult, (rate * durationMs / 1000).toInt())

    // 对照：闭环多用几个人
    for (w in listOf(2, 5, 10)) {
        val r = closedLoop(w, durationMs, ServerModel(serviceMs, stallFrom, stallTo, stallExtra))
        report("闭环（%d 个虚拟用户）".format(w), r, (rate * durationMs / 1000).toInt())
    }

    // 结论
    val openP99 = percentile(openResult.sortedArray(), 0.99)
    val closedP99 = percentile(closedResult.sortedArray(), 0.99)
    println("=== 结论 ===")
    println("开环报告的 P99：%8.2f ms  ← 接近真相".format(openP99))
    println("闭环报告的 P99：%8.2f ms  ← 被藏起来了".format(closedP99))
    println("低估倍数      ：%8.0f 倍".format(openP99 / closedP99))
    println()
    println("同一个服务、同一次卡顿，只是因为压测模型的差别，")
    println("报告的 P99 就差了三个数量级。这就是协调遗漏。")
}

三、预期输出

=== 服务端：500 req/s 基线，第 4~5 秒发生一次 1 秒的卡顿 ===

--- 开环（恒定到达率 500/s） ---
  请求数：实际 5000 / 期望 5000  （基本一致）
  P50  :     2.00 ms
  P95  :     2.00 ms
  P99  :  1002.00 ms      ← 看到了真相
  P999 :  1002.06 ms
  max  :  1002.26 ms

--- 闭环（1 个虚拟用户） ---
  请求数：实际 4501 / 期望 5000  ← 少了 10.0%，这是协调遗漏的证据！
  P50  :     2.00 ms
  P95  :     2.00 ms
  P99  :     2.00 ms      ← 1 秒的卡顿完全看不见
  P999 :  1002.00 ms      ← 只在这里露了个头
  max  :  1002.00 ms

--- 闭环（2 个虚拟用户） ---
  请求数：实际 4700 / 期望 5000  ← 少了 6.0% ...
  P99  :     2.00 ms      ← 依然看不见

--- 闭环（10 个虚拟用户） ---
  请求数：实际 4900 / 期望 5000  ← 少了 2.0% ...
  P99  :  1002.00 ms      ← 虚拟用户足够多时，才勉强能看见

请特别注意最后一段：闭环的虚拟用户越多，越接近真相。这解释了为什么「100 个并发用户」的压测比「1 个用户」可信——但即使 100 个用户，如果卡顿时间更长或服务更慢，依然会低估。开环模型从原理上就不存在这个问题。

配套代码：阶梯加压、拐点检测与容量推算

Mon, 01 Jan 0001 00:00:00 +0000

1.6 配套代码：阶梯加压、拐点检测与容量推算

对应小节：1.6 基线与容量曲线三件事：① 压出曲线 ② 找到拐点 ③ 推出安全容量与副本数。

一、阶梯加压脚本（k6）

// loadtest/capacity-staircase.js
import http from 'k6/http';
import { check } from 'k6';

// 阶梯：每一级"爬升 30s + 稳态 120s"
// 稳态窗口才是用来采数据的，爬升期不计入
const LEVELS = [100, 200, 400, 700, 1000, 1500, 2000];

const stages = [];
for (const target of LEVELS) {
  stages.push({ target, duration: '30s' });    // 爬升
  stages.push({ target, duration: '2m' });     // 稳态（采数据）
}

export const options = {
  scenarios: {
    staircase: {
      executor: 'ramping-arrival-rate',
      startRate: 50,
      timeUnit: '1s',
      preAllocatedVUs: 500,
      maxVUs: 5000,                             // 必须给够，否则实际到达率低于设定值
      stages,
    },
  },
  // 这里故意不设 thresholds：容量测试的目的是"找到拐点"，不是"判定通过/失败"
  discardResponseBodies: true,
};

export default function () {
  // 用幂律分布取样，制造真实的热点
  const u = Math.random();
  const id = Math.max(1, Math.floor(1_000_000 * Math.pow(u, 3)) + 1);
  const res = http.get(`${__ENV.BASE_URL}/orders/${id}?stage=${__ENV.STAGE ?? 'unknown'}`);
  check(res, { ok: (r) => r.status === 200 || r.status === 404 });
}

# 运行并把原始数据落盘
k6 run --out json=docs/experiments/E02-capacity/results/k6-raw.json \
       --summary-export=docs/experiments/E02-capacity/results/k6-summary.json \
       loadtest/capacity-staircase.js

关键检查：跑完后先看实际 QPS 是否等于设定值。如果 k6 报告的到达率低于 LEVELS，说明 preAllocatedVUs 不够——此时曲线不可用（第 0 章 0.6 节的协调遗漏）。

配套代码：非参数检验与 Bootstrap 置信区间

Mon, 01 Jan 0001 00:00:00 +0000

5.6 配套代码：非参数检验与 Bootstrap 置信区间

对应小节：5.6 统计基础 纯 Python 标准库实现，不依赖 scipy——这样在任何环境都能跑。

一、Mann-Whitney U 检验

# tools/stats_test.py <baseline.json...> -- <candidate.json...>
#   或者从两个目录读取：--baseline-dir DIR --candidate-dir DIR
"""
Mann-Whitney U 检验（又称 Wilcoxon 秩和检验）。

为什么不用 t 检验：
  - t 检验假设数据服从正态分布
  - 延迟分布是重尾的（大部分很小，少数极大）
  - t 检验对异常值敏感

Mann-Whitney U 的原理：
  把两组数据混合排序，看两组的值是否"交错"。
  完全不交错 → 差异显著
  完全交错   → 差异不显著
"""
import json
import pathlib
import sys
from math import sqrt, erf


def load_metric(paths, metric="p(99)"):
    """从 k6 summary 里提取指定指标"""
    vals = []
    for p in paths:
        try:
            m = json.loads(pathlib.Path(p).read_text())["metrics"]["http_req_duration"]
            vals.append(m.get(metric, m.get("med", 0)))
        except Exception as e:
            print(f"⚠️  跳过 {p}: {e}", file=sys.stderr)
    return vals


def rankdata(values):
    """计算秩（处理并列时取平均秩）"""
    order = sorted(range(len(values)), key=lambda i: values[i])
    ranks = [0.0] * len(values)
    i = 0
    while i < len(order):
        j = i
        while j + 1 < len(order) and values[order[j + 1]] == values[order[i]]:
            j += 1
        avg_rank = (i + j) / 2.0 + 1
        for k in range(i, j + 1):
            ranks[order[k]] = avg_rank
        i = j + 1
    return ranks


def mannwhitneyu(a, b):
    """
    返回 (U 统计量, 双尾 p 值)。
    用正态近似（大样本）+ 连续性校正。
    """
    n1, n2 = len(a), len(b)
    if n1 == 0 or n2 == 0:
        return None, None

    combined = list(a) + list(b)
    ranks = rankdata(combined)
    r1 = sum(ranks[:n1])
    u1 = r1 - n1 * (n1 + 1) / 2.0
    u2 = n1 * n2 - u1
    u = min(u1, u2)

    mu = n1 * n2 / 2.0
    # 处理并列的方差校正（简化版）
    sigma = sqrt(n1 * n2 * (n1 + n2 + 1) / 12.0)
    if sigma == 0:
        return u, 1.0

    z = (u - mu + 0.5) / sigma          # 连续性校正
    p = 2 * (1 - 0.5 * (1 + erf(abs(z) / sqrt(2))))
    return u, max(0.0, min(1.0, p))


def median(xs):
    s = sorted(xs)
    n = len(s)
    return s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2


def describe(vals, label):
    if not vals:
        print(f"{label}: （无数据）")
        return
    s = sorted(vals)
    print(f"{label}: n={len(vals)}  中位数={median(vals):.2f}  "
          f"最小={s[0]:.2f}  最大={s[-1]:.2f}")
    print(f"    值 = {[round(v, 1) for v in vals]}")


def main(argv):
    if len(argv) < 3:
        print(__doc__)
        return

    # 解析参数：支持 -- 分隔的两组文件，或两个目录
    if "--baseline-dir" in argv:
        bi = argv.index("--baseline-dir")
        ci = argv.index("--candidate-dir")
        bdir, cdir = pathlib.Path(argv[bi + 1]), pathlib.Path(argv[ci + 1])
        b_paths = sorted(bdir.glob("*.json"))
        c_paths = sorted(cdir.glob("*.json"))
    elif "--" in argv:
        sep = argv.index("--")
        b_paths = [pathlib.Path(p) for p in argv[1:sep]]
        c_paths = [pathlib.Path(p) for p in argv[sep + 1:]]
    else:
        print("❌ 请用 '基线文件... -- 实验文件...' 或 '--baseline-dir X --candidate-dir Y'")
        return

    print("═" * 74)
    print("Mann-Whitney U 检验")
    print("═" * 74)
    print()

    for metric, label in [("med", "P50"), ("p(95)", "P95"), ("p(99)", "P99"), ("p(99.9)", "P999")]:
        a = load_metric(b_paths, metric)
        b = load_metric(c_paths, metric)
        if len(a) < 3 or len(b) < 3:
            continue

        print(f"【{label}】")
        describe(a, "  基线  ")
        describe(b, "  实验  ")

        u, p = mannwhitneyu(a, b)
        ma, mb = median(a), median(b)
        delta = (mb - ma) / ma * 100 if ma else 0

        print(f"  差异       : {delta:+.2f}%")
        print(f"  U 统计量   : {u:.1f}")
        print(f"  p 值       : {p:.4f}")

        if p < 0.01:
            verdict = "高度显著（p < 0.01）"
        elif p < 0.05:
            verdict = "显著（p < 0.05）"
        else:
            verdict = "不显著（p ≥ 0.05）—— 无法确认差异"
        print(f"  判定       : {verdict}")

        # 提醒：显著 ≠ 值得做
        if p < 0.05 and abs(delta) < 10:
            print(f"  ⚠️  虽然显著，但幅度仅 {abs(delta):.1f}%，可能小于用户感知阈值")
            print(f"     统计显著 ≠ 值得做（第 5.6 节）")
        if len(a) < 5 or len(b) < 5:
            print(f"  ⚠️  样本量偏小（{len(a)}/{len(b)}），p 值的可靠性有限")
        if len(set(a) | set(b)) < 5:
            print(f"  ⚠️  数据取值太少（可能有并列），正态近似的 p 值不够准")
        print()

    print("═" * 74)
    print("判读提醒：")
    print("  ① p < 0.05 只说明「差异不太可能是偶然」，还需要看幅度是否大于噪声底线")
    print("  ② 样本量 ≥ 5 时结论较可靠；3–4 时只能作为参考")
    print("  ③ 统计显著 ≠ 值得做（还要看用户是否可感知、成本是否合理）")
    print("═" * 74)


if __name__ == "__main__":
    main(sys.argv)

二、Bootstrap 置信区间（更适合重尾分布）

# tools/bootstrap_ci.py <round-*.json>... [--metric p(99)] [--iters 10000]
"""
Bootstrap 重采样置信区间。

为什么用它：
  - 不假设分布形态（延迟是重尾的）
  - 比"均值 ± 1.96 × 标准误"更稳健
  - 对小样本也适用

原理：
  ① 从原始样本中有放回地抽取同样大小的样本
  ② 计算该样本的统计量（中位数）
  ③ 重复 10000 次
  ④ 取这 10000 个统计量的 2.5% 与 97.5% 分位 → 95% 置信区间
"""
import json
import pathlib
import random
import sys


def load_metric(paths, metric):
    vals = []
    for p in paths:
        try:
            m = json.loads(pathlib.Path(p).read_text())["metrics"]["http_req_duration"]
            vals.append(m.get(metric, m.get("med", 0)))
        except Exception:
            pass
    return vals


def median(xs):
    s = sorted(xs)
    n = len(s)
    return s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2


def bootstrap_ci(sample, iters=10000, alpha=0.05, seed=42):
    rnd = random.Random(seed)
    n = len(sample)
    stats = []
    for _ in range(iters):
        resample = [sample[rnd.randrange(n)] for _ in range(n)]
        stats.append(median(resample))
    stats.sort()
    lo = stats[int(iters * alpha / 2)]
    hi = stats[int(iters * (1 - alpha / 2))]
    return lo, hi


def main(argv):
    metric = "p(99)"
    iters = 10000
    if "--metric" in argv:
        metric = argv[argv.index("--metric") + 1]
    if "--iters" in argv:
        iters = int(argv[argv.index("--iters") + 1])
    paths = [pathlib.Path(p) for p in argv[1:] if not p.startswith("--") and not p.isdigit()]

    vals = load_metric(paths, metric)
    if len(vals) < 3:
        print("❌ 至少需要 3 轮数据")
        return

    med = median(vals)
    lo, hi = bootstrap_ci(vals, iters)

    print("═" * 66)
    print(f"Bootstrap 95% 置信区间（指标：{metric}，{iters} 次重采样）")
    print("═" * 66)
    print()
    print(f"样本（{len(vals)} 轮）: {[round(v, 1) for v in vals]}")
    print(f"点估计（中位数）: {med:.2f}")
    print(f"95% 置信区间    : [{lo:.2f}, {hi:.2f}]")
    print(f"区间宽度        : {hi - lo:.2f}  （越窄越精确）")
    print()

    width_pct = (hi - lo) / med * 100 if med else 0
    print("判读：")
    if width_pct < 10:
        print(f"  ✅ 区间宽度占中位数 {width_pct:.1f}%，样本量足够")
    elif width_pct < 25:
        print(f"  ⚠️  区间宽度占中位数 {width_pct:.1f}%，偏宽")
        print(f"     建议增加轮数（当前 {len(vals)} 轮）")
    else:
        print(f"  ❌ 区间宽度占中位数 {width_pct:.1f}%，太宽")
        print(f"     说明环境噪声大或轮数太少 —— 先修环境（第 5.4 节）")
    print()

    print("用法示例：")
    print(f"  「P99 中位数为 {med:.1f} ms，95% 置信区间 [{lo:.1f}, {hi:.1f}]」")
    print()
    print("  判断达标：如果区间上限 < SLO 阈值，可以认为达标")
    print("  判断优化：如果优化前后的置信区间【不重叠】，差异很可能是真实的")
    print("            （重叠也不代表没差异，需要 Mann-Whitney U 检验）")
    print("═" * 66)


if __name__ == "__main__":
    main(sys.argv)

三、完整分析流程（一键）

#!/usr/bin/env bash
# tools/analyze-experiment.sh <BASELINE_DIR> <CANDIDATE_DIR> <NOISE_FLOOR_P99_PCT>
#
# 把本章的统计工具串成一条流程。
set -uo pipefail

BASE_DIR="${1:?usage: analyze-experiment.sh <baseline_dir> <candidate_dir> <noise_floor_pct>}"
CAND_DIR="${2:?}"
NOISE="${3:?}"

echo "══════════════════════════════════════════════════════════════"
echo "实验分析流程"
echo "  基线   : $BASE_DIR"
echo "  实验   : $CAND_DIR"
echo "  噪声底线: ±${NOISE}%"
echo "══════════════════════════════════════════════════════════════"
echo

echo "─── ① 稳健统计（基线）───"
python3 tools/robust_stats.py "$BASE_DIR"
echo

echo "─── ② 稳健统计（实验）───"
python3 tools/robust_stats.py "$CAND_DIR"
echo

echo "─── ③ Bootstrap 置信区间（基线）───"
python3 tools/bootstrap_ci.py "$BASE_DIR"/*.json --metric 'p(99)'
echo

echo "─── ④ Bootstrap 置信区间（实验）───"
python3 tools/bootstrap_ci.py "$CAND_DIR"/*.json --metric 'p(99)'
echo

echo "─── ⑤ 显著性检验 ───"
python3 tools/stats_test.py --baseline-dir "$BASE_DIR" --candidate-dir "$CAND_DIR"
echo

echo "─── ⑥ 与噪声底线对比 ───"
python3 - "$BASE_DIR" "$CAND_DIR" "$NOISE" <<'PY'
import json, pathlib, statistics as st, sys

bdir, cdir, noise = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2]), float(sys.argv[3])

def med_p99(d):
    vals = []
    for f in sorted(d.glob("*.json")):
        try:
            vals.append(json.loads(f.read_text())["metrics"]["http_req_duration"]["p(99)"])
        except Exception:
            pass
    return st.median(vals) if vals else None

mb, mc = med_p99(bdir), med_p99(cdir)
if mb and mc:
    delta = (mc - mb) / mb * 100
    mdd = noise * 2
    print(f"基线 P99 中位数 : {mb:.2f} ms")
    print(f"实验 P99 中位数 : {mc:.2f} ms")
    print(f"差异            : {delta:+.2f}%")
    print(f"噪声底线        : ±{noise}%")
    print(f"最小可检测差异   : ±{mdd}%")
    print()
    if abs(delta) < noise:
        print("结论：❌ 差异在噪声范围内 —— 无法确认优化有效")
    elif abs(delta) < mdd:
        print("结论：⚠️  差异超过噪声底线但小于 MDD —— 方向可信，幅度需验证")
    else:
        print("结论：✅ 差异超过最小可检测差异 —— 优化有效，可信")
else:
    print("❌ 无法计算（数据缺失）")
PY

四、动手改造

改动	观察什么
用两组明显不同的数据跑 `stats_test.py`	p 值应该很小（显著）
用两组几乎相同的数据跑	p 值应该很大（不显著）
把轮数从 5 减到 3	置信区间明显变宽——理解"样本量决定精度"
把 `--iters` 从 10000 改成 1000	置信区间会有轻微抖动（重采样次数不足）
在数据里加一个极端异常值	中位数几乎不变，平均值大幅变化——这就是不用平均值的原因

五、这段代码的局限

Mann-Whitney U 用正态近似：样本很小（n < 5）时应该用精确分布表，近似会不够准。
并列值的处理是简化版：大量并列时 p 值会偏保守。
Bootstrap 假设样本能代表总体：如果 5 轮数据本身就有系统性偏差（比如都偏高），Bootstrap 也会偏。
p 值不是一切：它只回答"差异是否可能是偶然"，不回答"差异是否重要"——必须结合噪声底线与用户可感知性（第 5.6、5.7 节）。

配套代码：GC 对比实验与参数确认

Mon, 01 Jan 0001 00:00:00 +0000

7.7 配套代码：GC 对比实验与参数确认

对应小节：7.7 JVM 调优三件事：① 对比不同 GC；② 确认 JVM 实际参数；③ 堆大小与停顿的关系实验。

一、GC 对比实验脚本

#!/usr/bin/env bash
# tools/compare-gc.sh <EXP_ID> [DURATION]
#
# 用同一份代码、同一负载，对比不同 GC 的延迟与吞吐。
#
# ⚠️ 关键：必须同时看延迟（P99）、吞吐（QPS）、CPU——只看延迟会被误导。
set -uo pipefail

EXP_ID="${1:?usage: compare-gc.sh <exp_id> [duration]}"
DURATION="${2:-3m}"
DIR="docs/experiments/${EXP_ID}/results"
mkdir -p "$DIR"

# 要对比的 GC 配置
declare -a CONFIGS=(
  "G1:-XX:+UseG1GC -Xms2g -Xmx2g"
  "ZGC:-XX:+UseZGC -Xms2g -Xmx2g"
  "Parallel:-XX:+UseParallelGC -Xms2g -Xmx2g"
)

echo "═══ GC 对比实验 ═══"
echo "  实验编号: $EXP_ID"
echo "  每配置时长: $DURATION"
echo

tools/collect-env.sh "$EXP_ID" > /dev/null 2>&1 || true
tools/check-environment.sh "$EXP_ID" > /dev/null 2>&1 || true

for ENTRY in "${CONFIGS[@]}"; do
  GC="${ENTRY%%:*}"
  ARGS="${ENTRY#*:}"

  echo "───────── 配置：$GC ─────────"
  echo "  JVM 参数: $ARGS"

  # 启动服务（带 GC 日志）
  JVM_ARGS="$ARGS -Xlog:gc*:file=$DIR/gc-$GC.log:time,uptime,level,tags" \
    scripts/restart-app.sh "$DIR/gc-$GC-console.log" &
  sleep 8

  # 预热（不计入统计）
  BASE_URL=http://127.0.0.1:8080 k6 run --quiet --vus 20 --duration 60s \
    loadtest/profile-constant.js > /dev/null 2>&1

  # 正式测量
  BASE_URL=http://127.0.0.1:8080 RATE=500 DURATION="$DURATION" \
  k6 run --summary-export="$DIR/k6-$GC.json" \
         loadtest/profile-constant.js > /dev/null 2>&1

  # 记录 JVM 实际参数
  PID=$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')
  [ -n "$PID" ] && jcmd "$PID" VM.flags > "$DIR/flags-$GC.txt" 2>/dev/null || true

  # 停止服务
  scripts/stop-app.sh 2>/dev/null || pkill -f app.jar 2>/dev/null || true
  sleep 3

  echo "  ✅ 完成"
  echo
done

echo "═══ 对比结果 ═══"
echo
python3 - "$DIR" <<'PY'
import json, pathlib, re, sys

d = pathlib.Path(sys.argv[1])
configs = ["G1", "ZGC", "Parallel"]

print(f"{'GC':<12}{'QPS':>10}{'P50':>10}{'P95':>10}{'P99':>10}{'错误率':>10}{'GC停顿均值':>12}{'GC次数':>10}")
print("-" * 88)

results = {}
for gc in configs:
    k6 = d / f"k6-{gc}.json"
    gclog = d / f"gc-{gc}.log"
    if not k6.exists():
        print(f"{gc:<12}{'（无数据）':>10}")
        continue

    m = json.loads(k6.read_text())["metrics"]
    dur = m["http_req_duration"]

    # 解析 GC 日志
    pause_avg, pause_count = 0.0, 0
    if gclog.exists():
        pauses = re.findall(r"([\d.]+)ms\s*$", gclog.read_text(errors="ignore"), re.MULTILINE)
        if pauses:
            vals = [float(p) for p in pauses]
            pause_avg = sum(vals) / len(vals)
            pause_count = len(vals)

    results[gc] = {
        "qps": m["http_reqs"]["rate"], "p50": dur["med"], "p95": dur["p(95)"],
        "p99": dur["p(99)"], "err": m["http_req_failed"]["rate"],
        "pause_avg": pause_avg, "pause_count": pause_count,
    }

    print(f"{gc:<12}{m['http_reqs']['rate']:>10.1f}{dur['med']:>10.1f}{dur['p(95)']:>10.1f}"
          f"{dur['p(99)']:>10.1f}{m['http_req_failed']['rate']:>9.2%}"
          f"{pause_avg:>11.2f}ms{pause_count:>10}")

print()
print("判读：")
print("  ⚠️  不要只看延迟！要同时看三个指标：")
print("      ① P99（延迟）② QPS（吞吐）③ GC 停顿（机制验证）")
print()
print("  常见取舍：")
print("      ZGC：停顿最低，但吞吐可能略低、CPU 消耗更高（并发 GC 线程）")
print("      Parallel：吞吐最高，但停顿最长")
print("      G1：折中（默认选择）")
print()
print("  如果某个 GC 的 P99 更好但 QPS 明显下降 → 这个取舍是否值得要看你优化的是哪个指标")
PY

echo
echo "✅ 完成 → $DIR"

二、JVM 参数确认脚本

#!/usr/bin/env bash
# tools/verify-jvm-config.sh [PID]
#
# 确认 JVM 【实际】使用的参数与容器限制——不要相信文档。
set -uo pipefail

PID="${1:-$(jcmd 2>/dev/null | grep app.jar | awk '{print $1}')}"
[ -z "$PID" ] && { echo "❌ 找不到应用进程"; exit 1; }

echo "═══════════════════════════════════════════════════════════════"
echo "JVM 配置确认（PID=$PID）"
echo "═══════════════════════════════════════════════════════════════"
echo

# ── ① 实际 JVM 参数 ────────────────────────────────────────
echo "【① 实际 JVM 参数】"
jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep -E "^(MaxHeapSize|InitialHeapSize|UseG1GC|UseZGC|UseParallelGC|MaxMetaspaceSize|MaxDirectMemorySize|ActiveProcessorCount|HeapDumpOnOutOfMemoryError)" | sed 's/^/  /' || echo "  （无法获取）"
echo

# ── ② 堆大小 vs 容器内存 ────────────────────────────────────
echo "【② 堆大小 vs 容器限制】"
MAX_HEAP_BYTES=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep "^-XX:MaxHeapSize=" | sed 's/.*=//')
if [ -n "$MAX_HEAP_BYTES" ]; then
  MAX_HEAP_MB=$((MAX_HEAP_BYTES / 1048576))
  echo "  JVM 堆上限: ${MAX_HEAP_MB} MB"
fi

if [ -f /sys/fs/cgroup/memory.max ]; then
  MEM_LIMIT=$(cat /sys/fs/cgroup/memory.max)
  if [ "$MEM_LIMIT" != "max" ]; then
    MEM_MB=$((MEM_LIMIT / 1048576))
    echo "  容器内存限制: ${MEM_MB} MB"
    if [ -n "$MAX_HEAP_MB" ]; then
      RATIO=$((MAX_HEAP_MB * 100 / MEM_MB))
      echo "  堆占比: ${RATIO}%"
      if [ "$RATIO" -gt 85 ]; then
        echo "  ❌ 堆占比过高（> 85%）—— 几乎必然 OOMKilled"
        echo "     建议：堆 = 容器限制的 50%~75%（即 $((MEM_MB * 60 / 100)) MB）"
      elif [ "$RATIO" -gt 75 ]; then
        echo "  ⚠️  偏紧 —— 确认堆外内存的实际使用量"
      else
        echo "  ✅ 比例合理"
      fi
    fi
  else
    echo "  容器内存限制: 无限制"
  fi
else
  echo "  （非容器环境）"
fi
echo

# ── ③ CPU 核数识别 ─────────────────────────────────────────
echo "【③ CPU 核数识别】"
echo "  宿主机可见核数（nproc）: $(nproc)"
ACTIVE=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep "ActiveProcessorCount" | sed 's/.*=//')
echo "  JVM 使用的核数（ActiveProcessorCount）: ${ACTIVE:-未设置（JVM 自动检测）}"
if [ -f /sys/fs/cgroup/cpu.max ]; then
  read -r QUOTA PERIOD < /sys/fs/cgroup/cpu.max
  if [ "$QUOTA" != "max" ]; then
    echo "  容器 CPU 限制: $(awk -v q="$QUOTA" -v p="$PERIOD" 'BEGIN{printf "%.2f", q/p}') 核"
    echo "  ⚠️  如果容器限制 < 可见核数，JVM 的线程池/GC 线程数可能过大"
    echo "     建议：-XX:ActiveProcessorCount=<容器限制的核数>"
  fi
fi
echo

# ── ④ 排障必备参数 ─────────────────────────────────────────
echo "【④ 排障必备参数检查】"
FLAGS=$(jcmd "$PID" VM.flags 2>/dev/null)
check_flag() {
  local flag="$1" purpose="$2"
  if echo "$FLAGS" | grep -q "$flag"; then
    echo "  ✅ $flag （$purpose）"
  else
    echo "  ❌ 缺少 $flag （$purpose）"
  fi
}
check_flag "HeapDumpOnOutOfMemoryError" "OOM 时自动 dump"
check_flag "ExitOnOutOfMemoryError" "OOM 时退出（可选）"
echo

# 检查 GC 日志（无法从 VM.flags 看，需要看启动命令）
echo "【⑤ GC 日志】"
if ls /var/log/app/gc*.log /tmp/gc*.log 2>/dev/null | head -1 > /dev/null 2>&1; then
  echo "  ✅ 找到 GC 日志文件"
else
  echo "  ⚠️  未找到 GC 日志 —— 确认启动参数里有 -Xlog:gc*"
  echo "     建议：-Xlog:gc*:file=gc.log:time,uptime,level,tags:filecount=5,filesize=20m"
fi
echo

echo "═══════════════════════════════════════════════════════════════"
echo "结论："
echo "  ① 堆占比是否合理（应 < 75%）"
echo "  ② ActiveProcessorCount 是否与容器限制匹配"
echo "  ③ 排障参数是否齐全（HeapDumpOnOutOfMemoryError 必须有）"
echo "  ④ GC 日志是否开启（调优的眼睛）"
echo "═══════════════════════════════════════════════════════════════"

三、堆大小与停顿的关系实验

# tools/heap-pause-analysis.py <gc.log>
"""
从 GC 日志分析「堆大小与停顿时间」的关系。

用法：
  1. 用不同的 -Xmx 跑同一负载，各自生成 gc.log
  2. 分别跑本脚本，对比结果
"""
import re
import statistics as st
import sys


def parse_gc_log(path):
    """解析 GC 日志，提取停顿信息"""
    pauses = []
    heap_after = []

    with open(path, errors="ignore") as f:
        for line in f:
            # 匹配 Pause Young / Pause Full
            if "Pause" not in line:
                continue

            # 停顿时间（末尾的 XX.XXXms）
            pm = re.search(r"([\d.]+)ms\s*$", line.strip())
            if not pm:
                continue
            pause_ms = float(pm.group(1))

            # 回收前后的堆使用（形如 128M->32M(2048M)）
            hm = re.search(r"(\d+)M->(\d+)M\((\d+)M\)", line)
            if hm:
                before = int(hm.group(1))
                after = int(hm.group(2))
                heap_after.append(after)
            else:
                before = after = None

            # GC 类型
            gc_type = "Young" if "Pause Young" in line else ("Full" if "Pause Full" in line else "Other")

            pauses.append({"pause_ms": pause_ms, "type": gc_type, "after_mb": after})

    return pauses


def main(path):
    pauses = parse_gc_log(path)
    if not pauses:
        print(f"❌ 没有解析到 GC 停顿（{path}）")
        print("   提示：确认 GC 日志格式（-Xlog:gc*:time,uptime）")
        return

    vals = [p["pause_ms"] for p in pauses]
    vals_sorted = sorted(vals)

    print("═" * 70)
    print(f"GC 停顿分析：{path}")
    print("═" * 70)
    print()
    print(f"总停顿次数      : {len(vals)}")
    print(f"停顿总和        : {sum(vals):.1f} ms")
    print(f"平均值          : {st.mean(vals):.2f} ms")
    print(f"中位数          : {st.median(vals):.2f} ms")
    print(f"P95             : {vals_sorted[int(len(vals) * 0.95)]:.2f} ms")
    print(f"P99             : {vals_sorted[int(len(vals) * 0.99)]:.2f} ms")
    print(f"最大值          : {max(vals):.2f} ms")
    print()

    # 按类型统计
    by_type = {}
    for p in pauses:
        by_type.setdefault(p["type"], []).append(p["pause_ms"])
    print("按类型：")
    for t, v in by_type.items():
        print(f"  {t:<8} 次数 {len(v):>5}  平均 {st.mean(v):>7.2f} ms  最大 {max(v):>7.2f} ms")
    print()

    # 老年代基线趋势（泄漏/晋升检查）
    afters = [p["after_mb"] for p in pauses if p["after_mb"]]
    if len(afters) > 10:
        first_q = st.mean(afters[:len(afters) // 4])
        last_q = st.mean(afters[-len(afters) // 4:])
        print("GC 后堆基线趋势：")
        print(f"  前 1/4: {first_q:.0f} MB  →  后 1/4: {last_q:.0f} MB  （{last_q - first_q:+.0f} MB）")
        if last_q > first_q * 1.2:
            print("  ❌ 基线持续抬升 → 可能有内存泄漏或对象晋升过多")
        else:
            print("  ✅ 基线稳定")
        print()

    print("═" * 70)
    print("判读：")
    print("  ① 平均停顿 < 20ms、P99 < 50ms 通常可接受（取决于你的 SLO）")
    print("  ② 出现 Full GC → 必须查明（配置问题或泄漏）")
    print("  ③ 停顿次数太多（几秒一次）→ 分配速率太高（先去降分配，不是调 GC）")
    print("  ④ 对比不同 -Xmx 的同一份日志：")
    print("     堆大 → 停顿次数少但单次更长")
    print("     对延迟敏感的服务，【单次停顿时长】比频率更重要")
    print("═" * 70)


if __name__ == "__main__":
    main(sys.argv[1] if len(sys.argv) > 1 else "gc.log")

四、动手改造

改动	观察什么
用 `compare-gc.sh` 对比 G1 与 ZGC	同时看 P99、QPS、GC 停顿——体会「只看延迟会被误导」
把 `-Xmx` 从 2g 改成 8g 再跑	停顿次数下降但单次变长（用 `heap-pause-analysis.py` 对比）
用 `verify-jvm-config.sh` 检查你的服务	大概率会发现「堆占比过高」或「缺 HeapDumpOnOutOfMemoryError」
在容器里跑 `nproc` 并与 `cpu.max` 对比	会发现「以为有 8 核，实际只有 1 核」的陷阱
故意把 `-Xmx` 设成容器内存 limit	触发 OOMKilled（用 `kubectl describe pod` 验证）

五、这段代码的局限

compare-gc.sh 需要足够的压测时长：GC 效果要覆盖多个 GC 周期，建议每配置至少 3–5 分钟。
GC 日志格式因 JDK 版本而异：本脚本的正则适配了常见的 Pause Young ... XX.XXXms 格式，其他格式可能需要调整。
heap-pause-analysis.py 的堆基线趋势只在「同一份配置内」有意义：跨配置对比要看绝对值。
JVM 调优的效果需要长期观测：3 分钟的压测可能不够——最终验证应该在真实流量或长时间浸泡下进行。
verify-jvm-config.sh 的「堆占比 < 75%」是经验值：具体取决于堆外内存的实际使用（Netty、直接内存、线程数）。

配套代码：优化、验证与否决

Mon, 01 Jan 0001 00:00:00 +0000

9.7 配套代码：优化、验证与否决

对应小节：9.7 步骤六：优化与验证

一、优化清单与顺序（先算，再改）

#!/usr/bin/env python3
"""tools/step6a-plan.py —— 按金字塔排序优化项

第 7.1 节的优先级金字塔：
  ① 去掉不必要的工作（最大收益、最小风险）
  ② 减少工作量的算法/数据结构改进
  ③ 减少等待（并发/池/批量化）
  ④ 让剩下的更快（微优化、JIT 调参）
  ⑤ 加资源（最后一招）

本 Lab 的排序（算出「预期收益 / 风险」后得出）：
"""
import json
import pathlib

PLAN = [
    {
        "order": 1,
        "name": "给 code 加唯一索引",
        "layer": "① 去掉不必要的工作",
        "why": "Seq Scan 扫描 100 万行只为找 1 行 —— 99.9999% 是纯粹浪费",
        "expected": "P99 420.5ms → 45ms（依赖级 380ms → ~2ms）",
        "risk": "极低（一条 DDL；CONCURRENTLY 建索引不锁表）",
        "cost": "5 分钟",
        "single_variable": "只加索引，其他一律不动",
    },
    {
        "order": 2,
        "name": "阻塞调用切到 Dispatchers.IO + Semaphore 限流",
        "layer": "③ 减少等待（隔离）",
        "why": "JDBC 阻塞占满 Default 调度器（并行度=核数），"
               "导致不查库的 /health 也慢",
        "expected": "/health P99 380ms → 8ms（其他接口也跟着稳）",
        "risk": "低（但需限流，否则 IO 池会被打爆）",
        "cost": "30 分钟",
        "single_variable": "只切调度器 + 限流，不碰索引/日志",
    },
    {
        "order": 3,
        "name": "日志异步化 + 降级 + 参数化",
        "layer": "① 去掉不必要的工作",
        "why": "热路径 INFO 日志（含完整 UA/IP）同步写盘，"
               "wall 中占 6.1%",
        "expected": "P99 改善约 5%（45ms → 42.7ms）",
        "risk": "极低（异步 appender + 去掉 UA/IP）",
        "cost": "20 分钟",
        "single_variable": "只改日志",
    },
    {
        "order": 4,
        "name": "synchronized → Mutex（或去掉锁）",
        "layer": "② 减少工作量 / ③ 减少等待",
        "why": "线程级锁在协程里会跨越挂起点；写路径偶发 BLOCKED",
        "expected": "写接口 P99 改善约 1.2%",
        "risk": "中（改锁容易引入并发 bug，需要压测验证）",
        "cost": "1 小时",
        "single_variable": "只改锁",
    },
    {
        "order": 5,
        "name": "缓存 TTL 加抖动（±20%）",
        "layer": "③ 减少等待（削峰）",
        "why": "固定 TTL 导致周期性缓存雪崩（埋雷 ③）",
        "expected": "消除浸泡时的 DB QPS 脉冲（P99 未必改善，"
                    "但尖刺消失）",
        "risk": "极低",
        "cost": "10 分钟",
        "single_variable": "只改 TTL 策略",
    },
]

REJECTED = [
    {
        "name": "异步批量 UPDATE hits",
        "layer": "③ 减少等待（批量化）",
        "measured_gain": "2.1%",
        "mdd": "11.8%",
        "reason": "2.1% < MDD 11.8% —— 统计上无法区分于噪声",
        "extra_cost": "引入最终一致性：hits 会滞后；"
                      "需处理进程崩溃时的计数丢失；需额外的批量队列",
        "decision": "❌ 否决",
        "revisit_when": "当 hits 写入成为 top1 瓶颈时（当前排第 3）",
    },
    {
        "name": "加 Redis 做二级缓存",
        "layer": "① 去掉不必要的工作",
        "measured_gain": "未测（估算 5%~10%）",
        "mdd": "11.8%",
        "reason": "本地 Caffeine 命中率已达 75%，"
                  "剩余 25% 中大部分是【长尾冷 key】（幂律分布）——"
                  "Redis 也缓存不住",
        "extra_cost": "新增一个依赖（可用性风险）；"
                      "网络往返约 0.5ms；运维成本；"
                      "缓存一致性复杂度",
        "decision": "❌ 否决",
        "revisit_when": "当需要多实例共享缓存（水平扩展）时",
    },
]


def main(out: str) -> int:
    d = pathlib.Path(out)
    d.mkdir(parents=True, exist_ok=True)

    print("═══ 优化计划（按金字塔排序）═══\n")
    for p in PLAN:
        print(f"{p['order']}. {p['name']}")
        print(f"   层次：{p['layer']}")
        print(f"   理由：{p['why']}")
        print(f"   预期：{p['expected']}")
        print(f"   风险：{p['risk']}　成本：{p['cost']}")
        print(f"   ⚠️  单变量：{p['single_variable']}")
        print()

    print("═══ 被否决的方案 ═══\n")
    for r in REJECTED:
        print(f"{r['decision']}  {r['name']}")
        print(f"   层次：{r['layer']}")
        print(f"   实测收益：{r['measured_gain']}　MDD：{r['mdd']}")
        print(f"   否决理由：{r['reason']}")
        print(f"   额外代价：{r['extra_cost']}")
        print(f"   重新评估条件：{r['revisit_when']}")
        print()

    # ── 关键纪律检查 ──
    print("═══ 纪律检查 ═══")
    print()
    print("✅ 每一项都写了「单变量」约束")
    print("✅ 被否决的方案都记录了理由与重新评估条件")
    print("✅ 排序依据是「金字塔层次」，不是「我觉得哪个好改」")
    print()
    print("⚠️  没有记录「为什么不做 X」的报告 = 看起来像没考虑过备选")

    (d / "optimization-plan.json").write_text(json.dumps(
        {"plan": PLAN, "rejected": REJECTED}, indent=2, ensure_ascii=False))
    print(f"\n✅ 计划 → {d}/optimization-plan.json")
    return 0


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1
                  else "perf/results/step6-optimize"))

二、优化 1：加唯一索引

-- perf/sql/02-add-code-index.sql
-- ═══ 优化 1：把 Seq Scan 变成 Index Scan ═══

-- 【关键】用 CONCURRENTLY 避免锁表
-- 普通 CREATE INDEX 会持有 SHARE 锁，阻塞所有写操作
-- CONCURRENTLY 的代价：更慢（要扫两遍表），但线上安全
CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS idx_links_code
    ON links (code);

-- 建完后必须 ANALYZE，否则 Planner 可能仍选 Seq Scan
ANALYZE links;

-- ── 验证 ──
-- 预期：Index Scan / Index Only Scan，Execution Time < 1ms
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, code, url, user_id, created_at, hits
FROM links WHERE code = 'aB3xK9';

预期输出：

配套代码：协程开销与调度器饥饿实验

Mon, 01 Jan 0001 00:00:00 +0000

2.7 配套代码：协程开销与调度器饥饿实验

对应小节：2.7 协程的真实开销模型 第二个实验是本章最重要的一个：它让你亲眼看到「阻塞调用污染调度器」造成的全局卡顿。

一、实验一：协程的成本

// src/main/kotlin/lesson02/CoroutineCost.kt
package lesson02

import kotlinx.coroutines.*
import kotlin.system.measureNanoTime

private var sink = 0L

suspend fun noopSuspend(): Int = 1                    // 不真正挂起

suspend fun realSuspend(): Int = withContext(Dispatchers.IO) { 1 }   // 真正切换线程

fun main() = runBlocking {
    val n = 200_000

    fun bench(label: String, body: () -> Unit): Double {
        repeat(n / 4) { body() }
        val ns = measureNanoTime { repeat(n) { body() } }
        val per = ns.toDouble() / n
        println("%-44s %10.1f ns/op".format(label, per))
        return per
    }

    println("=== 协程相关操作的成本 ===")
    val plain = bench("普通函数调用") { sink += 1 }
    val suspendNoop = bench("suspend 函数（不真正挂起）") { sink += runBlocking { noopSuspend() } }
    val dispatch = bench("真正挂起：withContext(IO)") { sink += runBlocking { realSuspend() } }
    val thread = bench("线程创建 + join") {
        val t = Thread { }
        t.start(); t.join()
    }

    println()
    println("=== 结论 ===")
    println("suspend（不挂起）vs 普通调用 : %.1f 倍".format(suspendNoop / plain))
    println("真正挂起 vs 普通调用         : %.1f 倍".format(dispatch / plain))
    println("线程创建 vs 真正挂起         : %.0f 倍".format(thread / dispatch))
    println()
    println("注意：这里的 runBlocking 本身也有开销（它是被测的一部分）。")
    println("      严格的测量需要把 runBlocking 的空壳作为对照组单独测。")
    println()
    println("sink = $sink")
}

预期形态：

配套代码：噪声底线测量与回归门禁

Mon, 01 Jan 0001 00:00:00 +0000

5.7 配套代码：噪声底线测量与回归门禁

对应小节：5.7 噪声底线与回归检测 这是本章最重要的一份代码。 它产出你后续所有实验的标尺。

一、噪声底线测量流程

#!/usr/bin/env bash
# tools/noise-floor.sh <EXP_ID> [ROUNDS] [RATE] [DURATION]
#
# 测量噪声底线：代码完全不变，重复 N 轮实验。
#
# 关键要求：
#   ① 代码一字不改
#   ② 每轮都重启服务（确保同一初始状态）
#   ③ 每轮都独立预热（不计入统计）
#   ④ 至少 5 轮（推荐 10 轮）
set -euo pipefail

EXP_ID="${1:?usage: noise-floor.sh <EXP_ID> [rounds] [rate] [duration]}"
ROUNDS="${2:-10}"
RATE="${3:-500}"
DURATION="${4:-5m}"
DIR="docs/experiments/${EXP_ID}"
mkdir -p "$DIR/results" "$DIR/scripts"

echo "═══ 噪声底线测量 ═══"
echo "  实验编号 : $EXP_ID"
echo "  轮数     : $ROUNDS"
echo "  负载     : $RATE req/s × $DURATION"
echo "  ⚠️  请确认：代码未改动、环境已按第 5.4 节检查"
echo

# ① 环境检查
tools/check-environment.sh "$EXP_ID" || true

# ② 冻结脚本
cp loadtest/*.js "$DIR/scripts/" 2>/dev/null || true

# ③ 启动环境事件记录（用于解释异常轮）
tools/record-events.sh "$EXP_ID" 10 &
EVENTS_PID=$!
trap 'kill $EVENTS_PID 2>/dev/null || true' EXIT

# ④ 记录代码状态（必须干净）
{
  echo "commit=$(git rev-parse HEAD)"
  echo "git_dirty_files=$(git status --porcelain | wc -l | tr -d ' ')"
} | tee "$DIR/results/code-state.txt"

DIRTY=$(git status --porcelain | wc -l | tr -d ' ')
if [ "$DIRTY" -gt 0 ]; then
  echo "❌ 工作区有未提交改动（$DIRTY 个文件）—— 噪声底线必须在干净代码上测"
  exit 1
fi

# ⑤ 跑 N 轮
echo
for i in $(seq 1 "$ROUNDS"); do
  echo "───────── 第 $i / $ROUNDS 轮 ─────────"

  # 重启服务（关键！）
  scripts/restart-app.sh "$DIR/results/gc-$i.log"
  sleep 5

  # 独立预热（不计入统计）
  BASE_URL=http://127.0.0.1:8080 k6 run --quiet --vus 20 --duration 60s \
    loadtest/profile-constant.js > /dev/null
  echo "  预热完成"

  # 正式测量
  BASE_URL=http://127.0.0.1:8080 RATE="$RATE" DURATION="$DURATION" \
  k6 run --summary-export="$DIR/results/round-$i.json" \
         loadtest/profile-constant.js > "$DIR/results/round-$i-stdout.txt" 2>&1

  # 打印本轮关键值
  python3 - "$DIR/results/round-$i.json" <<'PY'
import json, sys
m = json.load(open(sys.argv[1]))["metrics"]
d = m["http_req_duration"]
print(f"  QPS={m['http_reqs']['rate']:.1f}  P50={d['med']:.1f}  P95={d['p(95)']:.1f}  "
      f"P99={d['p(99)']:.1f}  错误率={m['http_req_failed']['rate']:.2%}")
PY
done

kill $EVENTS_PID 2>/dev/null || true

echo
echo "═══ 测量完成，开始分析 ═══"
python3 tools/noise_floor.py "$DIR/results"

二、噪声底线计算与 MDD 推导

# tools/noise_floor.py <results_dir>
"""
计算噪声底线与最小可检测差异（MDD）。

核心逻辑：
  ① 从 N 轮数据里算出每个指标的波动范围（最大偏离中位数的百分比）
  ② 噪声底线 = 波动范围 × 1.5（安全系数）
  ③ MDD = 噪声底线 × 2（因为两组数据相减，噪声叠加）
  ④ 检查是否存在趋势漂移（单调上升/下降）
"""
import json
import pathlib
import statistics as st
import sys


def load_rounds(d):
    rounds = []
    for f in sorted(pathlib.Path(d).glob("round-*.json")):
        try:
            m = json.loads(f.read_text())["metrics"]
            dr = m["http_req_duration"]
            rounds.append({
                "file": f.name,
                "qps": m["http_reqs"]["rate"],
                "p50": dr.get("med", 0),
                "p95": dr.get("p(95)", 0),
                "p99": dr.get("p(99)", 0),
                "err": m["http_req_failed"]["rate"],
            })
        except Exception as e:
            print(f"⚠️  跳过 {f}: {e}")
    return rounds


def trend(values):
    """判断是否有单调趋势：返回 (斜率方向, 相关系数绝对值)"""
    n = len(values)
    if n < 3:
        return "样本不足", 0.0
    xs = list(range(n))
    mx, my = sum(xs) / n, sum(values) / n
    num = sum((x - mx) * (y - my) for x, y in zip(xs, values))
    den_x = sum((x - mx) ** 2 for x in xs)
    den_y = sum((y - my) ** 2 for y in values)
    if den_x == 0 or den_y == 0:
        return "无趋势", 0.0
    slope = num / den_x
    r = abs(num / ((den_x * den_y) ** 0.5))
    direction = "上升" if slope > 0 else "下降"
    return f"{direction}（r={r:.2f}）", r


def analyze(rounds):
    if len(rounds) < 3:
        print("❌ 至少需要 3 轮数据（推荐 5–10 轮）")
        return None

    print("═" * 76)
    print(f"噪声底线分析（{len(rounds)} 轮，代码未改动）")
    print("═" * 76)
    print()

    # 逐轮列出
    print(f"{'轮次':<5}{'QPS':>10}{'P50':>10}{'P95':>10}{'P99':>10}{'错误率':>10}  备注")
    for i, r in enumerate(rounds, 1):
        print(f"{i:<5}{r['qps']:>10.1f}{r['p50']:>10.1f}{r['p95']:>10.1f}{r['p99']:>10.1f}{r['err']:>10.2%}")
    print()

    # 计算波动范围
    print(f"{'指标':<8}{'中位数':>10}{'最小':>10}{'最大':>10}{'波动范围':>12}{'CV':>8}  趋势")
    print("-" * 76)

    results = {}
    for key, label in [("qps", "QPS"), ("p50", "P50"), ("p95", "P95"), ("p99", "P99")]:
        vals = [r[key] for r in rounds]
        med = st.median(vals)
        lo, hi = min(vals), max(vals)
        # 波动范围：取偏离中位数较大的一侧
        swing = max(abs(hi - med), abs(med - lo)) / med * 100 if med else 0
        cv = st.stdev(vals) / med * 100 if len(vals) > 1 and med else 0
        tr, r = trend(vals)
        results[key] = {"median": med, "swing": swing, "cv": cv, "trend_r": r, "values": vals}
        print(f"{label:<8}{med:>10.2f}{lo:>10.2f}{hi:>10.2f}{swing:>11.1f}%{cv:>7.1f}%  {tr}")
    print()

    # 噪声底线与 MDD
    print("═" * 76)
    print("噪声底线（波动范围 × 1.5 安全系数）与最小可检测差异（MDD = 噪声底线 × 2）")
    print("═" * 76)
    print()
    print(f"{'指标':<8}{'波动范围':>12}{'噪声底线':>12}{'MDD':>12}   含义")
    print("-" * 76)
    for key, label in [("qps", "QPS"), ("p50", "P50"), ("p95", "P95"), ("p99", "P99")]:
        r = results[key]
        noise = r["swing"] * 1.5
        mdd = noise * 2
        meaning = f"声称改善 < {mdd:.0f}% 无法证实"
        print(f"{label:<8}{r['swing']:>11.1f}%{noise:>11.1f}%{mdd:>11.1f}%   {meaning}")
    print()

    # 质量评估
    print("═" * 76)
    print("环境质量评估")
    print("═" * 76)
    print()
    max_cv = max(r["cv"] for r in results.values())
    p99_cv = results["p99"]["cv"]

    if p99_cv < 3:
        print(f"✅ P99 的轮间 CV = {p99_cv:.1f}% —— 环境很干净")
        print("   → 可以检测 5% 级别的差异（但仍需统计检验确认）")
    elif p99_cv < 5:
        print(f"✅ P99 的轮间 CV = {p99_cv:.1f}% —— 环境可接受")
        print("   → 可以检测 10% 级别的差异")
    elif p99_cv < 10:
        print(f"⚠️  P99 的轮间 CV = {p99_cv:.1f}% —— 环境噪声偏大")
        print("   → 只能判断 20% 以上的差异；建议先改善环境")
    else:
        print(f"❌ P99 的轮间 CV = {p99_cv:.1f}% —— 环境噪声过大")
        print("   → 任何结论都不可信；必须先修环境（第 5.4 节）")
    print()

    # 趋势漂移检查
    print("趋势漂移检查（单调上升/下降说明环境在变，不是噪声）：")
    drift_found = False
    for key, label in [("qps", "QPS"), ("p50", "P50"), ("p95", "P95"), ("p99", "P99")]:
        r = results[key]
        if r["trend_r"] > 0.7:
            drift_found = True
            print(f"  ❌ {label}: 存在明显趋势（r={r['trend_r']:.2f}）")
            print(f"     值 = {[round(v, 1) for v in r['values']]}")
            print(f"     → 可能原因：数据量增长 / 缓存污染 / 内存泄漏 / 机器降频")
            print(f"     → 必须先解决漂移，再重测噪声底线")
    if not drift_found:
        print("  ✅ 未检测到趋势漂移")
    print()

    print("═" * 76)
    print("如何使用这个结果：")
    print("═" * 76)
    print()
    print("  ① 写进实验档案（docs/experiments/E0x-noise/README.md）")
    print("  ② 后续任何优化实验，都拿它的差异与这里的 MDD 对比")
    print("  ③ CI 门禁阈值 = 噪声底线 × 1.5~2（不能直接等于噪声底线）")
    print("  ④ 每季度或环境重大变更后重测")
    print("═" * 76)

    return results


if __name__ == "__main__":
    d = sys.argv[1] if len(sys.argv) > 1 else "docs/experiments/E05-noise/results"
    analyze(load_rounds(d))

三、预期输出

════════════════════════════════════════════════════════════════════════════
噪声底线分析（10 轮，代码未改动）
════════════════════════════════════════════════════════════════════════════

轮次        QPS       P50       P95       P99     错误率  备注
1         498.2      32.1      68.4      93.2     0.00%
2         499.1      33.0      70.2      96.1     0.00%
3         497.5      32.4      67.9      94.0     0.00%
4         498.8      34.2      74.1     103.5     0.00%
5         499.4      32.8      69.3      95.2     0.00%
...

指标         中位数        最小        最大      波动范围      CV  趋势
----------------------------------------------------------------------------
QPS         498.80     497.50     499.70        0.2%     0.1%  无趋势
P50          32.80      32.10      34.20        4.3%     1.8%  无趋势
P95          69.20      67.90      74.10        7.1%     2.7%  无趋势
P99          95.10      93.20     103.50        8.8%     3.1%  无趋势

════════════════════════════════════════════════════════════════════════════
噪声底线（波动范围 × 1.5 安全系数）与最小可检测差异（MDD = 噪声底线 × 2）
════════════════════════════════════════════════════════════════════════════

指标         波动范围      噪声底线         MDD   含义
----------------------------------------------------------------------------
QPS             0.2%        0.3%        0.7%   声称改善 < 1% 无法证实
P50             4.3%        6.5%       13.0%   声称改善 < 13% 无法证实
P95             7.1%       10.7%       21.4%   声称改善 < 21% 无法证实
P99             8.8%       13.2%       26.4%   声称改善 < 26% 无法证实

════════════════════════════════════════════════════════════════════════════
环境质量评估
════════════════════════════════════════════════════════════════════════════

✅ P99 的轮间 CV = 3.1% —— 环境可接受
   → 可以检测 10% 级别的差异

这份输出最重要的两个数字：

配套代码：容量计算、复测与告警

Mon, 01 Jan 0001 00:00:00 +0000

8.7 配套代码：容量计算、复测与告警

对应小节：8.7 容量规划三部分：① 容量计算器（含约束检查）；② 简化复测脚本；③ 容量告警。

一、容量计算器（含非线性约束检查）

# tools/capacity-planner.py <capacity-input.json>
"""
从拐点计算所需副本数，并检查非线性约束。

输入格式见文件末尾的示例。
"""
import json
import math
import sys


def plan(data):
    print("═" * 84)
    print(f"容量规划：{data.get('service', 'app')}")
    print("═" * 84)
    print()

    knee = data["knee_qps"]
    headroom = data.get("headroom", 0.4)
    peak = data["peak_qps"]
    redundancy = data.get("redundancy", 1)
    spec = data.get("instance_spec", "?")
    constraints = data.get("constraints", {})

    # ── ① 基础计算 ──────────────────────────────────────────
    safe_capacity = int(knee * (1 - headroom))
    replicas = math.ceil(peak / safe_capacity) + redundancy

    print("【基础计算】")
    print(f"  实例规格        : {spec}")
    print(f"  拐点（实测）     : {knee} RPS")
    print(f"  headroom        : {headroom:.0%}")
    print(f"  单实例安全容量   : {safe_capacity} RPS")
    print(f"  峰值需求        : {peak} RPS")
    print(f"  所需副本（含 {redundancy} 台冗余）: {replicas}")
    print()

    # ── ② 约束检查（非线性因素）────────────────────────────
    print("【约束检查】⭐ 这一步常常否掉最优方案")
    problems = []

    # 数据库连接数
    if "db_max_connections" in constraints:
        pool_per_instance = constraints.get("pool_per_instance", 30)
        total_conn = replicas * pool_per_instance
        db_max = constraints["db_max_connections"]
        reserve = constraints.get("reserve_connections", 5)
        available = db_max - reserve

        print(f"  数据库连接数：")
        print(f"    {replicas} 实例 × {pool_per_instance} 池 = {total_conn}")
        print(f"    数据库上限 {db_max}（留 {reserve} 给运维）→ 可用 {available}")
        if total_conn > available:
            max_pool = available // replicas
            problems.append(
                f"连接数超出：需要 {total_conn}，可用 {available}\n"
                f"      → 每实例池降到 {max_pool}，或引入 PgBouncer，或减少副本数")
            print(f"    ❌ 超出！每实例池应 ≤ {max_pool}")
        else:
            print(f"    ✅ 余量 {available - total_conn}")
    print()

    # 共享缓存
    if "redis_max_qps" in constraints:
        cache_qps_factor = constraints.get("cache_qps_per_request", 2.0)
        cache_qps = peak * cache_qps_factor
        redis_max = constraints["redis_max_qps"]
        print(f"  共享 Redis：")
        print(f"    峰值 {peak} × 每请求 {cache_qps_factor} 次 = {cache_qps:.0f} QPS")
        print(f"    Redis 上限 {redis_max} QPS")
        if cache_qps > redis_max * 0.8:
            problems.append(f"Redis 接近上限（{cache_qps:.0f} / {redis_max}）")
            print(f"    ⚠️  接近上限")
        else:
            print(f"    ✅ 余量 {redis_max - cache_qps:.0f}")
    print()

    # 下游服务
    if "downstream_qps_limit" in constraints:
        factor = constraints.get("downstream_calls_per_request", 1.0)
        downstream_qps = peak * factor
        limit = constraints["downstream_qps_limit"]
        print(f"  下游服务：")
        print(f"    峰值 {peak} × 每请求 {factor} 次 = {downstream_qps:.0f} QPS")
        print(f"    下游上限 {limit} QPS")
        if downstream_qps > limit:
            problems.append(f"下游会被打垮（{downstream_qps:.0f} > {limit}）")
            print(f"    ❌ 超出！需要限流或缓存")
        else:
            print(f"    ✅")
    print()

    # 负载均衡上限
    if "lb_max_connections" in constraints:
        conn_per_instance = constraints.get("connections_per_instance", 1000)
        total = replicas * conn_per_instance
        lb_max = constraints["lb_max_connections"]
        print(f"  负载均衡连接数：{replicas} × {conn_per_instance} = {total}（上限 {lb_max}）")
        if total > lb_max:
            problems.append(f"负载均衡连接数超出（{total} > {lb_max}）")
            print(f"    ❌ 超出")
        else:
            print(f"    ✅")
    print()

    # ── ③ 数据量增长的影响 ──────────────────────────────────
    growth = data.get("data_growth_per_quarter", 0.3)
    if growth > 0:
        print("【数据量增长的影响】")
        print(f"  每季度数据增长 {growth:.0%}")
        print(f"  经验值：数据量翻倍时拐点下降 10%~20%")
        quarters = data.get("planning_horizon_quarters", 4)
        # 假设数据每季度增长 growth，拐点按 -15% per doubling 衰减
        import math as m
        doublings = m.log(1 + growth * quarters, 2) if growth > 0 else 0
        knee_after = knee * (1 - 0.15) ** doublings
        safe_after = int(knee_after * (1 - headroom))
        replicas_after = math.ceil(peak / safe_after) + redundancy
        print(f"  {quarters} 个季度后：拐点约 {knee_after:.0f} RPS，"
              f"所需副本约 {replicas_after} 台（当前 {replicas} 台）")
        print(f"  → 建议提前规划扩容")
    print()

    # ── ④ 结论 ──────────────────────────────────────────────
    print("═" * 84)
    if problems:
        print(f"❌ 存在 {len(problems)} 项约束冲突：")
        for p in problems:
            print(f"   - {p}")
        print()
        print("解决方案（按优先级）：")
        print("  ① 优化代码/查询（降低单请求资源消耗 → 拐点上升）")
        print("  ② 加缓存（降低对数据库/下游的压力）")
        print("  ③ 引入连接池代理（PgBouncer 等）")
        print("  ④ 提高单实例规格（减少副本数 → 减少总连接数）")
        print("  ⑤ 减少副本数 + 接受更低的安全容量（谨慎）")
    else:
        print("✅ 所有约束检查通过")
        print()
        print("最终建议：")
        print(f"  实例规格  : {spec}")
        print(f"  副本数    : {replicas}（含 {redundancy} 台冗余）")
        print(f"  安全容量  : {safe_capacity} RPS/实例，共 {safe_capacity * replicas} RPS")
        print(f"  峰值利用率: {peak / (safe_capacity * replicas):.0%}")
    print("═" * 84)

    return 1 if problems else 0


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(__doc__)
        print()
        print("示例输入：")
        print(json.dumps({
            "service": "orders-api",
            "instance_spec": "4C8G",
            "knee_qps": 900,
            "headroom": 0.4,
            "peak_qps": 3000,
            "redundancy": 1,
            "data_growth_per_quarter": 0.3,
            "planning_horizon_quarters": 4,
            "constraints": {
                "db_max_connections": 100,
                "reserve_connections": 5,
                "pool_per_instance": 30,
                "redis_max_qps": 50000,
                "cache_qps_per_request": 2.0,
                "downstream_qps_limit": 5000,
                "downstream_calls_per_request": 1.5,
                "lb_max_connections": 20000,
                "connections_per_instance": 1000,
            },
        }, ensure_ascii=False, indent=2))
        sys.exit(0)

    data = json.loads(open(sys.argv[1], encoding="utf-8").read())
    sys.exit(plan(data))

预期输出（含约束冲突）：

配套代码：层级选择辅助与测试预算计算

Mon, 01 Jan 0001 00:00:00 +0000

3.7 配套代码：层级选择辅助与测试预算计算

对应小节：3.7 层级选择与成本两件小工具：① 层级选择辅助（把你的问题映射到层级）；② 测试成本计算（量化"为什么先做组件基准"）。

一、层级选择辅助

// src/main/kotlin/selection/LevelSelector.kt
package selection

enum class TestLevel(val label: String, val minutesPerRun: Int, val needsFullEnv: Boolean) {
    MICRO("微基准（JMH）", 1, false),
    COMPONENT("组件基准（Testcontainers）", 1, false),
    INTEGRATION("集成基准（单服务完整启动）", 5, false),
    E2E("全链路负载", 40, true),
    SOAK("浸泡测试", 120, true),
    CAPACITY("容量测试", 180, true),
}

/** 问题类型 → 该用哪一层 */
enum class QuestionType(val phrase: String, val levels: List<TestLevel>) {
    CODE_SPEED("这段代码/算法快不快？", listOf(TestLevel.MICRO)),
    DATA_ACCESS("这条 SQL / 序列化 / 缓存操作慢不慢？", listOf(TestLevel.COMPONENT)),
    SINGLE_SERVICE("单个服务完整处理一个请求要多久？", listOf(TestLevel.COMPONENT, TestLevel.INTEGRATION)),
    SLO("满足 SLO 吗？拐点在哪？", listOf(TestLevel.E2E)),
    CAPACITY_PLAN("要几个副本？什么规格？", listOf(TestLevel.CAPACITY, TestLevel.E2E)),
    LEAK("有没有内存/连接泄漏？", listOf(TestLevel.SOAK)),
    RESILIENCE("系统垮了会怎样？能自愈吗？", listOf(TestLevel.E2E)),
    WHY_SLOW("为什么慢？（还不知道哪里慢）", emptyList()),   // 特殊：先剖析
}

data class Recommendation(
    val question: QuestionType,
    val levels: List<TestLevel>,
    val note: String,
)

fun recommend(question: QuestionType): Recommendation {
    if (question == QuestionType.WHY_SLOW) {
        return Recommendation(
            question = question,
            levels = listOf(TestLevel.COMPONENT, TestLevel.MICRO),
            note = "⚠️ 先做剖析（火焰图 / JFR / 线程 dump）定位，再用上面这些层级做验证。" +
                   "「为什么慢」不要用压测来回答。"
        )
    }
    return Recommendation(question, question.levels, "")
}

/** 成本估算：一天能做几轮 */
fun roundsPerDay(level: TestLevel, hoursPerDay: Double = 6.0): Int {
    val overhead = if (level.needsFullEnv) 20 else 2      // 环境准备与数据准备的额外开销（分钟）
    val perRun = level.minutesPerRun + overhead
    return (hoursPerDay * 60 / perRun).toInt()
}

fun main() {
    println("=== 问题 → 层级映射 ===\n")
    QuestionType.entries.forEach { q ->
        val r = recommend(q)
        println("「${q.phrase}」")
        println("  → 层级：${r.levels.joinToString(" + ") { it.label }}")
        if (r.note.isNotEmpty()) println("  ${r.note}")
        println()
    }

    println("=== 成本：一天能做几轮实验（按 6 小时有效工作时间）===\n")
    println("%-34s %10s %14s".format("层级", "单次耗时", "一天可做轮次"))
    println("-".repeat(62))
    TestLevel.entries.forEach { level ->
        println("%-34s %8d 分 %12d 轮".format(level.label, level.minutesPerRun, roundsPerDay(level)))
    }
    println()
    println("结论：全链路一天只能试 2~5 个假设，组件基准能试几十个。")
    println("      假设验证次数直接决定你找到正确解的概率 —— 这就是「先用组件基准」的真正理由。")
}

预期输出：

配套代码：数据库、连接池与缓存观测

Mon, 01 Jan 0001 00:00:00 +0000

4.7 配套代码：数据库、连接池与缓存观测

对应小节：4.7 数据与中间件观测核心：先区分「等连接」和「查询慢」，再决定优化方向。

一、PostgreSQL：四个必开配置

# postgresql.conf

# ① 语句统计（必须！否则无法知道哪条 SQL 最贵）
shared_preload_libraries = 'pg_stat_statements, auto_explain'
pg_stat_statements.max = 10000
pg_stat_statements.track = all
pg_stat_statements.track_planning = on

# ② 自动记录慢查询的执行计划（生产最有价值的配置之一）
auto_explain.log_min_duration = '200ms'
auto_explain.log_analyze = on
auto_explain.log_buffers = on
auto_explain.log_verbose = on
auto_explain.log_format = 'text'
auto_explain.sample_rate = 0.1        # 只记录 10% 的慢查询，避免日志爆炸

# ③ 记录锁等待
log_lock_waits = on
deadlock_timeout = '1s'

# ④ 慢查询日志（作为兜底）
log_min_duration_statement = '500ms'

auto_explain 是最值得开的一项：它让「慢查询」自动带上执行计划，不用等你复现。

二、四个诊断查询（放在一个 SQL 文件里）

-- tools/pg-diagnostics.sql

-- ═══════════════════════════════════════════════════════════
-- ① 最贵的语句（同时看 calls 和 total，防止漏掉 N+1）
-- ═══════════════════════════════════════════════════════════
SELECT
    calls,
    round(total_exec_time::numeric, 1)  AS total_ms,
    round(mean_exec_time::numeric, 2)   AS mean_ms,
    round((100 * total_exec_time / sum(total_exec_time) OVER ())::numeric, 1) AS pct_of_total,
    rows,
    left(regexp_replace(query, '\s+', ' ', 'g'), 70) AS query
FROM pg_stat_statements
WHERE query NOT LIKE '%pg_stat_statements%'
ORDER BY total_exec_time DESC
LIMIT 20;

-- ⭐ 读法：
--   高 calls + 低 mean  → N+1（总量大）
--   低 calls + 高 mean  → 单条慢查询（缺索引）
--   两者都高           → 最优先处理

-- ═══════════════════════════════════════════════════════════
-- ② 现在谁在等什么（wait_event_type 是最有价值的一列）
-- ═══════════════════════════════════════════════════════════
SELECT
    pid,
    round(extract(epoch from (now() - query_start))::numeric, 1) AS duration_s,
    state,
    wait_event_type,          -- Lock / IO / Client / LWLock / Timeout
    wait_event,
    left(regexp_replace(query, '\s+', ' ', 'g'), 60) AS query
FROM pg_stat_activity
WHERE state <> 'idle'
  AND pid <> pg_backend_pid()
ORDER BY duration_s DESC NULLS LAST
LIMIT 20;

-- ⭐ 读法：
--   wait_event_type=Lock    → 等锁（查下面的阻塞链）
--   wait_event_type=IO      → 等磁盘（查索引与缓存命中）
--   wait_event_type=Client  → 等客户端读取（应用层问题）
--   无等待 + state=active   → 在算（查询本身消耗 CPU）
--   duration_s 很大          → 长事务（可能是连接池被占住的原因）

-- ═══════════════════════════════════════════════════════════
-- ③ 阻塞链（谁在阻塞谁）
-- ═══════════════════════════════════════════════════════════
SELECT
    blocked.pid AS blocked_pid,
    round(extract(epoch from (now() - blocked.query_start))::numeric, 1) AS blocked_s,
    left(regexp_replace(blocked.query, '\s+', ' ', 'g'), 50) AS blocked_query,
    blocking.pid AS blocking_pid,
    left(regexp_replace(blocking.query, '\s+', ' ', 'g'), 50) AS blocking_query,
    blocking.state AS blocking_state
FROM pg_stat_activity blocked
JOIN pg_stat_activity blocking
  ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;

-- ⭐ 典型发现：一个"忘记提交"的事务持有行锁几十秒，
--    导致后续所有同行的更新排队。

-- ═══════════════════════════════════════════════════════════
-- ④ 连接使用情况（对比应用侧的连接池指标）
-- ═══════════════════════════════════════════════════════════
SELECT
    COALESCE(application_name, 'unknown') AS app,
    state,
    count(*) AS connections,
    round(max(extract(epoch from (now() - state_change)))::numeric, 1) AS max_state_s
FROM pg_stat_activity
WHERE pid <> pg_backend_pid()
GROUP BY app, state
ORDER BY connections DESC;

-- 与 max_connections 对比
SELECT
    (SELECT count(*) FROM pg_stat_activity) AS used,
    current_setting('max_connections')::int AS max_conn,
    round(100.0 * (SELECT count(*) FROM pg_stat_activity)
          / current_setting('max_connections')::int, 1) AS used_pct;

三、连接池判定决策树（脚本化）

#!/usr/bin/env bash
# tools/diagnose-pool.sh <APP_METRICS_URL> [PG_CONN_STRING]
#
# 自动判断"是等连接慢还是查询慢"，并给出建议方向。
set -uo pipefail

METRICS_URL="${1:-http://127.0.0.1:8080/metrics}"

echo "═══ 连接池诊断 ═══"
echo

M=$(curl -s --max-time 5 "$METRICS_URL" 2>/dev/null)
[ -z "$M" ] && { echo "❌ 无法获取指标（$METRICS_URL）"; exit 1; }

ACTIVE=$(echo "$M"  | awk '/^db_pool_active/{printf "%.0f", $2; exit}')
IDLE=$(echo "$M"    | awk '/^db_pool_idle/{printf "%.0f", $2; exit}')
PENDING=$(echo "$M" | awk '/^db_pool_pending/{printf "%.0f", $2; exit}')
TOTAL=$(echo "$M"   | awk '/^db_pool_total/{printf "%.0f", $2; exit}')

echo "连接池状态："
echo "  active  = ${ACTIVE:-?}"
echo "  idle    = ${IDLE:-?}"
echo "  pending = ${PENDING:-?}   ← 关键指标"
echo "  total   = ${TOTAL:-?}"
echo

if [ "${PENDING:-0}" -gt 0 ]; then
  echo "结论：❌ 存在排队（pending > 0）"
  echo
  echo "下一步（按顺序）："
  echo "  ① 查慢查询（不要先加池！）："
  echo "     psql -f tools/pg-diagnostics.sql   # 看第 ① 与 ② 节"
  echo "  ② 查长事务（可能是连接被占住的原因）："
  echo "     SELECT pid, now()-xact_start AS xact_age, state, left(query,50)"
  echo "     FROM pg_stat_activity WHERE xact_start IS NOT NULL"
  echo "     ORDER BY xact_age DESC LIMIT 10;"
  echo "  ③ 只有在【查询正常】且【并发确实高】时，才用 Little's Law 计算新池大小："
  echo "     所需连接 = 目标 QPS × 单次查询 P99"
else
  echo "结论：✅ 没有排队"
  echo
  if [ "${ACTIVE:-0}" -ge "${TOTAL:-1}" ] && [ "${TOTAL:-0}" -gt 0 ]; then
    echo "⚠️  但 active == total（池已满、但没有排队）"
    echo "   说明池容量刚好够用，没有余量应对突发。建议观察一段时间。"
  else
    echo "   延迟问题不在连接池，转向："
    echo "   - 依赖级指标（dep.postgres 的 P99）"
    echo "   - 慢查询统计（pg_stat_statements）"
    echo "   - 网络与下游"
  fi
fi

echo
echo "参考：pool 总连接数应 ≈ 目标QPS × 平均查询耗时（Little's Law）"

四、Redis 观测

#!/usr/bin/env bash
# tools/redis-diagnostics.sh [REDIS_CLI_ARGS]
set -uo pipefail

R="${REDIS_CLI_ARGS:--h 127.0.0.1}"

echo "═══ Redis 诊断 ═══"
echo

echo "① 基本信息"
redis-cli $R INFO server | grep -E "redis_version|uptime_in_days"
redis-cli $R INFO clients | grep -E "connected_clients|blocked_clients"
redis-cli $R INFO memory | grep -E "used_memory_human|maxmemory_human|mem_fragmentation_ratio"
echo

echo "② 命中率（低命中率说明缓存设计有问题）"
redis-cli $R INFO stats | grep -E "keyspace_hits|keyspace_misses" | awk -F: '
  /hits/{h=$2} /misses/{m=$2}
  END{ if (h+m>0) printf "  命中率: %.1f%% (hit=%d, miss=%d)\n", 100*h/(h+m), h, m }'
echo

echo "③ 慢查询日志（最近 10 条）"
redis-cli $R SLOWLOG GET 10
echo

echo "④ 延迟事件"
redis-cli $R LATENCY LATEST 2>/dev/null || echo "  （无延迟事件或无权限）"
echo

echo "⑤ 大 key 扫描（耗时操作，生产慎用）"
echo "  提示：redis-cli --bigkeys 会遍历所有 key，建议在从库或低峰期执行"
echo

echo "⑥ 命令统计 Top 10（按累计耗时）"
redis-cli $R INFO commandstats | sed 's/^cmdstat_//' | sort -t= -k4 -rn | head -10
echo

echo "判读要点："
echo "  used_memory 接近 maxmemory → 频繁淘汰，命中率下降"
echo "  mem_fragmentation_ratio > 1.5 → 内存碎片严重"
echo "  blocked_clients > 0 → 有客户端在阻塞命令（如 BLPOP）"
echo "  慢查询里有 KEYS/HGETALL 大集合 → 典型的 O(N) 命令误用"

五、一个完整的排查示例

## 现象
订单查询接口 P99 从 80ms 涨到 400ms，CPU 45%，QPS 未变。

## 排查过程

### ① 依赖级指标
dep.postgres 的 P99 从 20ms 涨到 350ms  ← 问题在数据库方向
dep.redis 的 P99 正常（2ms）

### ② 连接池（关键分叉）
db_pool_active  = 10
db_pool_idle    = 0
db_pool_pending = 18      ← 有排队

### ③ 但先不急着加池——查为什么连接被占住
psql -f tools/pg-diagnostics.sql

第 ② 节（pg_stat_activity）显示：
  10 个 backend 全部 state=active, wait_event_type=NULL（在算），已运行 3 秒
  → 不是等锁、不是等 IO，是【查询本身慢】

第 ① 节（pg_stat_statements）显示：
  某条查询 calls=50000, mean_ms=3400, total_ms=170000000
  → 单条查询慢

### ④ EXPLAIN ANALYZE
EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM orders WHERE status='PAID' ORDER BY created_at DESC LIMIT 20;
→ Seq Scan，Rows Removed by Filter: 900000
→ 行数估计 rows=20 但 actual rows=900000（统计信息过期）

### ⑤ 结论
缺索引（status）+ 统计信息过期。
连接池 pending=18 是【结果】而不是【原因】——连接被慢查询占住了。

### ⑥ 修复
CREATE INDEX CONCURRENTLY idx_orders_status_created ON orders(status, created_at DESC);
ANALYZE orders;

### ⑦ 验证
组件基准复测：P99 从 3400ms 降到 12ms
连接池 pending 回到 0
全链路 P99 从 400ms 降到 85ms

注意第 ③ 步的分叉：如果 pg_stat_activity 显示的是 wait_event_type=Lock，结论就完全不同（要查阻塞链）；如果显示 IO，要去查索引与磁盘。这就是「四个诊断查询」存在的价值——它们把猜测变成分类。

配套代码：环境元数据自动采集

Mon, 01 Jan 0001 00:00:00 +0000

1.7 配套代码：环境元数据自动采集

对应小节：1.7 实验元数据核心原则：手写一定会漏，脚本不会。

一、采集脚本

#!/usr/bin/env bash
# tools/collect-env.sh <EXP_ID>
# 由实验驱动器自动调用，把所有"实验条件"落盘。
set -uo pipefail

EXP_ID="${1:?usage: collect-env.sh <EXP_ID>}"
OUT="docs/experiments/${EXP_ID}/results/env.txt"
mkdir -p "$(dirname "$OUT")"

{
  echo "# 环境元数据（自动采集，请勿手工编辑）"
  echo "collected_at=$(date -Iseconds)"
  echo

  echo "## ① 代码版本"
  echo "git_commit=$(git rev-parse HEAD 2>/dev/null || echo 'not-a-git-repo')"
  echo "git_dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')  # >0 表示有未提交改动，实验不可复现！"
  echo "image_tag=${IMAGE_TAG:-n/a}"
  echo

  echo "## ② JVM 版本与完整参数"
  java -version 2>&1 | sed 's/^/jdk: /'
  echo "jvm_args=${JVM_ARGS:-（未设置，使用默认值——这本身也需要记录）}"
  echo

  echo "## ③ 机器规格"
  echo "os=$(uname -s -r -m)"
  if [ -f /proc/cpuinfo ]; then
    echo "cpu_model=$(awk -F': ' '/model name/{print $2; exit}' /proc/cpuinfo)"
    echo "cpu_cores=$(nproc)"
  else
    echo "cpu_model=$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo unknown)"
    echo "cpu_cores=$(sysctl -n hw.ncpu 2>/dev/null || echo unknown)"
  fi
  echo "mem_total=$(free -h 2>/dev/null | awk '/Mem:/{print $2}' || sysctl -n hw.memsize 2>/dev/null || echo unknown)"
  echo "disk=$(df -h / | awk 'NR==2{print $1, $2}')"
  echo

  echo "## ④ 容器与编排配置（缺这项是「本地好、上线慢」的头号原因）"
  echo "cgroup_cpu_max=$(cat /sys/fs/cgroup/cpu.max 2>/dev/null || echo 'n/a（非 cgroup v2 或非容器）')"
  echo "cgroup_mem_max=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo n/a)"
  if [ -f /sys/fs/cgroup/cpu.stat ]; then
    echo "--- cpu.stat ---"
    head -5 /sys/fs/cgroup/cpu.stat | sed 's/^/  /'
    echo "  （nr_throttled / throttled_usec 持续增长 = 被 CPU 配额周期性掐停）"
  fi
  echo

  echo "## ⑤ 操作系统与内核参数"
  echo "ulimit_nofile=$(ulimit -n)"
  echo "somaxconn=$(cat /proc/sys/net/core/somaxconn 2>/dev/null || echo n/a)"
  echo "cpu_governor=$(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo n/a)"
  echo "perf_event_paranoid=$(cat /proc/sys/kernel/perf_event_paranoid 2>/dev/null || echo n/a)"
  echo

  echo "## ⑥ 数据库与中间件"
  echo "postgres_version=$(psql -tAc 'select version()' 2>/dev/null | head -1 || echo 'psql 不可用')"
  echo "postgres_max_connections=$(psql -tAc 'show max_connections' 2>/dev/null || echo n/a)"
  echo "postgres_shared_buffers=$(psql -tAc 'show shared_buffers' 2>/dev/null || echo n/a)"
  echo "redis_version=$(redis-cli INFO server 2>/dev/null | awk -F: '/redis_version/{print $2}' | tr -d '\r' || echo n/a)"
  echo

  echo "## ⑦ 数据集：规模 + 分布（最常被忽略的一项）"
  echo "rows=$(psql -tAc 'select count(*) from orders' 2>/dev/null || echo n/a)"
  echo "distribution=${DATA_DISTRIBUTION:-未声明}  # 必须写：uniform / zipf(alpha) / real_replay"
  echo "cache_state=${CACHE_STATE:-未声明}          # 必须写：cold / warm(预热多久)"
  echo

  echo "## ⑧ 压测方式"
  echo "tool=$(k6 version 2>/dev/null | head -1 || echo n/a)"
  echo "model=${LOAD_MODEL:-未声明}  # constant-arrival-rate / ramping-arrival-rate / constant-vus"
  echo "target_qps=${TARGET_QPS:-未声明}"
  echo "warmup_duration=${WARMUP:-未声明}"
  echo "steady_duration=${STEADY:-未声明}"
  echo "script_commit=$(git rev-parse HEAD:loadtest 2>/dev/null || echo n/a)"
  echo

  echo "## ⑨ 测量点与观测工具"
  echo "measurement_point=${MEASUREMENT_POINT:-未声明}  # client / gateway / in_app"
  echo "prometheus_scrape_interval=${SCRAPE_INTERVAL:-未声明}"
  echo "histogram_buckets=${HISTOGRAM_BUCKETS:-未声明}"
} > "$OUT"

echo "环境元数据已写入 $OUT"

# 自检：把所有"未声明"标出来，提醒你补齐
if grep -q "未声明" "$OUT"; then
  echo
  echo "⚠️ 以下项目未声明，实验不可复现："
  grep -n "未声明" "$OUT" | sed 's/^/   /'
fi

二、为什么每一节都必要

段落	漏了会怎样（真实案例）
① 代码版本	三个月后无法确认「当时测的是哪个版本」
① `git_dirty`	代码有未提交改动 → 别人 checkout 同一个 commit 也复现不出来
② JVM 参数	把「换了 GC」误认为「优化有效」，提升 20% 其实是环境变了
③ CPU 型号	「都是 8 核」但一代 CPU 差 2 倍单核性能
④ 容器 CPU limit	本地压测无限制、生产 1 核 limit → 数据完全不可迁移
⑤ `ulimit -n`	并发连接数被文件描述符上限卡住，却以为是应用问题
⑤ `perf_event_paranoid`	火焰图采不到数据，浪费半天排查工具权限
⑥ 数据库配置	`max_connections` 和 `shared_buffers` 直接决定性能天花板
⑦ 数据量 + 分布	均匀分布测出「达标」，真实幂律流量下完全不达标
⑧ 流量模型	闭环模型的 P99 可能比真实值低 500 倍（第 0 章 0.6 节）
⑨ 测量点	拿客户端数据当基线、服务端数据当结果，得出「提升 77%」的假结论

三、配套的实验档案头信息

把 env.txt 粘进档案的同时，这几项要在 YAML 里写清（模板见 docs/experiments/_TEMPLATE/README.md）：

配套代码：陷阱的反例、正例与验证

Mon, 01 Jan 0001 00:00:00 +0000

6.7 配套代码：陷阱的反例、正例与验证

对应小节：6.7 陷阱清单：Kotlin 与 C++ 直觉九条 Kotlin 陷阱的可运行对照代码，以及三个验证实验。

一、九条陷阱的反例与正例

❶ 在 `Dispatchers.Default` 上做阻塞调用

// ❌ 反例：阻塞调用占满 Default 的 worker（= CPU 核数）
suspend fun findBad(id: Long): Order? =
    jdbcTemplate.queryForObject("select * from orders where id = ?", Order::class.java, id)

// ✅ 正例 1：切到 IO
suspend fun findGood(id: Long): Order? = withContext(Dispatchers.IO) {
    jdbcTemplate.queryForObject("select * from orders where id = ?", Order::class.java, id)
}

// ✅ 正例 2：异步驱动（根本不阻塞）
suspend fun findBest(id: Long): Order? =
    r2dbcClient.sql("select * from orders where id = :id")
        .bind("id", id)
        .map { row -> Order(row.get("id", Long::class.java)!!) }
        .awaitOneOrNull()

// ✅ 正例 3：即使切到 IO，也要限制并发（保护下游）
private val dbLimiter = Semaphore(64)
suspend fun findLimited(id: Long): Order? = dbLimiter.withPermit {
    withContext(Dispatchers.IO) {
        jdbcTemplate.queryForObject("select * from orders where id = ?", Order::class.java, id)
    }
}

❷ `synchronized` 跨越挂起点

// ❌ 反例：挂起时仍持锁
class OrderServiceBad {
    private val lock = Any()
    private val cache = mutableMapOf<Long, Order>()

    suspend fun get(id: Long): Order {
        synchronized(lock) {
            cache[id]?.let { return it }
            val order = loadFromDb(id)        // ← 挂起！但 monitor 没释放
            cache[id] = order
            return order
        }
    }
    private suspend fun loadFromDb(id: Long): Order = TODO()
}

// ✅ 正例：用 Mutex（协程感知）
class OrderServiceGood {
    private val mutex = Mutex()
    private val cache = mutableMapOf<Long, Order>()

    suspend fun get(id: Long): Order = mutex.withLock {
        cache[id] ?: loadFromDb(id).also { cache[id] = it }
    }
    private suspend fun loadFromDb(id: Long): Order = TODO()
}

❸ `Dispatchers.IO` 当成无限池

// ❌ 反例：10 万个协程抢 64 个 IO 线程
suspend fun handleAllBad(ids: List<Long>) = coroutineScope {
    ids.map { id -> async(Dispatchers.IO) { jdbcQuery(id) } }.awaitAll()
}

// ✅ 正例：用 Semaphore 或 limitedParallelism 显式限制
private val limiter = Semaphore(64)
suspend fun handleAllGood(ids: List<Long>) = coroutineScope {
    ids.map { id ->
        async { limiter.withPermit { withContext(Dispatchers.IO) { jdbcQuery(id) } } }
    }.awaitAll()
}

// ✅ 或用 limitedParallelism（Kotlin 1.6+）
private val limitedIo = Dispatchers.IO.limitedParallelism(64)

❹ `runBlocking` 在请求路径上

// ❌ 反例
fun handleBad(): Response = runBlocking { fetchData() }

// ✅ 正例：全链路 suspend
suspend fun handleGood(): Response = fetchData()

// ⚠️ 允许的用法：main / 测试 / 阻塞世界的边界
fun main() = runBlocking { startServer() }

❺ 无界缓存

// ❌ 反例：key 无限增长
class CacheBad {
    private val map = mutableMapOf<String, Order>()
    fun get(k: String) = map[k]
    fun put(k: String, v: Order) { map[k] = v }
}

// ✅ 正例：有界 + TTL + 抖动
private val cacheGood = Caffeine.newBuilder()
    .maximumSize(100_000)                                  // 有界
    .expireAfter(object : Expiry<String, Order> {           // TTL + 抖动
        private val base = Duration.ofMinutes(10).toMillis()
        override fun expireAfterCreate(k: String, v: Order, now: Long) =
            base + (Math.random() * base * 0.2).toLong()
        override fun expireAfterUpdate(k: String, v: Order, now: Long, dur: Long) =
            expireAfterCreate(k, v, now)
        override fun expireAfterRead(k: String, v: Order, now: Long, dur: Long) = dur
    })
    .recordStats()                                         // 可观测
    .build<String, Order>()

❻ `GlobalScope` / 未结构化并发

// ❌ 反例：请求结束后协程还在跑
fun handleBad() {
    GlobalScope.launch { heavyBackgroundWork() }
}

// ✅ 正例：绑定到请求生命周期
suspend fun handleGood() = coroutineScope {
    launch { heavyBackgroundWork() }    // 父作用域取消时它也取消
}

// ✅ 如果确实要后台任务，用受控的作用域 + 明确的取消策略
private val backgroundScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

❼ 热路径上的 `copy()`

data class Order(val id: Long, val status: String, val amount: Long, val items: List<Item>)
data class Item(val name: String, val qty: Int)

// ❌ 反例：热路径上频繁 copy
fun markAllPaidBad(orders: List<Order>) = orders.map { it.copy(status = "PAID") }

// ✅ 正例 1：如果只是展示，用视图对象
fun toView(orders: List<Order>) = orders.map { OrderView(it.id, it.status) }

// ✅ 正例 2：批量更新用一次性查询，不要逐条 copy
fun markAllPaidGood(ids: List<Long>) {
    // update orders set status = 'PAID' where id = any(?)
}

❽ 装箱与集合类型

// ❌ 反例：热路径上用包装类型
fun sumBad(values: List<Int>): Long {
    var s = 0L
    for (v in values) s += v          // v 是 Int（对象）→ 装箱
    return s
}

// ✅ 正例：原始类型数组
fun sumGood(values: IntArray): Long {
    var s = 0L
    for (v in values) s += v          // 无装箱
    return s
}

❾ `Sequence` 与 `Regex`

// ❌ 反例 1：小数据集用 Sequence（lambda 开销更大）
fun processBad(items: List<String>) =
    items.asSequence().map { it.trim() }.filter { it.isNotEmpty() }.toList()

// ✅ 正例：小数据集直接用 List 操作
fun processGood(items: List<String>) =
    items.map { it.trim() }.filter { it.isNotEmpty() }

// ❌ 反例 2：每次调用都编译正则
fun extractBad(text: String): Int {
    val re = Regex("""\d{3}-\d{4}""")      // 每次编译！
    return re.findAll(text).count()
}

// ✅ 正例：提到顶层，只编译一次
private val PHONE_RE = Regex("""\d{3}-\d{4}""")
fun extractGood(text: String): Int = PHONE_RE.findAll(text).count()

二、验证实验：用数据证明陷阱的影响

实验一：调度器污染（最有说服力）

// src/main/kotlin/experiments/DispatcherPollutionDemo.kt
package experiments

import kotlinx.coroutines.*
import kotlin.system.measureNanoTime

private var sink = 0L

suspend fun fastWork(): Double {
    val ns = measureNanoTime {
        var s = 0L
        repeat(10_000) { s += it }
        sink += s
    }
    return ns / 1_000_000.0
}

fun median(xs: List<Double>): Double = xs.sorted()[xs.size / 2]

fun main() = runBlocking {
    val cores = Runtime.getRuntime().availableProcessors()
    println("CPU 核数 = $cores，Dispatchers.Default 并行度 ≈ $cores")
    println()

    suspend fun runFast(n: Int) = coroutineScope {
        (0 until n).map { async(Dispatchers.Default) { fastWork() } }.awaitAll()
    }

    // 基线
    runFast(cores * 4)
    val baseline = runFast(cores * 4)
    println("基线（只有快速工作）    : 中位 %8.3f ms".format(median(baseline)))

    // 阻塞在 Default
    val blockers = List(cores) { launch(Dispatchers.Default) { Thread.sleep(1000) } }
    delay(100)
    val polluted = runFast(cores * 4)
    blockers.forEach { it.cancel() }
    println("阻塞在 Default          : 中位 %8.3f ms  ← 放大 %.0f 倍".format(
        median(polluted), median(polluted) / median(baseline)))

    delay(300)

    // 阻塞在 IO
    val ioBlockers = List(cores) { launch(Dispatchers.IO) { Thread.sleep(1000) } }
    delay(100)
    val healthy = runFast(cores * 4)
    ioBlockers.forEach { it.cancel() }
    println("阻塞在 IO               : 中位 %8.3f ms  ← 恢复正常".format(median(healthy)))

    println()
    println("sink = $sink")
    println()
    println("结论：同样是阻塞调用，放在 Default 上会让【所有】使用 Default 的协程排队。")
}

预期：阻塞在 Default 时，快速工作的延迟从 0.08 ms 涨到几百毫秒（放大几千倍），而 CPU 利用率很低。

配套代码：JMH 与 kotlinx-benchmark 的完整配置

Mon, 01 Jan 0001 00:00:00 +0000

2.8 配套代码：JMH 与 kotlinx-benchmark 的完整配置

对应小节：2.8 JMH 与 kotlinx-benchmark 这份配置可以直接抄进你的项目。

一、方案 A：JMH（功能最全）

1.1 构建配置

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.0.20"
    kotlin("kapt") version "2.0.20"                 // ← Kotlin 用 JMH 必须
    id("me.champeau.jmh") version "0.7.2"
}

repositories { mavenCentral() }

dependencies {
    jmh("org.openjdk.jmh:jmh-core:1.37")
    jmh("org.openjdk.jmh:jmh-generator-annprocess:1.37")
    kaptJmh("org.openjdk.jmh:jmh-generator-annprocess:1.37")   // ← 关键，缺了会静默失败
}

// 基准源码放在 src/jmh/kotlin，与 main/test 分开

⚠️ 两个 Kotlin 专属的坑：① 少了 kotlin("kapt") 和 kaptJmh，JMH 会报「找不到基准」而不提示原因；② 被测类和被测方法必须 open（Kotlin 默认 final，JMH 无法生成子类）。

配套代码：Lab 3 的实验编排

Mon, 01 Jan 0001 00:00:00 +0000

3.8 配套代码：Lab 3 的实验编排

对应小节：3.8 Lab 3 这份文件把前面的代码组织成一条流水线，并给出记录模板。

一、Lab 3 的目录与代码来源

docs/experiments/E03-two-level-test/
├── README.md                          # 实验档案（模板见下方）
├── scripts/                           # 冻结的脚本快照
│   ├── component-bench.txt            # 组件基准输出（见 02）
│   ├── integration-bench.txt          # 集成基准输出（见 03）
│   └── e2e-baseline.js                # k6 脚本（见 03）
└── results/
    ├── env.txt                        # 环境元数据（自动采集）
    ├── component-bench.txt
    ├── integration-bench.txt
    ├── k6-summary.json
    └── k6-raw.json

步骤	用哪份代码
组件基准	02-component-benchmark.md
集成基准	03-integration-and-e2e.md 第一节
全链路压测	03-integration-and-e2e.md 第二、三节
结果对比	本文件第三节

二、一键跑完三层（编排脚本）

#!/usr/bin/env bash
# tools/run-lab3.sh <EXP_ID>
set -euo pipefail

EXP_ID="${1:?usage: run-lab3.sh <EXP_ID>}"
DIR="docs/experiments/${EXP_ID}"
mkdir -p "$DIR/results" "$DIR/scripts"

echo "═══ 步骤 0：环境元数据 ═══"
tools/collect-env.sh "$EXP_ID"

echo
echo "═══ 步骤 1：组件基准（Testcontainers，约 5 分钟）═══"
./gradlew test --tests 'bench.OrderRepositoryBenchmark' --info 2>&1 \
  | tee "$DIR/results/component-bench.txt"

echo
echo "═══ 步骤 2：集成基准（单服务完整启动，约 3 分钟）═══"
./gradlew -PmainClass=bench.IntegrationBenchmark run 2>&1 \
  | tee "$DIR/results/integration-bench.txt"

echo
echo "═══ 步骤 3：全链路压测（k6，约 12 分钟）═══"
# 前置：服务以生产同构配置启动
scripts/restart-app.sh "$DIR/results/gc.log"
sleep 5

# 预热（不计入统计）
BASE_URL=http://127.0.0.1:8080 k6 run --quiet --vus 20 --duration 60s loadtest/e2e-baseline.js > /dev/null

# 正式测量
BASE_URL=http://127.0.0.1:8080 RATE=500 DURATION=10m \
k6 run --out json="$DIR/results/k6-raw.json" \
       --summary-export="$DIR/results/k6-summary.json" \
       loadtest/e2e-baseline.js | tee "$DIR/results/k6-stdout.txt"

echo
echo "═══ 步骤 4：验证数据可用性 ═══"
tools/check-k6-result.sh "$DIR/results/k6-summary.json" 500 || {
  echo "⚠️  全链路数据不可用 —— 请先修压测侧（preAllocatedVUs / 压测机资源）"
}

echo
echo "✅ Lab 3 完成 → $DIR"
echo "下一步：填写 $DIR/README.md（模板见 docs/experiments/_TEMPLATE/README.md）"

三、三层对比的自动汇总

把三份输出汇总成一张表，方便写结论：

配套代码：三问纪律与收益报告

Mon, 01 Jan 0001 00:00:00 +0000

7.8 配套代码：三问纪律与收益报告

对应小节：7.8 三问纪律与收益报告三件事：① 三问检查清单；② 收益报告生成器；③ 否决记录管理。

一、三问检查清单（交互式）

#!/usr/bin/env bash
# tools/optimization-three-questions.sh
#
# 每项优化都必须回答的三个问题。
# 缺任何一问，这次改动的证据链就是断的。
set -uo pipefail

echo "═══════════════════════════════════════════════════════════════"
echo "优化的三问检查"
echo "═══════════════════════════════════════════════════════════════"
echo

FAIL=0

ask_required() {
  local question="$1"
  local hint="$2"
  echo "── $question"
  echo "   （$hint）"
  read -r -p "   已完成？[y/N] " ans
  if [[ "${ans,,}" != "y" ]]; then
    echo "   ❌ 未完成 —— 这一问不能跳过"
    FAIL=$((FAIL+1))
  else
    echo "   ✅"
  fi
  echo
}

echo "【第一问：提升多少？】"
echo
ask_required "有 before/after 数据吗？" \
  "必须是同一套脚本、同一环境、≥3 轮"
ask_required "报了中位数与百分位（不是平均值）吗？" \
  "至少 P50/P95/P99 + 错误率"
ask_required "做了统计检验吗？" \
  "Mann-Whitney U 或 Bootstrap 置信区间（第 5 章）"
ask_required "与噪声底线/MDD 对比了吗？" \
  "差异必须超过 MDD 才可信（第 5 章 5.7）"

echo "【第二问：代价是什么？】"
echo
ask_required "显式列出了代价吗？" \
  "复杂度/一致性/资源/风险 —— 代价不会自己消失"
ask_required "有降级方案吗？" \
  "新组件挂了会怎样？服务还能用吗？"

echo "【第三问：回归验证了吗？】"
echo
ask_required "功能正确性验证了吗？" \
  "单元测试 + 关键路径手工验证"
ask_required "性能回归验证了吗？" \
  "⚠️ 优化 A 可能让 B 变慢 —— 用同一套脚本复跑基线"
ask_required "长稳（浸泡）验证了吗？" \
  "引入新组件或改并发模型时必须做（第 3 章 3.5）"

echo "═══════════════════════════════════════════════════════════════"
if [ "$FAIL" -eq 0 ]; then
  echo "✅ 三问全部通过 —— 这次优化可以写进报告"
else
  echo "❌ 有 $FAIL 项未完成"
  echo
  echo "提醒：答不出第三问的优化，本质上是【技术债】而不是优化。"
  echo "      它会在此后的每一次故障排查中增加不确定性。"
fi
echo "═══════════════════════════════════════════════════════════════"

二、收益报告生成器

# tools/generate-optimization-report.py <optimizations.json> [--out report.md]
"""
从结构化数据生成优化收益报告。

输入格式：
{
  "title": "订单查询接口优化",
  "root_cause": "缺索引导致全表扫描（贡献占比 72%）",
  "experiments": {"before": "E03", "after": "E08"},
  "noise_floor_pct": 13.2,
  "mdd_pct": 26.4,
  "optimizations": [
    {
      "name": "给 status 加索引",
      "level": 2,
      "level_name": "② 算法与数据访问",
      "changes": "CREATE INDEX idx_orders_status_created ON orders(status, created_at DESC)",
      "rationale": "消除全表扫描，Rows Removed by Filter 从 900000 降到 200",
      "metrics": {
        "before": {"p50": 20.1, "p99": 210.4, "qps": 498, "error_rate": 0.0005},
        "after":  {"p50": 8.3,  "p99": 95.2,  "qps": 499, "error_rate": 0.0003}
      },
      "p_value": 0.008,
      "costs": [
        "索引占用额外磁盘（约 120 MB）",
        "写入时有轻微的索引维护开销（实测 < 2%）"
      ],
      "rollback": "DROP INDEX idx_orders_status_created",
      "regressions": {
        "functional": "单元测试全通过；手工验证了 5 个关键路径",
        "performance": "其他接口 P99 变化 < 3%（在噪声范围内）",
        "soak": "40 分钟浸泡，内存与连接数稳定"
      }
    }
  ],
  "rejected": [
    {
      "name": "加 Redis 缓存",
      "expected_benefit": "P50 -70%",
      "reason": "批量查询已解决主要问题；key 分散导致命中率预估仅 40%，P99 不会改善；引入一致性风险",
      "reconsider_when": "命中率能到 90% 以上，或数据量增长导致即使批量查询也变慢"
    }
  ],
  "not_covered": ["冷启动路径", "数据量增长 10 倍后的表现", "多副本部署"],
  "next_steps": ["监控 P99 一周，确认稳定", "把索引加入部署脚本"]
}
"""
import json
import sys
from datetime import datetime


def fmt_delta(before, after):
    if before == 0:
        return "n/a"
    return f"{(after - before) / before * 100:+.1f}%"


def generate(data):
    noise = data.get("noise_floor_pct", 0)
    mdd = data.get("mdd_pct", 0)

    lines = [
        f"# 优化收益报告：{data['title']}",
        "",
        f"> 生成时间：{datetime.now().isoformat(timespec='seconds')}　|　"
        f"关联实验：{' – '.join(data.get('experiments', {}).values())}",
        "",
        "---",
        "",
        "## 1. 问题与根因",
        "",
        data["root_cause"],
        "",
        "---",
        "",
    ]

    for i, opt in enumerate(data["optimizations"], 1):
        lines += [
            f"## 2.{i} 优化措施 {i}：{opt['name']}",
            "",
            f"- **金字塔层级**：{opt.get('level_name', opt.get('level', '?'))}",
            f"- **改动**：`{opt['changes']}`",
            f"- **原理**：{opt['rationale']}",
            "",
            "### 第一问：提升多少",
            "",
            "| 指标 | before | after | 变化 |",
            "| --- | --- | --- | --- |",
        ]

        b, a = opt["metrics"]["before"], opt["metrics"]["after"]
        for key, label in [("p50", "P50 (ms)"), ("p99", "P99 (ms)"),
                           ("qps", "QPS"), ("error_rate", "错误率")]:
            if key in b and key in a:
                bv, av = b[key], a[key]
                if key == "error_rate":
                    bv_s, av_s = f"{bv:.2%}", f"{av:.2%}"
                    delta = f"{(av - bv) * 100:+.2f}pp"
                elif key == "qps":
                    bv_s, av_s = f"{bv:.1f}", f"{av:.1f}"
                    delta = fmt_delta(bv, av)
                else:
                    bv_s, av_s = f"{bv:.1f}", f"{av:.1f}"
                    delta = fmt_delta(bv, av)
                lines.append(f"| {label} | {bv_s} | {av_s} | {delta} |")

        lines += ["", "**显著性判定**：", ""]
        lines.append(f"- 环境噪声底线：±{noise}%")
        lines.append(f"- 最小可检测差异（MDD）：±{mdd}%")
        if "p_value" in opt:
            p = opt["p_value"]
            sig = "✅ 显著" if p < 0.05 else "❌ 不显著"
            lines.append(f"- 统计检验：Mann-Whitney U，p = {p}（{sig}）")

        # 判断可信度
        if "p99" in b and "p99" in a:
            delta_pct = (a["p99"] - b["p99"]) / b["p99"] * 100
            if abs(delta_pct) < noise:
                lines.append(f"- **结论**：⚠️ 变化 {delta_pct:+.1f}% 在噪声范围内，**无法确认优化有效**")
            elif abs(delta_pct) < mdd:
                lines.append(f"- **结论**：⚠️ 变化 {delta_pct:+.1f}% 超过噪声底线但小于 MDD，方向可信、幅度需验证")
            else:
                lines.append(f"- **结论**：✅ 变化 {delta_pct:+.1f}%，超过 MDD，**优化有效且可信**")

        lines += [
            "",
            "### 第二问：代价是什么",
            "",
        ]
        for c in opt.get("costs", []):
            lines.append(f"- {c}")
        if opt.get("rollback"):
            lines += ["", f"**回滚方式**：`{opt['rollback']}`"]

        lines += [
            "",
            "### 第三问：回归验证",
            "",
        ]
        reg = opt.get("regressions", {})
        lines.append(f"- [{'x' if reg.get('functional') else ' '}] **功能正确性**：{reg.get('functional', '未验证')}")
        lines.append(f"- [{'x' if reg.get('performance') else ' '}] **性能回归**：{reg.get('performance', '未验证')}")
        lines.append(f"- [{'x' if reg.get('soak') else ' '}] **长稳（浸泡）**：{reg.get('soak', '未验证')}")
        lines += ["", "---", ""]

    # 被否决的方案
    if data.get("rejected"):
        lines += [
            "## 3. 被否决的方案",
            "",
            "| 方案 | 预期收益 | 否决理由 | 重新评估的条件 |",
            "| --- | --- | --- | --- |",
        ]
        for r in data["rejected"]:
            lines.append(
                f"| {r['name']} | {r['expected_benefit']} | {r['reason']} | {r.get('reconsider_when', '—')} |")
        lines += ["", "---", ""]

    # 未覆盖场景
    lines += ["## 4. 未覆盖的场景", ""]
    for s in data.get("not_covered", []):
        lines.append(f"- {s}")
    lines += ["", "---", ""]

    # 后续
    lines += ["## 5. 后续建议", ""]
    for s in data.get("next_steps", []):
        lines.append(f"- {s}")
    lines.append("")

    return "\n".join(lines)


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(__doc__)
        sys.exit(1)

    data = json.loads(open(sys.argv[1]).read())
    report = generate(data)

    if "--out" in sys.argv:
        out = sys.argv[sys.argv.index("--out") + 1]
        open(out, "w", encoding="utf-8").write(report)
        print(f"✅ 报告已生成 → {out}")
    else:
        print(report)

三、否决记录管理

# tools/rejection-log.py
"""
管理「被否决的方案」——它们不是垃圾，而是有价值的决策记录。

用法：
    python3 tools/rejection-log.py add <EXP_ID> "<方案>" "<预期收益>" "<否决理由>" "<重新评估条件>"
    python3 tools/rejection-log.py list <EXP_ID>
    python3 tools/rejection-log.py review <EXP_ID>    # 检查是否有需要重新评估的
"""
import json
import pathlib
import sys
from datetime import datetime


def log_path(exp_id):
    d = pathlib.Path("docs/experiments") / exp_id
    d.mkdir(parents=True, exist_ok=True)
    return d / "rejections.json"


def load(exp_id):
    p = log_path(exp_id)
    return json.loads(p.read_text(encoding="utf-8")) if p.exists() else {"rejections": []}


def save(exp_id, data):
    log_path(exp_id).write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")


def cmd_add(exp_id, name, benefit, reason, reconsider):
    data = load(exp_id)
    data["rejections"].append({
        "id": f"R{len(data['rejections']) + 1}",
        "name": name,
        "expected_benefit": benefit,
        "reason": reason,
        "reconsider_when": reconsider,
        "date": datetime.now().isoformat(timespec="seconds"),
    })
    save(exp_id, data)
    print(f"✅ 已记录否决：{name}")


def cmd_list(exp_id):
    data = load(exp_id)
    if not data["rejections"]:
        print("（无否决记录）")
        return
    print("═" * 88)
    print(f"被否决的方案：{exp_id}")
    print("═" * 88)
    print()
    for r in data["rejections"]:
        print(f"【{r['id']}】{r['name']}　（{r['date']}）")
        print(f"  预期收益　　: {r['expected_benefit']}")
        print(f"  否决理由　　: {r['reason']}")
        print(f"  重新评估条件: {r['reconsider_when']}")
        print()


def cmd_review(exp_id):
    """检查是否有需要重新评估的否决"""
    data = load(exp_id)
    print("═" * 78)
    print("否决记录复查")
    print("═" * 78)
    print()
    print("提醒：以下否决是【有条件的】——如果条件已经变化，应该重新评估。")
    print()
    for r in data["rejections"]:
        print(f"  {r['id']} {r['name']}")
        print(f"     → 当「{r['reconsider_when']}」时，重新评估")
        print()
    print("═" * 78)
    print("为什么要复查：")
    print("  ① 数据量可能增长（原来命中率低的缓存现在可能有效）")
    print("  ② 业务可能变化（原来不需要实时，现在需要）")
    print("  ③ 技术可能演进（新的序列化器、新的 GC）")
    print("  ④ 瓶颈可能转移（原来占 5% 的部分现在占 40%）")
    print("═" * 78)


if __name__ == "__main__":
    if len(sys.argv) < 3:
        print(__doc__)
        sys.exit(1)
    cmd, exp = sys.argv[1], sys.argv[2]
    if cmd == "add" and len(sys.argv) >= 7:
        cmd_add(exp, sys.argv[3], sys.argv[4], sys.argv[5], sys.argv[6])
    elif cmd == "list":
        cmd_list(exp)
    elif cmd == "review":
        cmd_review(exp)
    else:
        print(__doc__)

使用示例：

配套代码：容器节流诊断与环境一致性检查

Mon, 01 Jan 0001 00:00:00 +0000

4.8 配套代码：容器节流诊断与环境一致性检查

对应小节：4.8 容器与编排的干扰核心：一条命令确认「你的进程有没有被周期性掐停」。

一、节流诊断脚本（最重要的一份）

#!/usr/bin/env bash
# tools/check-throttling.sh [SAMPLE_SECONDS]
#
# 判断容器是否被 CPU 配额节流。
# 这是「本地好、上线慢」的头号原因的确认手段。
set -uo pipefail

DURATION="${1:-10}"

echo "═══ 容器 CPU 节流诊断 ═══"
echo

# ── cgroup v2（现代发行版）────────────────────────────────
if [ -f /sys/fs/cgroup/cpu.max ]; then
  read -r QUOTA PERIOD < /sys/fs/cgroup/cpu.max
  echo "cgroup 版本: v2"
  if [ "$QUOTA" = "max" ]; then
    echo "CPU 配额  : 无限制（未设置 CPU limit）"
    echo "结论      : 不存在节流问题"
    exit 0
  fi
  LIMIT_CORES=$(awk -v q="$QUOTA" -v p="$PERIOD" 'BEGIN{printf "%.2f", q/p}')
  echo "CPU 配额  : $QUOTA / $PERIOD = ${LIMIT_CORES} 核"
  echo

  echo "采样 ${DURATION} 秒..."
  P0=$(awk '/nr_periods/{print $2}' /sys/fs/cgroup/cpu.stat)
  T0=$(awk '/nr_throttled/{print $2}' /sys/fs/cgroup/cpu.stat)
  U0=$(awk '/throttled_usec/{print $2}' /sys/fs/cgroup/cpu.stat)
  sleep "$DURATION"
  P1=$(awk '/nr_periods/{print $2}' /sys/fs/cgroup/cpu.stat)
  T1=$(awk '/nr_throttled/{print $2}' /sys/fs/cgroup/cpu.stat)
  U1=$(awk '/throttled_usec/{print $2}' /sys/fs/cgroup/cpu.stat)

  awk -v p0="$P0" -v p1="$P1" -v t0="$T0" -v t1="$T1" -v u0="$U0" -v u1="$U1" -v d="$DURATION" 'BEGIN{
    dp = p1-p0; dt = t1-t0; du = u1-u0;
    printf "本窗口周期数      : %d\n", dp
    printf "本窗口被节流次数  : %d\n", dt
    if (dp > 0) {
      ratio = 100*dt/dp
      printf "节流比例          : %.2f%%\n", ratio
      printf "被节流总时长      : %.3f 秒 / %d 秒\n", du/1e6, d
      printf "时间被掐停占比    : %.2f%%\n", 100*(du/1e6)/d
      print ""
      if (ratio > 25)      print "结论: ❌ 严重节流 —— 这是 P99 抖动的很可能原因"
      else if (ratio > 5)  print "结论: ⚠️  存在节流，值得关注"
      else if (ratio > 1)  print "结论: ⚠️  轻微节流，通常可接受"
      else                 print "结论: ✅ 基本无节流"
    } else {
      print "结论: 本窗口内没有调度周期（应用可能空闲）"
    }
  }'

# ── cgroup v1（较老发行版）────────────────────────────────
elif [ -f /sys/fs/cgroup/cpu/cpu.cfs_quota_us ]; then
  QUOTA=$(cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us)
  PERIOD=$(cat /sys/fs/cgroup/cpu/cpu.cfs_period_us)
  echo "cgroup 版本: v1"
  if [ "$QUOTA" -lt 0 ] 2>/dev/null; then
    echo "CPU 配额: 无限制"
  else
    awk -v q="$QUOTA" -v p="$PERIOD" 'BEGIN{printf "CPU 配额: %d/%d = %.2f 核\n", q, p, q/p}'
    echo
    echo "cpu.stat 内容："
    cat /sys/fs/cgroup/cpu/cpu.stat 2>/dev/null | head -5
    echo
    awk '/nr_periods/{p=$2} /nr_throttled/{t=$2} END{
      if (p>0) printf "累计节流比例: %.2f%%\n", 100*t/p
    }' /sys/fs/cgroup/cpu/cpu.stat
  fi
else
  echo "❌ 未检测到 cgroup CPU 限制"
  echo "   → 说明当前不在容器内，或容器未设置 CPU limit"
  echo "   → 本次实验【不能】用于推断生产环境（生产有 limit 时行为不同）"
fi

echo
echo "═══ 补充信息 ═══"
echo "容器内存 limit : $(cat /sys/fs/cgroup/memory.max 2>/dev/null || cat /sys/fs/cgroup/memory/memory.limit_in_bytes 2>/dev/null || echo 'n/a')"
echo "可见 CPU 核数   : $(nproc)"
echo "  ⚠️ 注意：容器里 nproc 可能显示宿主机的核数，与 CPU limit 不一致"

二、JVM 与容器内存对齐检查

#!/usr/bin/env bash
# tools/check-jvm-memory.sh <PID>
#
# 检查 JVM 堆设置与容器内存 limit 是否匹配。
# 不匹配的典型后果：OOMKilled（进程被无声杀死）。
set -uo pipefail

PID="${1:?usage: check-jvm-memory.sh <pid>}"

echo "═══ JVM 与容器内存对齐检查 ═══"
echo

# 容器内存 limit
if [ -f /sys/fs/cgroup/memory.max ]; then
  MEM_LIMIT_BYTES=$(cat /sys/fs/cgroup/memory.max)
elif [ -f /sys/fs/cgroup/memory/memory.limit_in_bytes ]; then
  MEM_LIMIT_BYTES=$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes)
else
  MEM_LIMIT_BYTES=0
fi

# JVM 堆上限
MAX_HEAP=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep -iE "^-XX:MaxHeapSize=" | head -1)
MAX_HEAP_MB=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep -iE "^-XX:MaxHeapSize=" | head -1 | sed 's/.*=//' | awk '{printf "%.0f", $1/1048576}')
[ -z "$MAX_HEAP_MB" ] && MAX_HEAP_MB=0

# 直接内存与元空间
MAX_DIRECT=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep -iE "MaxDirectMemorySize" | head -1 | sed 's/.*=//')
MAX_META=$(jcmd "$PID" VM.flags 2>/dev/null | tr ' ' '\n' | grep -iE "MaxMetaspaceSize" | head -1 | sed 's/.*=//')

if [ "$MEM_LIMIT_BYTES" != "0" ] && [ "$MEM_LIMIT_BYTES" != "max" ]; then
  MEM_LIMIT_MB=$(( MEM_LIMIT_BYTES / 1048576 ))
  echo "容器内存 limit : ${MEM_LIMIT_MB} MB"
  echo "JVM 堆上限     : ${MAX_HEAP_MB} MB"
  echo "堆外预留       : $(( MEM_LIMIT_MB - MAX_HEAP_MB )) MB"
  echo "  MaxDirectMemorySize: ${MAX_DIRECT:-未设置（默认≈堆大小，需注意！）}"
  echo "  MaxMetaspaceSize   : ${MAX_META:-未设置（默认无上限）}"
  echo

  if [ "$MAX_HEAP_MB" -gt 0 ]; then
    RATIO=$(awk -v h="$MAX_HEAP_MB" -v m="$MEM_LIMIT_MB" 'BEGIN{printf "%.0f", 100*h/m}')
    echo "堆占容器内存比例: ${RATIO}%"
    if [ "$RATIO" -gt 85 ]; then
      echo "结论: ❌ 堆占比过高，几乎必然 OOMKilled"
      echo "      建议: 堆 = 容器 limit 的 50%~75%（例如 ${MEM_LIMIT_MB}MB → $(( MEM_LIMIT_MB * 60 / 100 ))MB）"
    elif [ "$RATIO" -gt 75 ]; then
      echo "结论: ⚠️  偏紧，需确认堆外内存的实际使用量"
    else
      echo "结论: ✅ 比例合理"
    fi
  fi
else
  echo "容器内存 limit : 无限制或非容器环境"
  echo "JVM 堆上限     : ${MAX_HEAP_MB} MB"
  echo "  ⚠️ 本次实验不能推断生产环境（生产通常设置了内存 limit）"
fi

echo
echo "═══ 堆外内存实际使用（需 -XX:NativeMemoryTracking=summary）═══"
jcmd "$PID" VM.native_memory summary 2>/dev/null | head -25 || \
  echo "（未开启 NativeMemoryTracking，无法查看。启动时加 -XX:NativeMemoryTracking=summary）"

三、压测环境与生产一致性检查

#!/usr/bin/env bash
# tools/check-env-parity.sh <EXPECTED_CPU_CORES> <EXPECTED_MEM_MB>
#
# 对比压测环境与生产的关键配置。不一致则数据不可迁移。
set -uo pipefail

EXP_CPU="${1:?usage: check-env-parity.sh <expected_cpu_cores> <expected_mem_mb>}"
EXP_MEM="${2:?}"

FAILED=0
echo "═══ 环境一致性检查（压测环境 vs 生产）═══"
echo

# ① CPU limit
if [ -f /sys/fs/cgroup/cpu.max ]; then
  read -r Q P < /sys/fs/cgroup/cpu.max
  if [ "$Q" = "max" ]; then
    ACT_CPU="无限"
  else
    ACT_CPU=$(awk -v q="$Q" -v p="$P" 'BEGIN{printf "%.2f", q/p}')
  fi
  echo "CPU limit : 生产 [${EXP_CPU} 核]  压测 [${ACT_CPU} 核]"
  if [ "$Q" = "max" ]; then
    echo "   ❌ 压测环境未设置 CPU limit —— 数据与生产不可比"
    FAILED=1
  fi
else
  echo "CPU limit : 压测环境非容器或未设限制 ❌"
  FAILED=1
fi
echo

# ② 内存 limit
if [ -f /sys/fs/cgroup/memory.max ]; then
  M=$(cat /sys/fs/cgroup/memory.max)
  if [ "$M" = "max" ]; then
    ACT_MEM="无限"
  else
    ACT_MEM=$(( M / 1048576 ))
  fi
  echo "内存 limit: 生产 [${EXP_MEM} MB]  压测 [${ACT_MEM} MB]"
  [ "$ACT_MEM" != "$EXP_MEM" ] && { echo "   ❌ 不一致，数据不可迁移"; FAILED=1; }
else
  echo "内存 limit: 压测环境未设限制 ❌"
  FAILED=1
fi
echo

# ③ JVM 参数
echo "JVM 参数（必须完全一致）:"
echo "  ${JVM_ARGS:-（未设置 JVM_ARGS 环境变量，无法自动对比）}"
echo "  → 请手工核对：-Xmx / -Xms / GC 选型 / 其他 -XX"
echo

# ④ 节点规格
echo "节点信息:"
echo "  可见核数: $(nproc)（注意：容器里可能显示宿主机的核数）"
echo "  内存总量: $(free -h 2>/dev/null | awk '/Mem:/{print $2}' || echo n/a)"
echo

# ⑤ sidecar 检查
echo "同 Pod 内的其他容器（sidecar 会分走资源）:"
echo "  → 在 K8s 里执行: kubectl get pod <pod> -o jsonpath='{.spec.containers[*].name}'"
echo

if [ "$FAILED" -eq 0 ]; then
  echo "✅ 关键项一致（仍需人工核对 JVM 参数与 sidecar）"
else
  echo "❌ 存在不一致项 —— 本次压测数据【不可用于容量规划】"
  echo "   可以用于「相对比较」（优化前后），但必须在报告里声明"
fi

四、K8s 侧的资源与节流检查

#!/usr/bin/env bash
# 在 K8s 环境里使用（需要 kubectl）
POD="${1:?usage: check-k8s-resources.sh <pod>}"

echo "═══ Pod 资源配置 ═══"
kubectl get pod "$POD" -o jsonpath='{range .spec.containers[*]}{.name}{"\t"}{.resources}{"\n"}{end}'
echo

echo "═══ 容器实际使用 vs Limit ═══"
kubectl top pod "$POD" --containers 2>/dev/null || echo "（需要 metrics-server）"
echo

echo "═══ 节流指标 ═══"
kubectl exec "$POD" -- cat /sys/fs/cgroup/cpu.stat 2>/dev/null | head -5 || \
  echo "（无权限 exec，请通过 Prometheus 查询 container_cpu_cfs_throttled_periods_total）"
echo

echo "═══ OOMKilled 历史（内存 limit 过小会静默杀进程）═══"
kubectl get pod "$POD" -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}{"\n"}'
kubectl describe pod "$POD" | grep -A3 -E "Last State|Reason" | head -10

Prometheus 侧的对应查询：

配套代码：结论强度自评与反模式检查

Mon, 01 Jan 0001 00:00:00 +0000

5.8 配套代码：结论强度自评与反模式检查

对应小节：5.8 实验记录与常见反模式两份工具：① 报告前的结论强度自评；② 自动扫描实验档案里的反模式信号。

一、结论强度自评（交互式）

#!/usr/bin/env bash
# tools/check-conclusion-strength.sh
#
# 报告任何性能结论前，过一遍这十二条。
# 这不是形式主义——每一条都对应一个真实的反模式。
set -uo pipefail

FAIL=0
WARN=0

ask() {
  local q="$1"
  local hint="$2"
  echo
  echo "── $q"
  echo "   （$hint）"
  read -r -p "   [y=是 / n=否 / s=跳过] " ans
  case "${ans,,}" in
    y) echo "   ✅" ;;
    n) echo "   ❌ 这一条答「否」，结论强度要打折扣"; FAIL=$((FAIL+1)) ;;
    *) echo "   ⏭  跳过"; WARN=$((WARN+1)) ;;
  esac
}

echo "═══════════════════════════════════════════════════════════"
echo "结论强度自评（十二条）"
echo "═══════════════════════════════════════════════════════════"

ask "① 实验前写了假设和判定标准吗？" \
    "如果没写，可能事后调整了标准（反模式 ❼）"

ask "② 只改了一个变量吗？" \
    "如果有多个改动，无法归因（第 5.1 节）"

ask "③ 有对照组吗？" \
    "没有对照组的话，只有一组数字，不构成结论"

ask "④ 跑了几轮？≥ 3 吗？" \
    "单轮定论是反模式 ❹"

ask "⑤ 报了中位数和波动范围吗？" \
    "只报平均值或最好的一次可能是反模式 ❶❽"

ask "⑥ 知道环境的噪声底线吗？" \
    "不知道就无法判断差异真假（反模式 ❺，第 5.7 节）"

ask "⑦ 差异大于噪声底线和 MDD 吗？" \
    "小于的话可能是噪声（反模式 ❺）"

ask "⑧ 做了统计检验吗？" \
    "缺少显著性的证据（第 5.6 节）"

ask "⑨ 异常轮有成因解释吗？" \
    "没解释就剔除可能是删掉了真实问题（第 5.3 节）"

ask "⑩ 观测配置前后一致吗？" \
    "差异可能来自观测开销（第 5.4 节）"

ask "⑪ 有没有记录失败的实验？" \
    "不记录失败实验会丢失信息（反模式 ❻）"

ask "⑫ 结论里写了「未验证的场景」吗？" \
    "不写等于过度承诺"

echo
echo "═══════════════════════════════════════════════════════════"
echo "结果：$FAIL 条答"否"，$WARN 条跳过"
echo
if [ "$FAIL" -eq 0 ]; then
  echo "✅ 结论强度良好，可以报告"
elif [ "$FAIL" -le 2 ]; then
  echo "⚠️  有 $FAIL 条不足 —— 建议补上后再报告"
  echo "   或者在报告里明确声明这些局限"
else
  echo "❌ 有 $FAIL 条不足 —— 结论目前不可信"
  echo "   建议：补做实验，而不是急着写报告"
fi
echo "═══════════════════════════════════════════════════════════"

提示：脚本里的交互提示如果需要引用「否」这类词，请用中文引号 「」——在 shell 字符串里嵌 ASCII 引号会直接破坏语法。

配套代码：结论模板与证据打包

Mon, 01 Jan 0001 00:00:00 +0000

6.8 配套代码：结论模板与证据打包

对应小节：6.8 结论的写法两件事：① 结论模板；② 把证据文件自动打包成可交付的报告。

一、结论模板

<!-- tools/conclusion-template.md —— 复制到 docs/experiments/<EXP_ID>/CONCLUSION.md -->

# 根因结论：<一句话标题>

> 分析人 / 日期 / 关联实验编号

## 1. 现象

| 维度 | 观测值 |
| --- | --- |
| 接口 | |
| 指标变化 | P50: → 　P95: → 　P99: → |
| 错误率 | |
| 发现时间 | |
| 影响范围 | 全部实例 / 部分实例 / 特定请求类型 |
| 与变更的关系 | 与 YYYY-MM-DD HH:MM 的部署吻合 / 无关联 |

## 2. 延迟分解

| 环节 | P99 | 占比 | 测量方式 |
| --- | --- | --- | --- |
| 网络 + 客户端排队 | | | 客户端 − 网关 |
| 网关处理 + 服务排队 | | | 网关 − 应用内 |
| 应用自身 | | | 应用内 − 依赖之和 |
| └ 依赖 1 | | | 依赖级指标 |
| └ 依赖 2 | | | 依赖级指标 |

## 3. 根因

**<一句话根因>**

具体位置：`<文件:行号>` 或 `<配置项>`

## 4. 证据链

### 证据 1：<说明>

<命令> <输出>

配套代码：评审清单、周报与业务语言

Mon, 01 Jan 0001 00:00:00 +0000

8.8 配套代码：评审清单、周报与业务语言

对应小节：8.8 性能评审与组织落地三部分：① PR 模板（关键 5 项）；② 性能周报生成器；③ 业务语言翻译器。

一、PR 模板（只有关键 5 项）

<!-- .github/pull_request_template.md -->

## 变更说明

<!-- 简要描述这个 PR 做了什么 -->

## 性能影响

> ⚠️ 只需回答**与本次改动相关**的项。无关的项请勾选「无性能影响」。
>
> 详细清单见 `docs/performance-review-checklist.md`（按需查阅）。

- [ ] **无性能影响**（纯文案 / 纯样式 / 纯配置注释等，可跳过下面所有项）

### 如果改动涉及数据访问、外部调用或热路径：

- [ ] **IO / RPC 次数**：这个改动增加了多少次数据库查询、外部调用或序列化？
      → 如果是循环里的调用（N+1），请说明为什么不能批处理
      → 增加了 ____ 次

- [ ] **资源边界**：引入了新的缓存 / 队列 / 线程池 / 连接池吗？
      → 如果有，它们**有容量上限吗**？（无界的缓存/队列会导致 OOM）
      → 上限是 ____

- [ ] **超时与失败**：新增的下游调用有超时吗？
      → 超时值必须**小于上游给的预算**（逐层递减）
      → 超时是 ____ ms，上游预算是 ____ ms
      → 失败时会快速失败还是排队？

- [ ] **可观测性**：新增的接口/依赖有指标吗？
      → 至少要有：延迟（直方图）、错误率
      → 出问题时能否回答「这个接口的 P99 里，数据库占多少毫秒」？

- [ ] **性能验证**：关键路径做了 before/after 对比吗？
      → 附实验编号（如 E08-xxx），或说明为什么不需要
      → 实验编号：____

## 需要同步更新的文档

- [ ] 容量表（`docs/capacity.md`）——如果改变了资源用量
- [ ] SLO 定义（`slo/slos.yaml`）——如果新增了接口或改变了目标
- [ ] 告警规则（`observability/alerts.yml`）——如果新增了关键路径
- [ ] 不需要更新

## 其他

- [ ] 已运行单元测试
- [ ] 已运行 lint / format

这个模板的设计原则：

配套代码：长稳浸泡与三种回归

Mon, 01 Jan 0001 00:00:00 +0000

9.8 配套代码：长稳浸泡与三种回归

对应小节：9.8 步骤七：长稳与回归

一、浸泡测试编排（1 小时）

#!/usr/bin/env bash
# tools/step7a-soak.sh —— 1 小时浸泡 + 全程采集
#
# ═══ 为什么浸泡是【不可省略】的 ═══
# 短时压测只能看到「稳态」，看不到：
#   • 内存泄漏（每小时漏 20MB，3 分钟压测根本看不出来）
#   • 连接/FD 泄漏（同上）
#   • 缓存雪崩（固定 TTL 10min，至少跑 20min 才见两轮脉冲）
#   • 计数器溢出、缓慢退化（P99 每小时涨 5%）
# 这些都是【上线后才炸】的问题，必须在浸泡里抓出来。
set -euo pipefail

OUT="perf/results/step7-soak"
mkdir -p "$OUT"
DURATION="${DURATION:-60m}"
# ── 负载取拐点的 60%~80% ──
# 为什么不用 100%：满负荷下所有问题都会暴露，但那不是生产常态；
#   60%~80% 是"生产高峰"的合理模拟，也是发现慢性问题的最敏感区间
RATE="${RATE:-420}"

echo "═══ 浸泡测试 ═══"
echo "时长：$DURATION　负载：${RATE} RPS（拐点 600 的 70%）"
echo "开始：$(date -Iseconds)"
echo

# ══════════════════════════════════════════════
# 采集器：每 10 秒一个点，覆盖四类指标
# ══════════════════════════════════════════════
collect() {
  local f="$OUT/soak.csv"
  echo "ts,heap_used_mb,heap_committed_mb,gc_pause_sum_s,gc_count,"\
"pool_active,pool_idle,pool_pending,pool_total,"\
"threads_total,fds,p99_ms,rps,cpu_pct,dirties_per_sec,cache_hit_rate" > "$f"

  local t0 gc0
  t0=$(date +%s)
  gc0=0

  while true; do
    local ts m
    ts=$(date +%s)
    m=$(curl -sf http://localhost:8080/metrics 2>/dev/null) || { sleep 10; continue; }

    local heap heapc gcsum gccnt pa pi pp pt thr fds p99 rps cpu dss hit
    heap=$(echo "$m"  | grep '^jvm_memory_used_bytes{.*area="heap"' | awk '{s+=$NF} END{printf "%.1f", s/1048576}')
    heapc=$(echo "$m" | grep '^jvm_memory_committed_bytes{.*area="heap"' | awk '{s+=$NF} END{printf "%.1f", s/1048576}')
    gcsum=$(echo "$m" | grep '^jvm_gc_pause_seconds_sum' | awk '{s+=$NF} END{printf "%.3f", s+0}')
    gccnt=$(echo "$m" | grep '^jvm_gc_pause_seconds_count' | awk '{s+=$NF} END{print s+0}')
    pa=$(echo "$m" | grep '^hikaricp_connections_active' | awk '{print $NF}')
    pi=$(echo "$m" | grep '^hikaricp_connections_idle'   | awk '{print $NF}')
    pp=$(echo "$m" | grep '^db_pool_pending'             | awk '{print $NF}')
    pt=$(echo "$m" | grep '^db_pool_total'               | awk '{print $NF}')
    thr=$(echo "$m"| grep '^jvm_threads_live_threads'    | awk '{print $NF}')
    p99=$(echo "$m"| grep '^app_request_duration_seconds{.*quantile="0.99"' | awk '{print $NF}')
    rps=$(echo "$m"| grep '^http_server_requests_seconds_count' | awk '{s+=$NF} END{printf "%.0f", s}')
    cpu=$(echo "$m"| grep '^process_cpu_usage'           | awk '{printf "%.1f", $NF*100}')
    dss=$(echo "$m"| grep '^jvm_gc_memory_allocated_bytes_total' | awk '{print $NF}')
    hit=$(echo "$m"| grep '^app_cache_hit_rate'          | awk '{printf "%.3f", $NF}')

    # 文件描述符（macOS/Linux 命令不同）
    fds=$(lsof -p "${APP_PID:-0}" 2>/dev/null | wc -l | tr -d ' ')
    [ -z "$fds" ] && fds=0

    echo "$ts,${heap:-0},${heapc:-0},${gcsum:-0},${gccnt:-0},"\
"${pa:-0},${pi:-0},${pp:-0},${pt:-0},"\
"${thr:-0},${fds},${p99:-0},${rps:-0},${cpu:-0},${dss:-0},${hit:-0}" >> "$f"
    sleep 10
  done
}
collect &
COLLECT_PID=$!
trap 'kill $COLLECT_PID 2>/dev/null || true' EXIT

# ── 记录起始状态（用于算增长率）──
curl -sf http://localhost:8080/metrics > "$OUT/metrics-start.txt" || true
jcmd "${APP_PID:?请设置 APP_PID}" GC.heap_info > "$OUT/heap-start.txt" 2>/dev/null || true
jcmd "${APP_PID}" VM.native_memory summary > "$OUT/native-start.txt" 2>/dev/null || true

# ── 跑浸泡压测 ──
cat > /tmp/soak.js <<JS
import http from 'k6/http';
import { SharedArray } from 'k6/data';
export const options = {
  scenarios: { soak: {
    executor: 'constant-arrival-rate',
    rate: ${RATE}, timeUnit: '1s',
    duration: '${DURATION}',
    preAllocatedVUs: 300, maxVUs: 1500,
  }},
  thresholds: {},
  discardResponseBodies: true,
};
const codes = new SharedArray('codes', () =>
  open('/tmp/hot-codes-copy.txt').split('\n').filter(Boolean));
export default function () {
  const c = codes[Math.floor(Math.random() * codes.length)];
  http.get(\`http://localhost:8080/\${c}\`, { redirects: 0 });
}
JS
cp perf/data/hot-codes.txt /tmp/hot-codes-copy.txt

(cd perf/k6 && k6 run --quiet --summary-export="$OLDPWD/$OUT/summary.json" \
  /tmp/soak.js 2>&1 | tee "$OLDPWD/$OUT/k6.log")

# ── 结束状态 ──
curl -sf http://localhost:8080/metrics > "$OUT/metrics-end.txt" || true
jcmd "${APP_PID}" GC.heap_info > "$OUT/heap-end.txt" 2>/dev/null || true
jcmd "${APP_PID}" VM.native_memory summary > "$OUT/native-end.txt" 2>/dev/null || true

kill $COLLECT_PID 2>/dev/null || true
sleep 1

echo
echo "✅ 浸泡完成：$(date -Iseconds)"
echo "   数据 → $OUT/soak.csv"
echo
echo "下一步：python3 tools/step7b-analyze-soak.py"

二、浸泡数据分析（四类趋势 + 缓存雪崩）

#!/usr/bin/env python3
"""tools/step7b-analyze-soak.py —— 分析浸泡数据，判定「稳定 / 泄漏 / 雪崩」

三类典型结论：
  ① 稳定：所有趋势线【斜率≈0】，且 GC 后的基线不上升
  ② 泄漏：某个指标持续单调上升，且 GC 后【基线】仍上升
  ③ 雪崩：某个指标呈【周期性尖峰】，周期与 TTL 吻合

关键："GC 后基线"才是判断内存泄漏的正确指标 ——
  堆使用量上升可能是正常的（缓存填充、JIT 编译），GC 后会下降。
  只有 GC【之后】的谷底仍在上升，才是真正的泄漏。
"""
import csv
import pathlib
import statistics
import sys


def load(p: pathlib.Path):
    rows = []
    with p.open() as f:
        for r in csv.DictReader(f):
            rows.append(r)
    return rows


def slope(xs, ys):
    """最小二乘斜率（单位：y 每秒）"""
    n = len(xs)
    if n < 3:
        return 0.0
    mx, my = statistics.mean(xs), statistics.mean(ys)
    num = sum((x - mx) * (y - my) for x, y in zip(xs, ys))
    den = sum((x - mx) ** 2 for x in xs)
    return num / den if den else 0.0


def trend(rows, key, label, unit="", warn=None):
    xs, ys = [], []
    for r in rows:
        try:
            v = float(r[key] or 0)
        except ValueError:
            continue
        xs.append(float(r["ts"]))
        ys.append(v)

    if len(xs) < 5:
        print(f"  {label:<24s} 数据不足")
        return None

    s = slope(xs, ys)
    per_hour = s * 3600
    first, last = ys[0], ys[-1]
    lo, hi = min(ys), max(ys)

    # ── 判定 ──
    if warn is not None and abs(per_hour) > warn:
        icon = "❌"
    elif abs(per_hour) > warn * 0.3 if warn else False:
        icon = "🟡"
    else:
        icon = "✅"

    print(f"  {icon} {label:<22s} 首 {first:9.2f} → 末 {last:9.2f} {unit}"
          f"   斜率 {per_hour:+9.2f} {unit}/小时   范围 [{lo:.2f}, {hi:.2f}]")
    return {"slope_per_hour": per_hour, "first": first, "last": last,
            "min": lo, "max": hi, "ys": ys, "xs": xs}


def gc_baseline(rows, key: str, gc_key: str):
    """计算「GC 之后」的基线：找每次 gc 计数增加后的第一个采样点"""
    vals = []
    prev_gc = None
    for r in rows:
        try:
            g = float(r[gc_key] or 0)
            v = float(r[key] or 0)
        except ValueError:
            continue
        if prev_gc is not None and g > prev_gc:
            vals.append(v)          # 这一采样点紧跟一次 GC
        prev_gc = g
    return vals


def main(d: str) -> int:
    d = pathlib.Path(d)
    rows = load(d / "soak.csv")
    if len(rows) < 30:
        print(f"❌ 数据点太少（{len(rows)}）—— 浸泡时长不够")
        return 1

    dur_h = (float(rows[-1]["ts"]) - float(rows[0]["ts"])) / 3600
    print(f"═══ 浸泡分析（{len(rows)} 个点 / {dur_h:.2f} 小时）═══\n")

    # ══════════════════════════════════════════
    # ① 内存
    # ══════════════════════════════════════════
    print("① 内存")
    heap = trend(rows, "heap_used_mb", "堆使用量", "MB", warn=50)

    # ── 关键：GC 后基线 ──
    base = gc_baseline(rows, "heap_used_mb", "gc_count")
    if len(base) >= 3:
        b_first, b_last = statistics.mean(base[:3]), statistics.mean(base[-3:])
        b_delta = b_last - b_first
        print(f"     ⭐ GC 后基线   首 {b_first:.1f} → 末 {b_last:.1f} MB"
              f"   Δ {b_delta:+.1f} MB")
        if b_delta > 20:
            print(f"        ❌ GC 后基线上升 —— 【真泄漏】")
            print(f"           堆使用量上升 + GC 后基线上升 = 对象被持有")
            print(f"           下一步：jmap -histo:live 对比两次，找增长的类型")
        else:
            print(f"        ✅ GC 后基线稳定 —— 无泄漏")
            print(f"           （堆使用量上升但 GC 后回落 = 正常缓存/JIT）")
    else:
        print("     ⚠️  GC 次数太少，无法判断 GC 后基线")

    print()
    print("② GC")
    trend(rows, "gc_pause_sum_s", "GC 停顿累计", "s", warn=3.0)
    gc_rates = []
    for i in range(1, len(rows)):
        try:
            dg = float(rows[i]["gc_count"]) - float(rows[i-1]["gc_count"])
            dt = float(rows[i]["ts"]) - float(rows[i-1]["ts"])
            if dt > 0:
                gc_rates.append(dg / dt * 60)
        except ValueError:
            pass
    if gc_rates:
        early = statistics.mean(gc_rates[:len(gc_rates)//4])
        late = statistics.mean(gc_rates[-len(gc_rates)//4:])
        print(f"     GC 频率         首段 {early:.1f} 次/分 → 末段 {late:.1f} 次/分")
        if late > early * 2:
            print(f"        ❌ GC 频率翻倍 —— 分配速率上升或内存压力增大")
        else:
            print(f"        ✅ GC 频率稳定")

    print()
    print("③ 连接与 FD")
    trend(rows, "pool_active", "池活跃", warn=5)
    trend(rows, "pool_pending", "池等待", warn=0.5)
    trend(rows, "threads_total", "线程数", warn=5)
    trend(rows, "fds", "文件描述符", warn=10)

    print()
    print("④ 延迟与吞吐")
    trend(rows, "p99_ms", "P99", "ms", warn=5)
    trend(rows, "cpu_pct", "CPU", "%", warn=10)
    trend(rows, "cache_hit_rate", "缓存命中率", warn=0.05)
    trend(rows, "heap_committed_mb", "堆已提交", "MB", warn=100)

    # ══════════════════════════════════════════
    # ⑤ 缓存雪崩检测（埋雷 ③）⭐
    # ══════════════════════════════════════════
    print()
    print("⑤ 缓存雪崩检测（埋雷 ③）")
    print("   检测方法：看 DB 相关指标的【周期性】")
    print("   周期预期：约 10 分钟（= 缓存 TTL）")
    print()

    # 用 RPS 的差分找脉冲
    rps_deltas = []
    for i in range(1, len(rows)):
        try:
            dr = float(rows[i]["rps"]) - float(rows[i-1]["rps"])
            dt = float(rows[i]["ts"]) - float(rows[i-1]["ts"])
            if dt > 0:
                rps_deltas.append((float(rows[i]["ts"]), dr / dt * 60))
        except ValueError:
            pass

    if rps_deltas:
        rates = [v for _, v in rps_deltas]
        mean_r = statistics.mean(rates)
        sd_r = statistics.stdev(rates) if len(rates) > 1 else 0
        # ── 找超过 均值+3σ 的尖峰 ──
        spikes = [(ts, v) for ts, v in rps_deltas
                  if sd_r > 0 and v > mean_r + 3 * sd_r]

        print(f"   DB 请求速率：均值 {mean_r:.0f}/分　标准差 {sd_r:.0f}")
        print(f"   超过 +3σ 的尖峰：{len(spikes)} 个")

        if len(spikes) >= 2:
            intervals = [spikes[i][0] - spikes[i-1][0]
                         for i in range(1, len(spikes))]
            avg_interval = statistics.mean(intervals) / 60
            print(f"   尖峰间隔：{[f'{i/60:.1f}分' for i in intervals]}")
            print(f"   平均间隔：{avg_interval:.1f} 分钟")
            print()
            if 8 <= avg_interval <= 12:
                print(f"   ❌ 尖峰周期 ≈ {avg_interval:.0f} 分钟，与缓存 TTL(10min) 【吻合】")
                print(f"      → 确认埋雷 ③：固定 TTL 导致集体失效")
                print(f"      → 修复：TTL 加 ±20% 抖动（见 07-step6-optimize.md 优化 4）")
            else:
                print(f"   ⚠️  有周期性尖峰但与 TTL 不吻合 —— 排查其他周期性任务")
        else:
            print(f"   ✅ 未发现周期性尖峰（或 TTL 抖动已生效）")
    else:
        print("   ⚠️  数据不足")

    # ── 写报告 ──
    (d / "soak-report.md").write_text(f"""# 浸泡测试报告

- 时长：{dur_h:.2f} 小时
- 数据点：{len(rows)}

## 结论

（请根据上面的输出填写）

## 判读要点

1. **GC 后基线**才是泄漏判据，不是堆使用量
2. 任何【单调上升】的指标都要解释：
   - 缓存填充 → 正常，会收敛
   - 线程/FD/连接 → 泄漏
3. 周期性尖峰要【与已知周期对齐】才能归因
""")
    print()
    print(f"✅ 报告 → {d}/soak-report.md")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1
                  else "perf/results/step7-soak"))

预期输出：

配套代码 on Dorkytiger 的小屋

配套代码：A/B/A' 对照编排与环境漂移检测

5.1 配套代码：A/B/A’ 对照编排与环境漂移检测

一、A/B/A’ 实验编排脚本

二、A/B/A’ 结果分析（检测环境漂移）

三、预期输出

配套代码：k6 进阶用法与压测机自查

4.1 配套代码：k6 进阶用法与压测机自查

一、多场景组合（一个脚本测多种流量）

配套代码：从延迟分解到优先级排序

7.1 配套代码：从延迟分解到优先级排序

一、延迟分解 → 层级映射

二、候选优化的排序器

配套代码：分析工作流与假设台账

6.1 配套代码：分析工作流与假设台账

一、现象量化表模板

配套代码：台阶式提升与 PrintCompilation 解读

2.1 配套代码：台阶式提升与 PrintCompilation 解读

一、实验：在不同调用次数下测量同一个方法

二、预期输出形态

三、观察编译事件

配套代码：同一个函数，为什么测出三个不同的数字

0.1 配套代码：同一个函数，为什么测出三个不同的数字

一、这段代码想说明什么

二、代码

三、预期输出（形态）

配套代码：四层指标的埋点骨架

1.1 配套代码：四层指标的埋点骨架

一、注册表与四层指标的对应关系

配套代码：渐进退化模拟与门禁经济性

8.1 配套代码：渐进退化模拟与门禁经济性

一、渐进退化模拟

配套代码：短链服务骨架与六颗埋雷

9.1 配套代码：短链服务骨架与六颗埋雷

一、目录结构

二、领域模型与 DTO

三、埋雷 ⑥：synchronized 生成短码

四、埋雷 ① ② ④：Repository 的三个问题

五、埋雷 ③：缓存 TTL 无抖动

六、Service 层：编排 + 短码冲突重试

配套代码：CI 微基准门禁

8.2 配套代码：CI 微基准门禁

一、CI workflow（完整版）

配套代码：SLO 表与延迟预算校验

9.2 配套代码：SLO 表与延迟预算校验

一、SLO 定义文件

二、延迟预算校验器

三、把 SLO 变成压测阈值

配套代码：减少工作的五种模式

7.2 配套代码：减少工作的五种模式

一、❶ 批处理：N 次变 1 次

配套代码：延迟分解的 PromQL 与自动计算

6.2 配套代码：延迟分解的 PromQL 与自动计算

一、三段分解的 PromQL

二、自动分解脚本（从 Prometheus 拉数据）

三、基于 tracing 的精确分解（推荐）

配套代码：时长规划与预热判定

5.2 配套代码：时长规划与预热判定

一、时长规划器

配套代码：直方图合并实验

1.2 配套代码：直方图合并实验

一、先实现一个最小的直方图

二、预期输出

配套代码：组件基准（Testcontainers + 采样循环）

3.2 配套代码：组件基准（Testcontainers + 采样循环）

一、测试容器与数据准备

二、采样循环与百分位统计

三、四件事分开测

四、预期输出与判读

配套代码：调用点类型数量与去优化

2.2 配套代码：调用点类型数量与去优化

一、实验：单态 / 双态 / 巨态

二、预期输出形态

配套代码：async-profiler 命令全集与火焰图解读

4.3 配套代码：async-profiler 命令全集与火焰图解读

一、安装与权限（最容易卡住的一步）

配套代码：三个测量点的埋点与延迟分解

1.3 配套代码：三个测量点的埋点与延迟分解

一、依赖级计时器

配套代码：全链路性能门禁

三、埋雷 ⑥：`synchronized` 生成短码