kcenon::network::metrics::sliding_histogram Class Reference

Time-windowed histogram for tracking recent latency distributions. More...

#include <sliding_histogram.h>

Collaboration diagram for kcenon::network::metrics::sliding_histogram:

Classes
struct	time_bucket

Public Member Functions
	sliding_histogram (sliding_histogram_config cfg=sliding_histogram_config::default_config())
	Construct sliding histogram with configuration.
	~sliding_histogram ()=default
	Destructor.
	sliding_histogram (const sliding_histogram &)=delete
auto	operator= (const sliding_histogram &) -> sliding_histogram &=delete
	sliding_histogram (sliding_histogram &&other) noexcept
auto	operator= (sliding_histogram &&other) noexcept -> sliding_histogram &
void	record (double value)
	Record a value observation.
auto	count () const -> uint64_t
	Get total number of observations in current window.
auto	sum () const -> double
	Get sum of all observations in current window.
auto	mean () const -> double
	Get mean of all observations in current window.
auto	percentile (double p) const -> double
	Calculate percentile value for current window.
auto	p50 () const -> double
	Get 50th percentile (median) for current window.
auto	p95 () const -> double
	Get 95th percentile for current window.
auto	p99 () const -> double
	Get 99th percentile for current window.
auto	p999 () const -> double
	Get 99.9th percentile for current window.
auto	snapshot (const std::map< std::string, std::string > &labels={}) const -> histogram_snapshot
	Create snapshot aggregating all time buckets in current window.
auto	window_duration () const -> std::chrono::seconds
	Get the window duration.
void	reset ()
	Reset all data.

Private Member Functions
void	expire_old_buckets ()
	Expire old buckets outside the window.
auto	get_current_bucket () -> time_bucket &
	Get or create current time bucket.
auto	aggregate () const -> histogram_snapshot
	Create aggregated histogram from all buckets.

Private Attributes
sliding_histogram_config	config_
std::chrono::milliseconds	bucket_duration_
std::deque< std::unique_ptr< time_bucket > >	buckets_
std::mutex	mutex_

Detailed Description

Time-windowed histogram for tracking recent latency distributions.

This class maintains a sliding window of histogram data, automatically expiring old measurements. Useful for monitoring recent performance without accumulating historical data indefinitely.

Example usage:

sliding_histogram sh(sliding_histogram_config::default_config());
sh.record(5.5);
sh.record(10.2);
 
// Get percentiles for the last 60 seconds
double p99 = sh.p99();

Definition at line 66 of file sliding_histogram.h.

Constructor & Destructor Documentation

sliding_histogram() [1/3]

kcenon::network::metrics::sliding_histogram::sliding_histogram ( sliding_histogram_config cfg = sliding_histogram_config::default_config() )

explicit

Construct sliding histogram with configuration.

Parameters

cfg	Configuration for the sliding window

Definition at line 13 of file sliding_histogram.cpp.

    : config_(std::move(cfg))
    , bucket_duration_(std::chrono::duration_cast<std::chrono::milliseconds>(config_.window_duration)
                       / config_.bucket_count)
{
    // Ensure at least 1 bucket
    if (config_.bucket_count == 0)
    {
        config_.bucket_count = 1;
        bucket_duration_ = std::chrono::duration_cast<std::chrono::milliseconds>(config_.window_duration);
    }
}

References kcenon::network::metrics::sliding_histogram_config::bucket_count, and config_.

~sliding_histogram()

kcenon::network::metrics::sliding_histogram::~sliding_histogram ( )

default

Destructor.

sliding_histogram() [2/3]

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

delete

sliding_histogram() [3/3]

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

noexcept

Definition at line 26 of file sliding_histogram.cpp.

    : config_(std::move(other.config_))
    , bucket_duration_(other.bucket_duration_)
    , buckets_(std::move(other.buckets_))
{
}

Member Function Documentation

aggregate()

