跳到主要内容

分布摘要

DeepSeek V3 中英对照 Distribution Summaries

分布摘要（Distribution Summary）用于追踪事件的分布情况。它在结构上与计时器（Timer）类似，但记录的值并不代表时间单位。例如，你可以使用分布摘要来测量访问服务器的请求的有效载荷大小。

以下示例创建了一个分布摘要：

DistributionSummary summary = registry.summary("response.size");
java

该接口包含一个用于分布摘要的流畅构建器：

DistributionSummary summary = DistributionSummary
    .builder("response.size")
    .description("a description of what this summary does") // optional
    .baseUnit("bytes") // optional // <1>
    .tags("region", "test") // optional
    .scale(100) // optional // <2>
    .register(registry);
java

  • 添加基本单位以实现最大可移植性。基本单位是某些监控系统命名约定的一部分。如果忘记添加基本单位并且违反了命名约定，不会产生不利影响。

  • 可选地，您可以提供一个缩放因子，每个记录的样本在记录时都会乘以该因子。

备注

对于基本的 DistributionSummary 实现（例如 CumulativeDistributionSummary 和 StepDistributionSummary），最大值（命名为 max）是一个时间窗口最大值（TimeWindowMax）。这意味着它的值是在一个时间窗口内的最大值。如果在时间窗口长度内没有记录新的值，最大值会在新时间窗口开始时重置为 0。值完全过期的时间窗口大小是 DistributionStatisticConfig 中的 expiry 乘以 bufferLength。expiry 默认值为仪表注册表的步长，除非显式设置为不同的值，而 bufferLength 默认为 3。时间窗口最大值用于在资源压力较大触发延迟后捕获后续间隔内的最大延迟，并防止指标被发布。百分位数也是时间窗口百分位数（TimeWindowPercentileHistogram）。

缩放和直方图​

Micrometer 的预选百分位直方图桶是从 1 到 Long.MAX_VALUE 的所有整数。目前，minimumExpectedValue 和 maximumExpectedValue 用于控制桶集的基数。如果我们尝试检测到您的最小/最大值产生了一个小范围，并将预选桶域缩放到您的摘要范围，我们就没有其他杠杆来控制桶的基数。

相反，如果你的摘要的域更加受限，可以通过一个固定的因子来缩放摘要的范围。到目前为止，我们听到的用例是针对域为 [0,1] 的比率摘要。在这种情况下，我们可以使用以下代码创建从 0 到 100 的值：

DistributionSummary.builder("my.ratio").scale(100).register(registry)
java

这样，比率最终会落在 [0,100] 的范围内，我们可以将 maximumExpectedValue 设置为 100。如果你关心特定的比率，可以将其与自定义的 SLO 边界配对使用：

DistributionSummary.builder("my.ratio")
   .scale(100)
   .serviceLevelObjectives(70, 80, 90)
   .register(registry)
java

内存占用估计​

分布摘要的总内存占用可能会有很大差异，具体取决于您选择的选项。以下内存消耗表基于各种功能的使用情况。这些数据假设没有标签且环形缓冲区长度为 3。添加标签和增加缓冲区长度都会在一定程度上增加总内存占用。总存储空间也可能因注册表实现的不同而有所变化。

  • R = 环形缓冲区长度。我们在所有示例中假设默认值为 3。R 通过 DistributionSummary.Builder#distributionStatisticBufferLength 设置。

  • B = 直方图的总桶数。它可以是 SLO 边界或百分位数直方图桶。默认情况下，摘要没有最小值和最大值预期值，因此我们传输所有 276 个预定的直方图桶。当您打算传输百分位数直方图时，应始终使用 minimumExpectedValue 和 maximumExpectedValue 来限制分布摘要。

  • M = 时间衰减最大值。104 字节。

  • Fb = 固定边界直方图。8b * B * R。

  • Pp = 百分位数精度。默认情况下为 1。通常范围为 [0, 3]。Pp 通过 DistributionSummary.Builder#percentilePrecision 设置。

  • Hdr(Pp) = 高动态范围直方图。

    • 当 Pp = 0 时：1.9kb * R + 0.8kb

    • 当 Pp = 1 时：3.8kb * R + 1.1kb

    • 当 Pp = 2 时：18.2kb * R + 4.7kb

    • 当 Pp = 3 时：66kb * R + 33kb

客户端百分位数直方图和/或 SLOs公式示例
否否M~0.1kb
否是M + Fb对于限制为 66 个桶的百分位数直方图，~6kb
是是M + Hdr(Pp)对于默认情况下添加的 0.95 百分位数，~12.6kb
备注

对于 Prometheus 来说，R 始终 等于 1，无论你如何尝试通过 DistributionSummary.Builder 进行配置。Prometheus 存在这一特殊情况是因为它期望接收永远不会重置的累积直方图数据。