hdrhistogram 0.10.3

Python API

此库的使用者通常扮演以下两种角色之一（有时两者都是）

• 将值记录到1个或多个直方图中（直方图配置）

• 分析和显示直方图内容及其特征（直方图查询）

在分布式情况下，直方图配置可以在远程（可能在多个位置）完成，然后在中心位置进行聚合以进行分析。

使用 HdrHistogram 类可以创建直方图实例，并指定可追踪的最小和最大值以及所需的精度位数。例如，创建一个可以计算 [1..3600000] 范围内值且精度为 1% 的直方图（例如，用于跟踪 [1 毫秒..1 小时] 范围内的延迟）

histogram = HdrHistogram(1, 60 * 60 * 1000, 2)

默认情况下，计数器为 64 位，但也可以指定 16 或 32 位计数器（word_size 选项设置为 2 或 4 字节）。请注意，在此版本中未测试计数器溢出，因此在使用较小的计数器大小时请谨慎。

一旦创建，很容易向直方图添加值

histogram.record_value(latency)

如果生成值的代码受到协调省略的影响，请使用该方法的修正版本（例如，当预期间隔为 10 毫秒时）

histogram.record_corrected_value(latency, 10)

在任何时候，都可以查询直方图以返回任何属性，例如获取记录的总值数或给定百分位数处的值

count = histogram.get_total_count()
value = histogram.get_value_at_percentile(99.9)

可以使用记录迭代器遍历记录的值

for item in histogram.get_recorded_iterator():
    print('value=%f count=%d percentile=%f' %
            item.value_iterated_to,
            item.count_added_in_this_iter_step,
            item.percentile)

histoblob（base64 编码/压缩的直方图）是一种方便的序列化和存储直方图实例的方法，而不会丢失精度（无损）。然后可以将生成的 base64 字符串存储在标准容器中，如 JSON 文档、XML、CSV 等

可以通过调用压缩方法生成直方图实例的 histoblob

histoblob = histogram.encode()

可以使用解码方法将 histoblob 解码为直方图实例

decoded_histogram = HdrHistogram.decode(histoblob)
count = decoded_histogram.get_total_count()

在聚合的情况下，可以使用 decode_and_add 方法

aggregation_histogram.decode_and_add(histoblob)

如果您想以绘图友好的百分位数表格格式（.hgrm）打印直方图

histogram.output_percentile_distribution(file, scaling_ratio)

有关如何使用 API 的更多信息

• 浏览 Python 代码，并检查每个方法的注释部分中的 API 文档（如有可用）

• 最好的文档是通过查看测试目录下的测试代码来实现的

测试代码（https://github.com/HdrHistogram/HdrHistogram_py/blob/master/test/test_hdrhistogram.py）几乎涵盖了所有 API。

安装

先决条件

确保您有 python 3.x 和 pip 已经安装

pip install hdrhistogram

pip install tox
# cd to the proper location to clone the repository
git clone https://github.com/HdrHistogram/HdrHistogram_py.git
cd HdrHistogram_py

$ tox
GLOB sdist-make: /openstack/pyhdr/HdrHistogram_py/setup.py
31 passed, 2 skipped in 5.14 seconds
py3 inst-nodeps: /openstack/pyhdr/HdrHistogram_py/.tox/dist/hdrhistogram-0.5.2.zip
py3 runtests: PYTHONHASHSEED='4015036329'
py3 runtests: commands[0] | py.test -q -s --basetemp=/openstack/pyhdr/HdrHistogram_py/.tox/py3/tmp
s......................ss.........
31 passed, 3 skipped in 5.11 seconds
pep8 inst-nodeps: /openstack/pyhdr/HdrHistogram_py/.tox/dist/hdrhistogram-0.5.2.zip
pep8 runtests: PYTHONHASHSEED='4015036329'
pep8 runtests: commands[0] | flake8 hdrh test
lint inst-nodeps: /openstack/pyhdr/HdrHistogram_py/.tox/dist/hdrhistogram-0.5.2.zip
lint installed: astroid==1.5.3,backports.functools-lru-cache==1.4,configparser==3.5.0,enum34==1.1.6,flake8==3.3.0,hdrhistogram==0.5.2,isort==4.2.15,lazy-object-proxy==1.3.1,mccabe==0.6.1,pbr==3.1.1,py==1.4.34,pycodestyle==2.3.1,pyflakes==1.5.0,pylint==1.7.1,pytest==3.1.2,singledispatch==3.4.0.3,six==1.10.0,wrapt==1.10.10
lint runtests: PYTHONHASHSEED='4015036329'
lint runtests: commands[0] | pylint --rcfile pylint.rc hdrh test

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