auto kcenon::network::metrics::sliding_histogram::aggregate ( ) const -> histogram_snapshot

nodiscardprivate

Create aggregated histogram from all buckets.

Returns

Aggregated histogram snapshot

Definition at line 186 of file sliding_histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
    const_cast<sliding_histogram*>(this)->expire_old_buckets();
 
    histogram_snapshot result;
    result.count = 0;
    result.sum = 0.0;
    result.min_value = std::numeric_limits<double>::infinity();
    result.max_value = -std::numeric_limits<double>::infinity();
 
    if (buckets_.empty())
    {
        return result;
    }
 
    // Aggregate statistics
    std::vector<std::pair<double, uint64_t>> merged_buckets;
    bool first_snapshot = true;
 
    for (const auto& bucket : buckets_)
    {
        auto snap = bucket->hist.snapshot();
        result.count += snap.count;
        result.sum += snap.sum;
 
        if (snap.min_value < result.min_value)
        {
            result.min_value = snap.min_value;
        }
        if (snap.max_value > result.max_value)
        {
            result.max_value = snap.max_value;
        }
 
        // Merge bucket counts
        if (first_snapshot)
        {
            merged_buckets = snap.buckets;
            first_snapshot = false;
        }
        else
        {
            // Need to convert from cumulative to individual counts, add, then back to cumulative
            std::vector<uint64_t> individual_counts(snap.buckets.size(), 0);
            for (size_t i = 0; i < snap.buckets.size(); ++i)
            {
                uint64_t prev = (i == 0) ? 0 : snap.buckets[i - 1].second;
                individual_counts[i] = snap.buckets[i].second - prev;
            }
 
            std::vector<uint64_t> merged_individual(merged_buckets.size(), 0);
            for (size_t i = 0; i < merged_buckets.size(); ++i)
            {
                uint64_t prev = (i == 0) ? 0 : merged_buckets[i - 1].second;
                merged_individual[i] = merged_buckets[i].second - prev;
            }
 
            // Add individual counts
            for (size_t i = 0; i < merged_buckets.size() && i < individual_counts.size(); ++i)
            {
                merged_individual[i] += individual_counts[i];
            }
 
            // Convert back to cumulative
            uint64_t cumulative = 0;
            for (size_t i = 0; i < merged_buckets.size(); ++i)
            {
                cumulative += merged_individual[i];
                merged_buckets[i].second = cumulative;
            }
        }
    }
 
    result.buckets = std::move(merged_buckets);
 
    // Calculate percentiles from merged buckets
    if (result.count > 0 && !result.buckets.empty())
    {
        auto calc_percentile = [&](double p) -> double
        {
            double target = p * static_cast<double>(result.count);
 
            for (size_t i = 0; i < result.buckets.size(); ++i)
            {
                if (static_cast<double>(result.buckets[i].second) >= target)
                {
                    double lower_bound = (i == 0) ? 0.0 : result.buckets[i - 1].first;
                    double upper_bound = result.buckets[i].first;
 
                    if (std::isinf(upper_bound))
                    {
                        return lower_bound;
                    }
 
                    uint64_t lower_count = (i == 0) ? 0 : result.buckets[i - 1].second;
                    uint64_t upper_count = result.buckets[i].second;
 
                    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));
                }
            }
            return 0.0;
        };
 
        result.percentiles[0.5] = calc_percentile(0.5);
        result.percentiles[0.9] = calc_percentile(0.9);
        result.percentiles[0.95] = calc_percentile(0.95);
        result.percentiles[0.99] = calc_percentile(0.99);
        result.percentiles[0.999] = calc_percentile(0.999);
    }
 
    return result;
}

References kcenon::network::metrics::histogram_snapshot::buckets, buckets_, kcenon::network::metrics::histogram_snapshot::count, expire_old_buckets(), kcenon::network::metrics::histogram_snapshot::max_value, kcenon::network::metrics::histogram_snapshot::min_value, mutex_, kcenon::network::metrics::histogram_snapshot::percentiles, and kcenon::network::metrics::histogram_snapshot::sum.

