kcenon::network::metrics::histogram Class Reference

Thread-safe histogram for capturing value distributions. More...

#include <histogram.h>

Collaboration diagram for kcenon::network::metrics::histogram:

Public Member Functions
	histogram (histogram_config cfg=histogram_config::default_latency_config())
	Construct histogram with configuration.
	~histogram ()=default
	Destructor.
	histogram (const histogram &)=delete
auto	operator= (const histogram &) -> histogram &=delete
	histogram (histogram &&other) noexcept
auto	operator= (histogram &&other) noexcept -> histogram &
void	record (double value)
	Record a value observation.
auto	count () const -> uint64_t
	Get total number of observations.
auto	sum () const -> double
	Get sum of all observations.
auto	min () const -> double
	Get minimum observed value.
auto	max () const -> double
	Get maximum observed value.
auto	mean () const -> double
	Get mean of all observations.
auto	percentile (double p) const -> double
	Calculate percentile value.
auto	p50 () const -> double
	Get 50th percentile (median)
auto	p95 () const -> double
	Get 95th percentile.
auto	p99 () const -> double
	Get 99th percentile.
auto	p999 () const -> double
	Get 99.9th percentile.
auto	buckets () const -> std::vector< std::pair< double, uint64_t > >
	Get all bucket counts.
auto	snapshot (const std::map< std::string, std::string > &labels={}) const -> histogram_snapshot
	Create immutable snapshot of current state.
void	reset ()
	Reset all statistics.

Private Member Functions
auto	find_bucket (double value) const -> size_t
	Find bucket index for a value.
void	update_min (double value)
	Update min value atomically.
void	update_max (double value)
	Update max value atomically.
void	add_to_sum (double value)
	Add to sum atomically.

Private Attributes
std::vector< double >	boundaries_
std::unique_ptr< std::atomic< uint64_t >[]>	bucket_counts_
size_t	bucket_count_ {0}
std::atomic< uint64_t >	count_ {0}
std::atomic< double >	sum_ {0.0}
std::atomic< double >	min_ {std::numeric_limits<double>::infinity()}
std::atomic< double >	max_ {-std::numeric_limits<double>::infinity()}
std::mutex	mutex_

Detailed Description

Thread-safe histogram for capturing value distributions.

This histogram implementation uses predefined bucket boundaries to track the distribution of values. It supports:

• Recording values with thread-safe atomic operations
• Calculating percentiles (p50, p95, p99, p999)
• Exporting to Prometheus and JSON formats

Example usage:

histogram h(histogram_config::default_latency_config());
h.record(5.5);
h.record(10.2);
h.record(3.1);
 
double p99 = h.p99();
auto snapshot = h.snapshot();
std::cout << snapshot.to_prometheus("latency_ms") << std::endl;

Examples

network_metrics_example.cpp.

Definition at line 105 of file histogram.h.

Constructor & Destructor Documentation

histogram() [1/3]

kcenon::network::metrics::histogram::histogram ( histogram_config cfg = histogram_config::default_latency_config() )

explicit

Construct histogram with configuration.

Parameters

cfg	Configuration with bucket boundaries

Definition at line 153 of file histogram.cpp.

{
    if (cfg.bucket_boundaries.empty())
    {
        cfg = histogram_config::default_latency_config();
    }
 
    boundaries_ = std::move(cfg.bucket_boundaries);
    std::sort(boundaries_.begin(), boundaries_.end());
 
    // Add +Inf bucket
    boundaries_.push_back(std::numeric_limits<double>::infinity());
 
    // Initialize bucket counts
    bucket_count_ = boundaries_.size();
    bucket_counts_ = std::make_unique<std::atomic<uint64_t>[]>(bucket_count_);
    for (size_t i = 0; i < bucket_count_; ++i)
    {
        bucket_counts_[i].store(0, std::memory_order_relaxed);
    }
}

References boundaries_, kcenon::network::metrics::histogram_config::bucket_boundaries, bucket_count_, bucket_counts_, and kcenon::network::metrics::histogram_config::default_latency_config().

Here is the call graph for this function:

~histogram()

kcenon::network::metrics::histogram::~histogram ( )

default

Destructor.

histogram() [2/3]

kcenon::network::metrics::histogram::histogram ( const histogram & )

delete

histogram() [3/3]

kcenon::network::metrics::histogram::histogram ( histogram && other )

noexcept