________________________________________________________________ summary ________________________________________________________________
  py3: commands succeeded
  pep8: commands succeeded
  lint: commands succeeded
  congratulations :)

从 histoblob 中显示百分位数表 (.hgrm)

要打印任何 histoblob 的 .hgrm 百分位数表，请使用 dump_hdrh 工具（与包一起安装）。

$ dump_hdrh

Usage: dump_hdrh [<string encoded hdr histogram>]*

您可以将一个或多个 histoblob 传递给该工具

$ dump_hdrh 'HISTFAAAACl4nJNpmSzMwMDAxQABzFCaEUzOmNZg/wEi0NzIyPSYlWmpGBMAh4gG4A=='

Dumping histogram: HISTFAAAACl4nJNpmSzMwMDAxQABzFCaEUzOmNZg/wEi0NzIyPSYlWmpGBMAh4gG4A==

      Value     Percentile TotalCount 1/(1-Percentile)

139647.000 0.000000000000          1           1.00
139647.000 0.100000000000          1           1.11
139647.000 0.190000000000          1           1.23
139647.000 0.271000000000          1           1.37
187135.000 0.343900000000          2           1.52
187135.000 0.409510000000          2           1.69
187135.000 0.468559000000          2           1.88
187135.000 0.521703100000          2           2.09
187135.000 0.569532790000          2           2.32
187135.000 0.612579511000          2           2.58
187135.000 0.651321559900          2           2.87
477695.000 0.686189403910          3           3.19
477695.000 1.000000000000          3
#[Mean    =   268074.667, StdDeviation   =   149397.390]
#[Max     =   477695.000, TotalCount     =        3.000]
#[Buckets =           14, SubBuckets     =         2048]

分布式直方图的聚合

将多个直方图聚合为1在以下情况下很有用：生成这些单个直方图的工具需要以分布式方式运行，以便足够地扩展。例如，wrk2工具（https://github.com/giltene/wrk2.git）是一个测量大量连接的HTTP请求延迟的绝佳工具。尽管这个工具可以支持每个进程数千个连接，但某些配置需要以数百万个连接的规模运行，可能需要运行大量wrk进程，可能是在大量服务器上。鉴于每个wrk实例可以生成一个单独的直方图，评估整个系统的规模需要将这些直方图聚合为1，而不影响结果的准确性。因此，有两个问题需要解决

• 找到一种正确聚合多个直方图而不丢失任何细节的方法

• 找到一种将所有这些直方图传输到中央位置的方法

此库为问题的聚合部分提供了一种解决方案

• 重用HDR直方图压缩格式版本1来编码和压缩可以发送到聚合器的完整直方图

• 提供Python API，以便轻松高效

  • 将直方图实例压缩成可传输的字符串

  • 解压缩压缩的直方图并将其添加到现有直方图

请参阅单元测试代码（test/test_hdrhistogram.py），以了解如何使用这些API。

直方图线编码和大小

直方图使用基于改进的ZigZag LEB128编码的HdrHistogram V2格式进行编码，其中

• 连续零计数器被编码为一个表示连续零计数的负数

• 非零计数器值被编码为一个正数

一个空直方图（所有计数器都是零）无论计数器大小如何，都编码为正好48字节。一个典型的直方图（2位精度，从1微秒到1天范围）可以编码在小于典型MTU大小1500字节。

此格式与HdrHistogram Java和C实现兼容。

性能

由于这是一个直接移植（CPU的固定成本和内存使用减少），直方图值记录的成本特征与原始Java版本相同。Python版本的编码和解码非常快，接近原生性能，这得益于

• 集成C扩展（从Python调用的原生C代码）的开发，这些扩展被开发出来以在原生速度处理低级字节编码/解码/添加工作

• 原生压缩库（zlib和base64）