Here is the call graph for this function:

count()

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

nodiscard

Get total number of observations in current window.

Returns

Count of recorded values

Definition at line 53 of file sliding_histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
    const_cast<sliding_histogram*>(this)->expire_old_buckets();
 
    uint64_t total = 0;
    for (const auto& bucket : buckets_)
    {
        total += bucket->hist.count();
    }
    return total;
}

References buckets_, expire_old_buckets(), and mutex_.

Referenced by mean().

Here is the call graph for this function:

Here is the caller graph for this function:

expire_old_buckets()

void kcenon::network::metrics::sliding_histogram::expire_old_buckets ( )

private

Expire old buckets outside the window.

Definition at line 154 of file sliding_histogram.cpp.

{
    auto now = std::chrono::steady_clock::now();
    auto cutoff = now - config_.window_duration;
 
    while (!buckets_.empty() && buckets_.front()->start_time < cutoff)
    {
        buckets_.pop_front();
    }
}

References buckets_, config_, and kcenon::network::metrics::sliding_histogram_config::window_duration.

Referenced by aggregate(), count(), record(), and sum().

Here is the caller graph for this function:

get_current_bucket()

auto kcenon::network::metrics::sliding_histogram::get_current_bucket ( ) -> time_bucket&

private

Get or create current time bucket.

Returns

Reference to the current bucket

Definition at line 165 of file sliding_histogram.cpp.

{
    auto now = std::chrono::steady_clock::now();
 
    if (buckets_.empty())
    {
        buckets_.push_back(std::make_unique<time_bucket>(config_.hist_config));
        return *buckets_.back();
    }
 
    auto& last = buckets_.back();
    auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(now - last->start_time);
 
    if (elapsed >= bucket_duration_)
    {
        buckets_.push_back(std::make_unique<time_bucket>(config_.hist_config));
    }
 
    return *buckets_.back();
}

Referenced by record().

Here is the caller graph for this function:

mean()

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

nodiscard

Get mean of all observations in current window.

Returns

Mean value, or 0 if no observations

Definition at line 79 of file sliding_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:

operator=() [1/2]

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

delete

operator=() [2/2]

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

noexcept

Definition at line 33 of file sliding_histogram.cpp.

{
    if (this != &other)
    {
        std::lock_guard<std::mutex> lock(mutex_);
        config_ = std::move(other.config_);
        bucket_duration_ = other.bucket_duration_;
        buckets_ = std::move(other.buckets_);
    }
    return *this;
}

p50()

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

inlinenodiscard

Get 50th percentile (median) for current window.

Returns

Estimated median value

Definition at line 126 of file sliding_histogram.h.

{ return percentile(0.50); }

References percentile().

Here is the call graph for this function:

p95()

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

inlinenodiscard

Get 95th percentile for current window.

Returns

Estimated p95 value

Definition at line 132 of file sliding_histogram.h.

{ return percentile(0.95); }

References percentile().

Here is the call graph for this function:

p99()

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

inlinenodiscard

Get 99th percentile for current window.

Returns

Estimated p99 value

Definition at line 138 of file sliding_histogram.h.

{ return percentile(0.99); }

References percentile().

Here is the call graph for this function:

p999()

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

inlinenodiscard

Get 99.9th percentile for current window.

Returns

Estimated p999 value

Definition at line 144 of file sliding_histogram.h.

{ return percentile(0.999); }

References percentile().

Here is the call graph for this function:

percentile()

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

nodiscard

Calculate percentile value for current window.

Parameters

p	Percentile (0.0 to 1.0)

Returns

Estimated value at the given percentile

Definition at line 89 of file sliding_histogram.cpp.