Definition at line 175 of file histogram.cpp.

    : boundaries_(std::move(other.boundaries_))
    , bucket_counts_(std::move(other.bucket_counts_))
    , bucket_count_(other.bucket_count_)
    , count_(other.count_.load(std::memory_order_relaxed))
    , sum_(other.sum_.load(std::memory_order_relaxed))
    , min_(other.min_.load(std::memory_order_relaxed))
    , max_(other.max_.load(std::memory_order_relaxed))
{
    other.bucket_count_ = 0;
}

Member Function Documentation

add_to_sum()

void kcenon::network::metrics::histogram::add_to_sum ( double value )

private

Add to sum atomically.

Parameters

value

Value to add

Definition at line 390 of file histogram.cpp.

{
    double current = sum_.load(std::memory_order_relaxed);
    while (!sum_.compare_exchange_weak(current, current + value, std::memory_order_relaxed,
                                       std::memory_order_relaxed))
    {
        // current is updated by compare_exchange_weak
    }
}

References sum_.

Referenced by record().

Here is the caller graph for this function:

buckets()

auto kcenon::network::metrics::histogram::buckets ( ) const -> std::vector<std::pair<double, uint64_t>>

nodiscard

Get all bucket counts.

Returns

Vector of (boundary, cumulative_count) pairs

Definition at line 305 of file histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
 
    std::vector<std::pair<double, uint64_t>> result;
    result.reserve(bucket_count_);
 
    uint64_t cumulative = 0;
    for (size_t i = 0; i < bucket_count_; ++i)
    {
        cumulative += bucket_counts_[i].load(std::memory_order_relaxed);
        result.emplace_back(boundaries_[i], cumulative);
    }
 
    return result;
}

References boundaries_, bucket_count_, bucket_counts_, and mutex_.

count()

auto kcenon::network::metrics::histogram::count ( ) const -> uint64_t

nodiscard

Get total number of observations.

Returns

Count of recorded values

Definition at line 214 of file histogram.cpp.

{
    return count_.load(std::memory_order_relaxed);
}

References count_.

Referenced by mean().

Here is the caller graph for this function:

find_bucket()

auto kcenon::network::metrics::histogram::find_bucket ( double value ) const -> size_t

nodiscardprivate

Find bucket index for a value.

Parameters

value

The value to classify

Returns

Index of the bucket containing this value

Definition at line 360 of file histogram.cpp.

{
    auto it = std::lower_bound(boundaries_.begin(), boundaries_.end(), value);
    if (it == boundaries_.end())
    {
        return boundaries_.size() - 1;
    }
    return static_cast<size_t>(std::distance(boundaries_.begin(), it));
}

Referenced by record().

Here is the caller graph for this function:

max()

auto kcenon::network::metrics::histogram::max ( ) const -> double

nodiscard

Get maximum observed value.

Returns

Maximum value, or -inf if no observations

Definition at line 229 of file histogram.cpp.

{
    return max_.load(std::memory_order_relaxed);
}

References max_.

mean()

auto kcenon::network::metrics::histogram::mean ( ) const -> double

nodiscard

Get mean of all observations.

Returns

Mean value, or 0 if no observations

Definition at line 234 of file histogram.cpp.

{
    uint64_t c = count();
    if (c == 0)
    {
        return 0.0;
    }
    return sum() / static_cast<double>(c);
}

References count(), and sum().

Here is the call graph for this function:

min()

auto kcenon::network::metrics::histogram::min ( ) const -> double

nodiscard

Get minimum observed value.

Returns

Minimum value, or +inf if no observations

Definition at line 224 of file histogram.cpp.

{
    return min_.load(std::memory_order_relaxed);
}

References min_.

operator=() [1/2]

auto kcenon::network::metrics::histogram::operator= ( const histogram & ) -> histogram &=delete

delete

operator=() [2/2]

auto kcenon::network::metrics::histogram::operator= ( histogram && other ) -> histogram&

noexcept

Definition at line 187 of file histogram.cpp.

{
    if (this != &other)
    {
        boundaries_ = std::move(other.boundaries_);
        bucket_counts_ = std::move(other.bucket_counts_);
        bucket_count_ = other.bucket_count_;
        count_.store(other.count_.load(std::memory_order_relaxed), std::memory_order_relaxed);
        sum_.store(other.sum_.load(std::memory_order_relaxed), std::memory_order_relaxed);
        min_.store(other.min_.load(std::memory_order_relaxed), std::memory_order_relaxed);
        max_.store(other.max_.load(std::memory_order_relaxed), std::memory_order_relaxed);
        other.bucket_count_ = 0;
    }
    return *this;
}

