HdrHistogram_rust

HdrSample 是 Gil Tene 的 HdrHistogram 的原生 Rust 版本。它提供了在大范围内以可配置的精度记录和分析样本数据值计数的功能。生成的“HDR”直方图允许快速准确地分析数据极端范围，如延迟。

HdrHistogram

以下是从 HdrHistogram 网站上的描述。建议用户阅读原始 Java 实现 的文档，因为大部分概念都直接适用于 Rust 版本。

HdrHistogram 支持在可配置的整数值范围和该范围内可配置的值精度内记录和分析样本数据值计数。值精度用记录的值的有效数字数量表示，并控制值量化行为和任何给定级别上的后续值分辨率。

例如，直方图可以配置为跟踪 0 到 3,600,000,000 之间观察到的整数值的计数，同时在该范围内保持 3 位有效数字的值精度。因此，范围内的值量化不会大于任何值的 1/1,000 (或 0.1%)。此示例直方图可以用于跟踪和分析介于 1 微秒和 1 小时之间的响应时间计数，同时保持从 1 微秒到 1 毫秒的 1 微秒分辨率，从 1 毫秒到 1 秒的 1 毫秒分辨率，以及从 1 秒到 1,000 秒的 1 秒分辨率。在其最大跟踪值（1 小时）时，它仍然保持 3.6 秒（或更好）的分辨率。

HDR直方图旨在记录延迟和性能敏感应用中的值测量直方图。测量显示，在2014年左右的现代英特尔CPU上，值记录时间低至3-6纳秒。HDR直方图在空间和时间上保持固定成本。直方图的内存占用是固定的，记录数据值或遍历它们时没有分配操作。内存占用固定，不受记录的数据值样本数量的影响，仅取决于选择的动态范围和精度。记录样本所需的工作量是恒定的，并且直接计算存储索引位置，因此在记录数据值时不需要迭代或搜索。

如果您正在寻找HdrHistogram_c的FFI绑定，请使用hdrhistogram_c存储库。

与库交互

HdrSample的API遵循原始HdrHistogram Java实现的API，并进行了一些修改，使其在Rust中使用更符合习惯。本节中的描述已根据Python移植中给出的说明进行修改，因为它比Java文档提供了更好的首次使用HdrHistogram的介绍。

HdrSample通常以两种模式之一使用：记录样本或查询分析。在分布式部署中，记录可能是在远程（可能在多个位置）执行的，然后在中央位置进行聚合分析。

记录样本

使用Histogram结构体上的::new方法创建直方图实例。这些方法有三种变体：new、new_with_max和new_with_bounds。这些变体中的第一个仅设置样本数据的所需精度，但将值范围保持开放，以便记录任何值。以这种方式创建的Histogram（或其中已显式启用自动调整大小）将自动调整大小，如果遇到无法适应当前数据集的值，则会自动调整大小。使用new_with_max设置要记录的值的上限，并禁用自动调整大小，从而在记录过程中防止任何重新分配。如果应用程序尝试记录大于此最大界限的值，则record调用将返回错误。最后，new_with_bounds限制数据集可以表示的最小值，从而减少需要覆盖的范围（从而减少整体分配大小）。

例如，下面的示例显示了如何创建一个可以计数[1..3600000]范围内的值的Histogram，以1%的精度，这可以用于跟踪[1 毫秒..1 小时]范围内的延迟。

use hdrhistogram::Histogram;
let mut hist = Histogram::<u64>::new_with_bounds(1, 60 * 60 * 1000, 2).unwrap();

// samples can be recorded using .record, which will error if the value is too small or large
hist.record(54321).expect("value 54321 should be in range");

// for ergonomics, samples can also be recorded with +=
// this call will panic if the value is out of range!
hist += 54321;

// if the code that generates the values is subject to Coordinated Omission,
// the self-correcting record method should be used instead.
// for example, if the expected sampling interval is 10 msec:
hist.record_correct(54321, 10).expect("value 54321 should be in range");

use hdrhistogram::Histogram;
let hist = Histogram::<u64>::new(2).unwrap();
// ...
println!("# of samples: {}", hist.len());
println!("99.9'th percentile: {}", hist.value_at_quantile(0.999));

use hdrhistogram::Histogram;
let hist = Histogram::<u64>::new(2).unwrap();
// ...
for v in hist.iter_recorded() {
    println!("{}'th percentile of data is {} with {} samples",
        v.percentile(), v.value_iterated_to(), v.count_at_value());
}

[dependencies]
hdrhistogram = "7"

extern crate hdrhistogram;