Micrometer 的百分位数（如 p95、p99）并非基于全局历史数据，而是依赖滑动时间窗口内的采样数据；该窗口由 DistributionStatisticConfig.expiry() 和 bufferSize 共同控制，需显式配置才能调整统计时长与精度。
micrometer 的百分位数（如 p95、p99）并非基于全局历史数据，而是依赖滑动时间窗口内的采样数据；该窗口由 `distributionstatisticconfig.expiry()` 和 `buffersize` 共同控制，需显式配置才能调整统计时长与精度。
在 Micrometer 中，百分位数计算本身不依赖“固定时间范围”（如最近 1 分钟或 5 分钟），而是基于一个滑动的、有界的数据缓冲区（sliding window buffer）。这个缓冲区通过两个关键参数协同工作：
- expiry: 缓冲区中每个样本的最大存活时间（单位：Duration），超过此时间的样本将被自动驱逐；
- bufferSize: 缓冲区能容纳的最大样本数量（默认为 100），当新样本写入且缓冲已满时，最旧样本会被淘汰。
二者共同决定了参与百分位计算的“有效数据集”的时间跨度和规模——实际时间范围 ≈ bufferSize × 平均采样间隔，但受 expiry 强约束：即使缓冲未满，超期样本也会被清除。因此，expiry 是真正的“时间边界”，而 bufferSize 控制分辨率与内存开销。
✅ 正确配置示例（Spring Boot）
@Bean
public MeterRegistryCustomizer<MeterRegistry> metricsCustomizer() {
return registry -> registry.config()
.meterFilter(new MeterFilter() {
@Override
public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) {
// 设置：保留最多 1000 个样本，且每个样本最长存活 2 分钟
return DistributionStatisticConfig.builder()
.percentiles(0.5, 0.9, 0.95, 0.99, 0.999)
.expiry(Duration.ofMinutes(2)) // ⚠️ 关键：定义时间窗口上限
.bufferSize(1000) // 提升统计稳定性（尤其高 QPS 场景）
.build()
.merge(config);
}
});
}? 注意：expiry 必须显式设置才生效；若未指定，Micrometer 使用默认值（通常为 300s / 5 分钟），但不同注册表实现（如 PrometheusMeterRegistry）可能有额外行为（例如 Prometheus 客户端会按 scrape 间隔重置分布摘要）。
⚠️ 重要注意事项
- 无全局“滚动时间窗口”概念：Micrometer 不维护跨 scrape 周期的持久化滑窗。每次指标暴露（如 /actuator/prometheus）时，各 Timer/DistributionSummary 仅基于其当前内存缓冲区计算并输出 quantile 值。因此，Prometheus 抓取到的 p99 是“最后一次 scrape 前 expiry 窗口内样本的 p99”，而非“过去 N 分钟的聚合 p99”。
- 高基数风险：增大 bufferSize 或延长 expiry 会增加内存占用，尤其在高并发、多标签维度场景下易引发 OOM。建议结合压测评估。
- Prometheus 后端限制：Prometheus 自身不存储原始样本，仅抓取 Micrometer 暴露的 quantile 值。如需更精确的长期百分位分析（如“过去 1 小时 p99”），应改用服务端聚合（如 PromQL 的 histogram_quantile() + 直方图桶）或启用 Micrometer 的 publishPercentileHistogram = true（生成直方图供 PromQL 计算）。
- Azure Cosmos DB 特殊场景：若使用 CosmosMicrometerMeterOptions（如 configurePercentiles(...)），其底层仍遵循 Micrometer 的 DistributionStatisticConfig 机制，expiry 和 bufferSize 需通过 MeterFilter 统一配置，而非在 Cosmos 专属选项中设置。
✅ 推荐生产实践
| 场景 | 建议配置 |
|---|---|
| 低延迟敏感型 API（如支付） | expiry = 30s, bufferSize = 500 → 快速响应瞬时毛刺 |
| 批处理任务监控 | expiry = 5m, bufferSize = 2000 → 平滑偶发长尾 |
| 调试慢请求根因 | 启用 publishPercentileHistogram = true + Prometheus histogram_quantile(0.99, sum(rate(http_server_requests_seconds_bucket[5m])) by (le)) |
总之，Micrometer 的 percentile 时间范围由 expiry 主导、bufferSize 辅助调控，没有独立的“time range”配置项，但通过二者可精准控制统计时效性与资源消耗的平衡点。
