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

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

// src/main/kotlin/Routes.kt
package app

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Timer
import io.micrometer.core.instrument.distribution.DistributionStatisticConfig
import metrics.DependencyTimers
import java.time.Duration

fun Application.orderRoutes(
    registry: MeterRegistry,
    deps: DependencyTimers,
    repo: OrderRepository,
    cache: OrderCache,
) {
    // ── 测量点 ③：应用内 —— handler 级别（这是"应用自身处理时间"） ──
    val handlerTimer = Timer.builder("app.handler.duration")
        .description("handler 内部耗时（不含网络与网关）")
        .publishPercentileHistogram(true)
        .serviceLevelObjectives(*metrics.sloBuckets.toTypedArray())
        .register(registry)

    routing {
        get("/orders/{id}") {
            val id = call.parameters["id"]!!
            val sample = Timer.start(registry)          // ← 从进入 handler 开始计时

            try {
                // 依赖 1：缓存（可能命中，可能未命中）
                val cached = deps.timed(deps.redis, registry) { cache.get(id) }

                val order = cached ?: deps.timed(deps.postgres, registry) {
                    // 注意：这个 Timer 覆盖了「等连接 + 执行 SQL + 映射结果」
                    repo.findById(id)
                }

                // 依赖 2：下游服务（并行调用时要用 async）
                val user = deps.timed(deps.downstream, registry) {
                    userClient.fetch(order.userId)
                }

                call.respond(order.copy(userName = user.name))
            } finally {
                sample.stop(handlerTimer)               // ← 到响应返回为止
            }
        }
    }
}

# 应用自身开销（序列化、业务计算、锁等）
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(http_server_requests_seconds_bucket{uri="/orders/{id}"}[5m])))
-
histogram_quantile(0.99,
  sum by (le) (rate(app_handler_duration_seconds_bucket[5m])))

// ❌ 错误 1：分母只算成功请求 → 超时的慢请求被剔除
if (success) timer.record(duration)

// ✅ 正确：无论成败都记录
try { ... } finally { sample.stop(timer) }

// ❌ 错误 2：计时范围漏掉序列化
sample.stop(timer)          // 在 respond 之前就停止了
call.respond(order)         // 序列化发生在这里，没被计入

// ✅ 正确：把 respond 包在计时范围内（或用 Ktor 插件的全量计时）

// ❌ 错误 3：用 requestId / userId 当标签 → 指标基数爆炸
registry.counter("req", "id", requestId)

// ✅ 正确：只用可枚举维度
registry.counter("req", "uri", "/orders/{id}", "status", "200")

// ❌ 错误 4：Timer 名字里带动态值
Timer.builder("req.$uri")   // 每个 URL 一个 Timer

// ✅ 正确：固定名字 + 标签
Timer.builder("req").tag("uri", routeTemplate)