Skip to content

hdrhistogram-c.md

Latest commit

 

History

History
69 lines (50 loc) · 1.84 KB

hdrhistogram-c.md

File metadata and controls

69 lines (50 loc) · 1.84 KB
Raw

Tutorial: HdrHistogram_c + portable HDR

Tail latency is the product metric. This repo ships two histogram layers:

Layer Type When to use
ll::HdrLatencyHistogram Portable log2 buckets, header-only Always-on, no deps, demos
ll::HdrHistogramC Wrapper over HdrHistogram_c Production fidelity (optional)

Enable HdrHistogram_c

CMake option STACK_WITH_HDRHISTOGRAM=ON (default) FetchContents HdrHistogram_c 0.11.10 and links hdr_histogram_static.

LL_HAS_HDRHISTOGRAM_C=1  → full API
LL_HAS_HDRHISTOGRAM_C=0  → wrapper methods no-op / invalid()

Disable if you need a deps-free configure:

cmake -S . -B build -DSTACK_WITH_HDRHISTOGRAM=OFF

Usage

#include "ll/hdr_c.hpp"
#include "ll/tsc_clock.hpp"

ll::HdrHistogramC h;  // range up to ~1h in ns by default
auto t0 = ll::steady_ns();
// … work …
h.record(static_cast<std::int64_t>(ll::steady_ns() - t0));

auto p99  = h.value_at_percentile(99.0);
auto p999 = h.value_at_percentile(99.9);
auto mx   = h.max();

Compare with portable:

ll::HdrLatencyHistogram<> portable;
portable.record(dt);
// portable is coarser (power-of-two buckets) but zero external deps

Run

./build/example_hdr_c
ctest --test-dir build -R 'roadmap.*hdr'

Production notes

  1. Prefer HdrHistogram_c (or Java/Go HDR ports) for long-running services.
  2. Record in nanoseconds or cycles, not mixed units.
  3. Export p50/p90/p99/p99.9/max every interval — never ship on mean alone.
  4. Keep recording allocation-free (both wrappers avoid heap after init).
  5. Pair with Google Benchmark (make bench) for micro-level queue costs.

Related

  • docs/blueprint/06-telemetry.md
  • include/ll/hdr_histogram.hpp · include/ll/hdr_c.hpp