在macbook pro（2019 Intel Core i7 @ 2.6GHz）和Linux服务器（Intel(R) Xeon(R) Gold 5118 CPU @ 2.30GHz）上

典型直方图定义为具有30%的64位桶从数组的20%开始填充序列值，范围为1微秒到24小时，2位精度。这代表总共3968个桶，其中前793个是零，接下来的1190个桶有序列/唯一值，所有剩余的桶都是零，编码长度为3116字节。大多数真实世界的直方图具有更稀疏的图案，这将导致更低的编码和解码时间。解码和添加将解码编码的直方图并将其内容添加到现有直方图。

为了测量编码和解码的性能并获得性能分析，您必须使用git克隆github仓库，安装它（如果需要，在虚拟环境中安装）并使用pytest调用带有–runperf选项。两个性能分析函数将提供对典型直方图进行编码和解码1000次的性能分析信息（因此显示的时间值是1000次解码/解码所需的时间）。

Linux上的运行示例

# pytest -s -k test_cod_perf --runperf
=============================================================================== test session starts ================================================================================
platform linux -- Python 3.6.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1
rootdir: /root/HdrHistogram_py, configfile: tox.ini
collected 39 items / 38 deselected / 1 selected

test_hdrhistogram.py 0:00:00.061559
         35305 function calls in 0.068 seconds

   Ordered by: standard name

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
      1    0.000    0.000    0.068    0.068 <string>:1(<module>)
   2000    0.002    0.000    0.002    0.000 __init__.py:483(string_at)
   1000    0.000    0.000    0.004    0.000 base64.py:51(b64encode)
      1    0.000    0.000    0.000    0.000 codec.py:119(__init__)
      1    0.000    0.000    0.000    0.000 codec.py:154(_init_counts)
      1    0.000    0.000    0.000    0.000 codec.py:172(get_counts)
   1000    0.004    0.000    0.050    0.000 codec.py:214(compress)
      1    0.000    0.000    0.000    0.000 codec.py:256(__init__)
      1    0.000    0.000    0.000    0.000 codec.py:285(get_counts)
   1000    0.002    0.000    0.061    0.000 codec.py:291(encode)
      1    0.000    0.000    0.000    0.000 codec.py:65(get_encoding_cookie)
      1    0.000    0.000    0.000    0.000 codec.py:69(get_compression_cookie)
   2190    0.001    0.000    0.001    0.000 histogram.py:142(_clz)
   2190    0.002    0.000    0.003    0.000 histogram.py:153(_get_bucket_index)
   2190    0.001    0.000    0.001    0.000 histogram.py:159(_get_sub_bucket_index)
   1190    0.000    0.000    0.000    0.000 histogram.py:162(_counts_index)
   1190    0.001    0.000    0.003    0.000 histogram.py:172(_counts_index_for)
   1190    0.001    0.000    0.005    0.000 histogram.py:177(record_value)
   1190    0.000    0.000    0.000    0.000 histogram.py:232(get_value_from_sub_bucket)
   1190    0.001    0.000    0.001    0.000 histogram.py:235(get_value_from_index)
      1    0.000    0.000    0.000    0.000 histogram.py:34(get_bucket_count)
   1000    0.000    0.000    0.061    0.000 histogram.py:419(encode)
   1000    0.001    0.000    0.003    0.000 histogram.py:462(get_counts_array_index)
      1    0.000    0.000    0.000    0.000 histogram.py:65(__init__)
      1    0.001    0.001    0.006    0.006 test_hdrhistogram.py:408(fill_hist_counts)
      1    0.000    0.000    0.068    0.068 test_hdrhistogram.py:526(check_cod_perf)
   5000    0.000    0.000    0.000    0.000 {built-in method _ctypes.addressof}
   1000    0.004    0.000    0.004    0.000 {built-in method binascii.b2a_base64}
   2190    0.000    0.000    0.000    0.000 {built-in method builtins.bin}
      1    0.000    0.000    0.068    0.068 {built-in method builtins.exec}
   3190    0.000    0.000    0.000    0.000 {built-in method builtins.len}
   1190    0.000    0.000    0.000    0.000 {built-in method builtins.max}
   1190    0.000    0.000    0.000    0.000 {built-in method builtins.min}
      1    0.000    0.000    0.000    0.000 {built-in method builtins.print}
      1    0.000    0.000    0.000    0.000 {built-in method math.ceil}
      1    0.000    0.000    0.000    0.000 {built-in method math.floor}
      4    0.000    0.000    0.000    0.000 {built-in method math.log}
      2    0.000    0.000    0.000    0.000 {built-in method math.pow}
      2    0.000    0.000    0.000    0.000 {built-in method now}
   1000    0.006    0.000    0.006    0.000 {built-in method pyhdrh.encode}
   1000    0.039    0.000    0.039    0.000 {built-in method zlib.compress}
      1    0.000    0.000    0.000    0.000 {method 'disable' of '_lsprof.Profiler' objects}

