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

// 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()
}

/**
 * 模拟一次"页面加载"：并行调用 downstreams 个服务，
 * 每个服务有 slowRatio 的概率变慢。只要有一个慢，整页就慢。
 */
fun simulateComposite(trials: Int, downstreams: Int, slowRatio: Double, seed: Int = 7): Double {
    val rnd = Random(seed)
    var slowPages = 0
    repeat(trials) {
        var pageIsSlow = false
        for (d in 0 until downstreams) {
            if (rnd.nextDouble() < slowRatio) { pageIsSlow = true; break }
        }
        if (pageIsSlow) slowPages++
    }
    return slowPages.toDouble() / trials
}

fun demonstrateTailAmplification() {
    val p = 0.01
    println("=== 实验二：尾延迟放大（每个下游各有 1% 概率变慢）===")
    println("下游数量 |  整页变慢的概率 |  理论值 1-(1-p)^n")
    for (n in listOf(1, 3, 5, 10, 20)) {
        val measured = simulateComposite(200_000, n, p)
        val theory = 1 - Math.pow(1 - p, n.toDouble())
        println("%6d   |  %12.2f%%   |  %10.2f%%".format(n, measured * 100, theory * 100))
    }
    println()
    println("注意第 10 行和第 20 行：单个服务 P99 都合格，但整页已经有 10%~18% 是慢的。")
    println()
}

下游数量 |  整页变慢的概率 |  理论值 1-(1-p)^n
     1   |          1.00%   |        1.00%
     3   |          2.98%   |        2.97%
     5   |          4.90%   |        4.90%
    10   |          9.55%   |        9.56%
    20   |         18.21%   |       18.21%

fun demonstratePercentileAggregationTrap() {
    // A 实例：健康，1% 慢请求只到 20 ms
    // （heavyTailed 的慢尾固定是 800~1200ms，这里手工构造更贴近本场景的两个实例）
    val rndA = Random(1)
    val a = LongArray(100_000) { if (rndA.nextDouble() < 0.01) rndA.nextLong(15, 25) else rndA.nextLong(4, 7) }

    // B 实例：有问题，1% 慢请求到 2000 ms
    val rndB = Random(2)
    val b = LongArray(100_000) { if (rndB.nextDouble() < 0.01) rndB.nextLong(1800, 2200) else rndB.nextLong(4, 7) }

    val p99a = percentile(a.sortedArray(), 0.99)
    val p99b = percentile(b.sortedArray(), 0.99)

    // ❌ 错误做法：把两个实例的 P99 求平均
    val wrong = (p99a + p99b) / 2.0

    // ✅ 正确做法：把样本合并（相当于合并直方图的桶）后重新计算
    val merged = LongArray(a.size + b.size)
    a.copyInto(merged, 0)
    b.copyInto(merged, a.size)
    val right = percentile(merged.sortedArray(), 0.99)

    println("=== 实验三：百分位不能直接平均 ===")
    println("A 实例 P99        : %6d ms".format(p99a))
    println("B 实例 P99        : %6d ms".format(p99b))
    println("❌ 两个 P99 求平均 : %6.0f ms   ← 这个数字不代表任何真实用户".format(wrong))
    println("✅ 合并样本后计算  : %6d ms   ← 这才是真实用户看到的分位数".format(right))
    println("误差              : %.0f 倍".format(wrong / right))
    println()
    println("结论：Prometheus 的 summary 类型、以及任何在客户端算好的百分位，")
    println("      都因为无法跨实例聚合而失真。延迟指标必须用直方图（histogram）。")
}

A 实例 P99        :      20 ms
B 实例 P99        :    2000 ms
❌ 两个 P99 求平均 :     1010 ms   ← 这个数字不代表任何真实用户
✅ 合并样本后计算  :      20 ms   ← 因为 99% 的请求仍然很快
误差              : 50 倍