p50()

auto kcenon::network::metrics::histogram::p50 ( ) const -> double

inlinenodiscard

Get 50th percentile (median)

Returns

Estimated median value

Definition at line 179 of file histogram.h.

{ return percentile(0.50); }

p95()

auto kcenon::network::metrics::histogram::p95 ( ) const -> double

inlinenodiscard

Get 95th percentile.

Returns

Estimated p95 value

Definition at line 185 of file histogram.h.

{ return percentile(0.95); }

p99()

auto kcenon::network::metrics::histogram::p99 ( ) const -> double

inlinenodiscard

Get 99th percentile.

Returns

Estimated p99 value

Definition at line 191 of file histogram.h.

{ return percentile(0.99); }

p999()

auto kcenon::network::metrics::histogram::p999 ( ) const -> double

inlinenodiscard

Get 99.9th percentile.

Returns

Estimated p999 value

Definition at line 197 of file histogram.h.

{ return percentile(0.999); }

percentile()

auto kcenon::network::metrics::histogram::percentile ( double p ) const -> double

nodiscard

Calculate percentile value.

Parameters

p	Percentile (0.0 to 1.0)

Returns

Estimated value at the given percentile

Uses linear interpolation within buckets for estimation.

Definition at line 244 of file histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
 
    uint64_t total = count_.load(std::memory_order_relaxed);
    if (total == 0)
    {
        return 0.0;
    }
 
    // Clamp percentile to valid range
    p = std::clamp(p, 0.0, 1.0);
 
    // Target count for this percentile
    double target = p * static_cast<double>(total);
 
    // Calculate cumulative counts
    std::vector<uint64_t> cumulative;
    cumulative.reserve(bucket_count_);
    uint64_t running_sum = 0;
    for (size_t i = 0; i < bucket_count_; ++i)
    {
        running_sum += bucket_counts_[i].load(std::memory_order_relaxed);
        cumulative.push_back(running_sum);
    }
 
    // Find the bucket containing the target count
    size_t bucket_idx = 0;
    for (size_t i = 0; i < cumulative.size(); ++i)
    {
        if (static_cast<double>(cumulative[i]) >= target)
        {
            bucket_idx = i;
            break;
        }
    }
 
    // Linear interpolation within the bucket
    double lower_bound = (bucket_idx == 0) ? 0.0 : boundaries_[bucket_idx - 1];
    double upper_bound = boundaries_[bucket_idx];
 
    // Handle infinity bucket
    if (std::isinf(upper_bound))
    {
        return lower_bound;
    }
 
    uint64_t lower_count = (bucket_idx == 0) ? 0 : cumulative[bucket_idx - 1];
    uint64_t upper_count = cumulative[bucket_idx];
 
    if (upper_count == lower_count)
    {
        return lower_bound;
    }
 
    double fraction = (target - static_cast<double>(lower_count))
                      / (static_cast<double>(upper_count) - static_cast<double>(lower_count));
 
    return lower_bound + (fraction * (upper_bound - lower_bound));
}

record()

void kcenon::network::metrics::histogram::record

(

double

value

)

Record a value observation.

Parameters

value

The value to record

Thread-safe. Values are placed in the appropriate bucket based on configured boundaries.

Examples

network_metrics_example.cpp.

Definition at line 203 of file histogram.cpp.

{
    size_t bucket_idx = find_bucket(value);
    bucket_counts_[bucket_idx].fetch_add(1, std::memory_order_relaxed);
 
    count_.fetch_add(1, std::memory_order_relaxed);
    add_to_sum(value);
    update_min(value);
    update_max(value);
}

References add_to_sum(), bucket_counts_, count_, find_bucket(), update_max(), and update_min().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

reset()

void kcenon::network::metrics::histogram::reset

(

)

Reset all statistics.

Thread-safe. Clears all observations.

Definition at line 345 of file histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
 
    count_.store(0, std::memory_order_relaxed);
    sum_.store(0.0, std::memory_order_relaxed);
    min_.store(std::numeric_limits<double>::infinity(), std::memory_order_relaxed);
    max_.store(-std::numeric_limits<double>::infinity(), std::memory_order_relaxed);
 
    for (size_t i = 0; i < bucket_count_; ++i)
    {
        bucket_counts_[i].store(0, std::memory_order_relaxed);
    }
}

References bucket_count_, bucket_counts_, count_, max_, min_, mutex_, and sum_.

snapshot()