{
    auto snap = aggregate();
    if (snap.count == 0)
    {
        return 0.0;
    }
 
    // Clamp percentile
    p = std::clamp(p, 0.0, 1.0);
 
    // Use pre-calculated percentiles if available
    auto it = snap.percentiles.find(p);
    if (it != snap.percentiles.end())
    {
        return it->second;
    }
 
    // Calculate from buckets
    double target = p * static_cast<double>(snap.count);
 
    for (size_t i = 0; i < snap.buckets.size(); ++i)
    {
        if (static_cast<double>(snap.buckets[i].second) >= target)
        {
            double lower_bound = (i == 0) ? 0.0 : snap.buckets[i - 1].first;
            double upper_bound = snap.buckets[i].first;
 
            if (std::isinf(upper_bound))
            {
                return lower_bound;
            }
 
            uint64_t lower_count = (i == 0) ? 0 : snap.buckets[i - 1].second;
            uint64_t upper_count = snap.buckets[i].second;
 
            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));
        }
    }
 
    return 0.0;
}

Referenced by p50(), p95(), p99(), and p999().

Here is the caller graph for this function:

record()

void kcenon::network::metrics::sliding_histogram::record

(

double

value

)

Record a value observation.

Parameters

value

The value to record

Thread-safe. Automatically creates new time buckets as needed and expires old ones.

Definition at line 45 of file sliding_histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
    expire_old_buckets();
    auto& bucket = get_current_bucket();
    bucket.hist.record(value);
}

References expire_old_buckets(), get_current_bucket(), and mutex_.

Here is the call graph for this function:

reset()

void kcenon::network::metrics::sliding_histogram::reset

(

)

Reset all data.

Thread-safe. Clears all time buckets.

Definition at line 148 of file sliding_histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
    buckets_.clear();
}

References buckets_, and mutex_.

snapshot()

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

nodiscard

Create snapshot aggregating all time buckets in current window.

Parameters

labels

Additional labels to include in snapshot

Returns

Aggregated snapshot with statistics

Definition at line 140 of file sliding_histogram.cpp.

{
    auto snap = aggregate();
    snap.labels = labels;
    return snap;
}

sum()

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

nodiscard

Get sum of all observations in current window.

Returns

Sum of recorded values

Definition at line 66 of file sliding_histogram.cpp.

{
    std::lock_guard<std::mutex> lock(mutex_);
    const_cast<sliding_histogram*>(this)->expire_old_buckets();
 
    double total = 0.0;
    for (const auto& bucket : buckets_)
    {
        total += bucket->hist.sum();
    }
    return total;
}

References buckets_, expire_old_buckets(), and mutex_.

Referenced by mean().

Here is the call graph for this function:

Here is the caller graph for this function:

window_duration()

auto kcenon::network::metrics::sliding_histogram::window_duration ( ) const -> std::chrono::seconds

inlinenodiscard

Get the window duration.

Returns

Configured window duration

Definition at line 158 of file sliding_histogram.h.

    {
        return config_.window_duration;
    }

References config_, and kcenon::network::metrics::sliding_histogram_config::window_duration.

Member Data Documentation

bucket_duration_

std::chrono::milliseconds kcenon::network::metrics::sliding_histogram::bucket_duration_

private

Definition at line 183 of file sliding_histogram.h.

buckets_

std::deque<std::unique_ptr<time_bucket> > kcenon::network::metrics::sliding_histogram::buckets_

private

Definition at line 184 of file sliding_histogram.h.

Referenced by aggregate(), count(), expire_old_buckets(), reset(), and sum().

config_

sliding_histogram_config kcenon::network::metrics::sliding_histogram::config_

private

Definition at line 182 of file sliding_histogram.h.

Referenced by expire_old_buckets(), sliding_histogram(), and window_duration().

mutex_

std::mutex kcenon::network::metrics::sliding_histogram::mutex_

mutableprivate

Definition at line 185 of file sliding_histogram.h.

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

---

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

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