解码示例

# pytest -s -k test_dec_perf --runperf
=============================================================================== test session starts ================================================================================
platform linux -- Python 3.6.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1
rootdir: /root/HdrHistogram_py, configfile: tox.ini
collected 39 items / 38 deselected / 1 selected

test_hdrhistogram.py 0:00:00.106705
         118327 function calls in 0.113 seconds

   Ordered by: standard name

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
      1    0.000    0.000    0.113    0.113 <string>:1(<module>)
      2    0.000    0.000    0.000    0.000 __init__.py:483(string_at)
   1000    0.001    0.000    0.001    0.000 base64.py:34(_bytes_from_decode_data)
      1    0.000    0.000    0.000    0.000 base64.py:51(b64encode)
   1000    0.001    0.000    0.010    0.000 base64.py:65(b64decode)
   1001    0.001    0.000    0.019    0.000 codec.py:119(__init__)
   1001    0.004    0.000    0.004    0.000 codec.py:154(_init_counts)
   1000    0.002    0.000    0.012    0.000 codec.py:157(init_counts)
   3001    0.000    0.000    0.000    0.000 codec.py:172(get_counts)
   1000    0.002    0.000    0.018    0.000 codec.py:175(_decompress)
      1    0.000    0.000    0.000    0.000 codec.py:214(compress)
   1001    0.002    0.000    0.002    0.000 codec.py:256(__init__)
   3001    0.001    0.000    0.001    0.000 codec.py:285(get_counts)
      1    0.000    0.000    0.000    0.000 codec.py:291(encode)
   1000    0.003    0.000    0.032    0.000 codec.py:313(decode)
   1000    0.001    0.000    0.011    0.000 codec.py:359(add)
   3000    0.001    0.000    0.001    0.000 codec.py:56(get_cookie_base)
   1000    0.000    0.000    0.001    0.000 codec.py:59(get_word_size_in_bytes_from_cookie)
      1    0.000    0.000    0.000    0.000 codec.py:65(get_encoding_cookie)
   1001    0.000    0.000    0.000    0.000 codec.py:69(get_compression_cookie)
      1    0.000    0.000    0.000    0.000 expression.py:81(lex)
   7191    0.003    0.000    0.005    0.000 histogram.py:142(_clz)
   7191    0.006    0.000    0.011    0.000 histogram.py:153(_get_bucket_index)
   7191    0.002    0.000    0.002    0.000 histogram.py:159(_get_sub_bucket_index)
   1190    0.000    0.000    0.000    0.000 histogram.py:162(_counts_index)
   1190    0.001    0.000    0.003    0.000 histogram.py:172(_counts_index_for)
   1190    0.001    0.000    0.005    0.000 histogram.py:177(record_value)
   10190   0.002    0.000    0.002    0.000 histogram.py:232(get_value_from_sub_bucket)
   4190    0.002    0.000    0.003    0.000 histogram.py:235(get_value_from_index)
   2000    0.002    0.000    0.005    0.000 histogram.py:244(get_lowest_equivalent_value)
   4000    0.004    0.000    0.013    0.000 histogram.py:252(get_highest_equivalent_value)
   1000    0.000    0.000    0.000    0.000 histogram.py:330(get_total_count)
   1001    0.007    0.000    0.007    0.000 histogram.py:34(get_bucket_count)
   2000    0.001    0.000    0.007    0.000 histogram.py:346(get_max_value)
   2000    0.001    0.000    0.007    0.000 histogram.py:351(get_min_value)
      1    0.000    0.000    0.000    0.000 histogram.py:419(encode)
   1000    0.001    0.000    0.006    0.000 histogram.py:445(set_internal_tacking_values)
      1    0.000    0.000    0.000    0.000 histogram.py:462(get_counts_array_index)
   1000    0.005    0.000    0.035    0.000 histogram.py:513(add)
   1000    0.001    0.000    0.106    0.000 histogram.py:544(decode_and_add)
   1000    0.002    0.000    0.071    0.000 histogram.py:563(decode)
   1001    0.008    0.000    0.037    0.000 histogram.py:65(__init__)
      1    0.001    0.001    0.006    0.006 test_hdrhistogram.py:408(fill_hist_counts)
      1    0.000    0.000    0.113    0.113 test_hdrhistogram.py:539(check_dec_perf)
   3005    0.000    0.000    0.000    0.000 {built-in method _ctypes.addressof}
   1000    0.008    0.000    0.008    0.000 {built-in method binascii.a2b_base64}
      1    0.000    0.000    0.000    0.000 {built-in method binascii.b2a_base64}
   7191    0.001    0.000    0.001    0.000 {built-in method builtins.bin}
      1    0.000    0.000    0.113    0.113 {built-in method builtins.exec}
   2000    0.000    0.000    0.000    0.000 {built-in method builtins.isinstance}
   9192    0.001    0.000    0.001    0.000 {built-in method builtins.len}
   3190    0.001    0.000    0.001    0.000 {built-in method builtins.max}
   3190    0.001    0.000    0.001    0.000 {built-in method builtins.min}
      1    0.000    0.000    0.000    0.000 {built-in method builtins.print}
   1001    0.000    0.000    0.000    0.000 {built-in method math.ceil}
   1001    0.000    0.000    0.000    0.000 {built-in method math.floor}
   4004    0.001    0.000    0.001    0.000 {built-in method math.log}
   2002    0.000    0.000    0.000    0.000 {built-in method math.pow}
      2    0.000    0.000    0.000    0.000 {built-in method now}
   1000    0.008    0.000    0.008    0.000 {built-in method pyhdrh.add_array}
   1000    0.007    0.000    0.007    0.000 {built-in method pyhdrh.decode}
      1    0.000    0.000    0.000    0.000 {built-in method pyhdrh.encode}
      1    0.000    0.000    0.000    0.000 {built-in method zlib.compress}
   1000    0.014    0.000    0.014    0.000 {built-in method zlib.decompress}
      1    0.000    0.000    0.000    0.000 {method 'disable' of '_lsprof.Profiler' objects}
   2000    0.001    0.000    0.001    0.000 {method 'from_buffer_copy' of '_ctypes.PyCStructType' objects}