auto kcenon::network::metrics::histogram::snapshot ( const std::map< std::string, std::string > & labels = {} ) const -> histogram_snapshot

nodiscard

Create immutable snapshot of current state.

Parameters

labels

Additional labels to include in snapshot

Returns

Snapshot with all statistics and bucket counts

Definition at line 322 of file histogram.cpp.

{
    histogram_snapshot snap;
    snap.count = count();
    snap.sum = sum();
    snap.min_value = min();
    snap.max_value = max();
    snap.labels = labels;
 
    // Calculate percentiles
    snap.percentiles[0.5] = p50();
    snap.percentiles[0.9] = percentile(0.9);
    snap.percentiles[0.95] = p95();
    snap.percentiles[0.99] = p99();
    snap.percentiles[0.999] = p999();
 
    // Get buckets
    snap.buckets = buckets();
 
    return snap;
}

References kcenon::network::metrics::histogram_snapshot::buckets, kcenon::network::metrics::histogram_snapshot::count, kcenon::network::metrics::histogram_snapshot::labels, kcenon::network::metrics::histogram_snapshot::max_value, kcenon::network::metrics::histogram_snapshot::min_value, kcenon::network::metrics::histogram_snapshot::percentiles, and kcenon::network::metrics::histogram_snapshot::sum.

sum()

auto kcenon::network::metrics::histogram::sum ( ) const -> double

nodiscard

Get sum of all observations.

Returns

Sum of recorded values

Definition at line 219 of file histogram.cpp.

{
    return sum_.load(std::memory_order_relaxed);
}

References sum_.

Referenced by mean().

Here is the caller graph for this function:

update_max()

void kcenon::network::metrics::histogram::update_max ( double value )

private

Update max value atomically.

Parameters

value

New potential maximum

Definition at line 380 of file histogram.cpp.

{
    double current = max_.load(std::memory_order_relaxed);
    while (value > current && !max_.compare_exchange_weak(current, value, std::memory_order_relaxed,
                                                          std::memory_order_relaxed))
    {
        // current is updated by compare_exchange_weak
    }
}

References max_.

Referenced by record().

Here is the caller graph for this function:

update_min()

void kcenon::network::metrics::histogram::update_min ( double value )

private

Update min value atomically.

Parameters

value

New potential minimum

Definition at line 370 of file histogram.cpp.

{
    double current = min_.load(std::memory_order_relaxed);
    while (value < current && !min_.compare_exchange_weak(current, value, std::memory_order_relaxed,
                                                          std::memory_order_relaxed))
    {
        // current is updated by compare_exchange_weak
    }
}

References min_.

Referenced by record().

Here is the caller graph for this function:

Member Data Documentation

boundaries_

std::vector<double> kcenon::network::metrics::histogram::boundaries_

private

Definition at line 221 of file histogram.h.

Referenced by buckets(), and histogram().

bucket_count_

size_t kcenon::network::metrics::histogram::bucket_count_ {0}

private

Definition at line 223 of file histogram.h.

{0};

Referenced by buckets(), histogram(), and reset().

bucket_counts_

std::unique_ptr<std::atomic<uint64_t>[]> kcenon::network::metrics::histogram::bucket_counts_

private

Definition at line 222 of file histogram.h.

Referenced by buckets(), histogram(), record(), and reset().

count_

std::atomic<uint64_t> kcenon::network::metrics::histogram::count_ {0}

private

Definition at line 224 of file histogram.h.

{0};

Referenced by count(), record(), and reset().

max_

std::atomic<double> kcenon::network::metrics::histogram::max_ {-std::numeric_limits<double>::infinity()}

private

Definition at line 227 of file histogram.h.

{-std::numeric_limits<double>::infinity()};

Referenced by max(), reset(), and update_max().

min_

std::atomic<double> kcenon::network::metrics::histogram::min_ {std::numeric_limits<double>::infinity()}

private

Definition at line 226 of file histogram.h.

{std::numeric_limits<double>::infinity()};

Referenced by min(), reset(), and update_min().

mutex_

std::mutex kcenon::network::metrics::histogram::mutex_

mutableprivate

Definition at line 228 of file histogram.h.

Referenced by buckets(), and reset().

sum_

std::atomic<double> kcenon::network::metrics::histogram::sum_ {0.0}

private

Definition at line 225 of file histogram.h.

{0.0};

Referenced by add_to_sum(), reset(), and sum().

---

The documentation for this class was generated from the following files:

• include/kcenon/network/detail/metrics/histogram.h
• src/metrics/histogram.cpp