histogram.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <atomic>
#include <cstdint>
#include <limits>
#include <map>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
 
namespace kcenon::network::metrics {
 
struct histogram_config
{
    std::vector<double> bucket_boundaries;
 
    static auto default_latency_config() -> histogram_config
    {
        return histogram_config{
            {0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0, 2500.0, 5000.0,
             10000.0}};
    }
};
 
struct histogram_snapshot
{
    uint64_t count;                                        
    double sum;                                            
    double min_value;                                      
    double max_value;                                      
    std::map<double, double> percentiles;                  
    std::vector<std::pair<double, uint64_t>> buckets;      
    std::map<std::string, std::string> labels;             
 
    [[nodiscard]] auto to_prometheus(const std::string& name) const -> std::string;
 
    [[nodiscard]] auto to_json() const -> std::string;
};
 
class histogram
{
public:
    explicit histogram(histogram_config cfg = histogram_config::default_latency_config());
 
    ~histogram() = default;
 
    // Non-copyable (contains atomics)
    histogram(const histogram&) = delete;
    auto operator=(const histogram&) -> histogram& = delete;
 
    // Movable
    histogram(histogram&& other) noexcept;
    auto operator=(histogram&& other) noexcept -> histogram&;
 
    void record(double value);
 
    [[nodiscard]] auto count() const -> uint64_t;
 
    [[nodiscard]] auto sum() const -> double;
 
    [[nodiscard]] auto min() const -> double;
 
    [[nodiscard]] auto max() const -> double;
 
    [[nodiscard]] auto mean() const -> double;
 
    [[nodiscard]] auto percentile(double p) const -> double;
 
    [[nodiscard]] auto p50() const -> double { return percentile(0.50); }
 
    [[nodiscard]] auto p95() const -> double { return percentile(0.95); }
 
    [[nodiscard]] auto p99() const -> double { return percentile(0.99); }
 
    [[nodiscard]] auto p999() const -> double { return percentile(0.999); }
 
    [[nodiscard]] auto buckets() const -> std::vector<std::pair<double, uint64_t>>;
 
    [[nodiscard]] auto snapshot(const std::map<std::string, std::string>& labels = {}) const
        -> histogram_snapshot;
 
    void reset();
 
private:
    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()};
    mutable std::mutex mutex_;
 
    [[nodiscard]] auto find_bucket(double value) const -> size_t;
 
    void update_min(double value);
 
    void update_max(double value);
 
    void add_to_sum(double value);
};
 
} // namespace kcenon::network::metrics