局限性、注意事项和已知问题

原始HDR直方图库的最新功能和错误修复可能不适用于此Python端口。以下是一些未实现的重要功能和API示例

• 并发支持（AtomicHistogram，ConcurrentHistogram等）

• DoubleHistogram

• 直方图自动调整大小

• 记录函数

由于PyPy代码的限制，当与PyPy一起使用时，此实现存在字节序编码问题（请参阅https://github.com/HdrHistogram/HdrHistogram_py/issues/13）。

当前实现存在在Windows 32位系统上运行的问题（库在解码时崩溃）。

依赖关系

唯一依赖项（除使用pytest和tox进行单元测试外）是负责版本控制（以及其他事项）的小型pbr Python包。

发布新版本到PyPI

要创建新版本，应用新的版本标签，然后在GitHub上创建新的发布版本（这需要正确的权限）。GitHub CI将构建分发布并将其推送到PyPI。

许可

根据Apache License，版本2.0（“许可证”）许可；除非遵守许可证，否则您不得使用此文件。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可证的具体语言，请参阅许可证。

贡献

欢迎外部贡献、分支和GitHub拉取请求。有关任何讨论，请访问gitter HdrHistogram空间https://gitter.im/HdrHistogram/HdrHistogram

致谢

Python代码直接从原始HDR直方图Java和C库移植而来

• https://github.com/HdrHistogram/HdrHistogram.git

• https://github.com/HdrHistogram/HdrHistogram_c.git

链接

• 来源：https://github.com/HdrHistogram/HdrHistogram_py.git