registry.hpp

Go to the documentation of this file.

#pragma once
 
 
#include <prom/adapter.hpp>
#include <prom/counter.hpp>
#include <prom/error.hpp>
#include <prom/gauge.hpp>
#include <prom/global.hpp>
#include <prom/histogram.hpp>
#include <prom/info.hpp>
#include <prom/labels.hpp>
#include <prom/metric_base.hpp>
#include <prom/stateset.hpp>
#include <prom/summary.hpp>
#include <prom/unit.hpp>
#include <prom/untyped.hpp>
 
#include <cmath>
#include <cstddef>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace prom {
 
class Scope;
struct ScopeConfig;
 
struct RegistryConfig {
    std::string prefix{};
    Labels const_labels{};
    comms::DisplayInfo display{};
};
 
struct MetricInfo {
    MetricType type{};
    std::string name;
    std::string help;
    Labels const_labels;
    Unit unit;
    bool scoped = false;
};
 
[[nodiscard]] inline MetricInfo describe(const MetricCore& core) {
    MetricInfo info;
    info.type = core.type;
    if (core.scope) {
        info.name = core.scope->full_name(core.base_name);
        info.const_labels = core.scope->effective_labels(core.base_labels);
    } else {
        info.name = core.name;
        info.const_labels = core.const_labels;
    }
    info.help = core.help;
    info.unit = core.unit_view();
    // "scoped" means the metric is actually decorated: an empty decoration (a
    // plain registry, or an unconfigured global) leaves it reported as plain.
    info.scoped = core.scope && core.scope->decorates();
    return info;
}
 
class Registry {
public:
    Registry(const Registry&) = delete;
    Registry& operator=(const Registry&) = delete;
    Registry(Registry&&) = delete;
    Registry& operator=(Registry&&) = delete;
    ~Registry() = default;
 
    [[nodiscard]] static std::shared_ptr<Registry> create(AdapterPtr adapter = nullptr) {
        return std::shared_ptr<Registry>(
            new Registry(std::make_shared<AdapterCell>(std::move(adapter))));
    }
 
    [[nodiscard]] static std::shared_ptr<Registry> create(AdapterPtr adapter,
                                                          RegistryConfig config) {
        return std::shared_ptr<Registry>(
            new Registry(std::make_shared<AdapterCell>(std::move(adapter)),
                         std::make_shared<detail::DecorationState>(std::move(config.prefix),
                                                                   std::move(config.const_labels),
                                                                   std::move(config.display))));
    }
 
    [[nodiscard]] static std::shared_ptr<Registry> global() {
        static std::shared_ptr<Registry> instance(
            new Registry(detail::global_adapter_cell(), detail::global_decoration()));
        return instance;
    }
 
    [[nodiscard]] AdapterPtr adapter() const {
        return cell_->adapter();
    }
 
    void set_adapter(AdapterPtr adapter) const {
        cell_->set_adapter(std::move(adapter));
    }
 
    // --- live decoration (prefix / default labels / display) ----------------
    //
    // Every registry carries a decoration (empty by default), so these setters
    // reconfigure *all* metrics it has created — existing and future — which
    // re-register on their next use. On `Registry::global()` the decoration is
    // the process-wide one, so a prefix / label set here also reaches standalone
    // and scoped metrics.
 
    [[nodiscard]] std::string prefix() const {
        return decoration_->prefix();
    }
    void set_prefix(std::string prefix) {
        decoration_->set_prefix(std::move(prefix));
    }
 
    [[nodiscard]] Labels const_labels() const {
        return decoration_->const_labels();
    }
    void set_const_labels(Labels labels) {
        decoration_->set_const_labels(std::move(labels));
    }
    void add_const_label(std::string name, std::string value) {
        decoration_->add_const_label(std::move(name), std::move(value));
    }
 
    [[nodiscard]] comms::DisplayInfo display() const {
        return decoration_->display();
    }
    void set_display(comms::DisplayInfo display) {
        decoration_->set_display(std::move(display));
    }
 
    [[nodiscard]] RegistryConfig config() const {
        return RegistryConfig{
            decoration_->prefix(), decoration_->const_labels(), decoration_->display()};
    }
    void configure(RegistryConfig config) {
        decoration_->configure(
            std::move(config.prefix), std::move(config.const_labels), std::move(config.display));
    }
 
    [[nodiscard]] std::vector<MetricInfo> metrics() const {
        // Collect live cores under the lock, then describe() after releasing it
        // (keeps the lock hold short and avoids any reentrancy on describe()).
        std::vector<std::shared_ptr<MetricCore>> live;
        {
            const std::scoped_lock lock(mutex_);
            for (auto it = metrics_.begin(); it != metrics_.end();) {
                if (auto core = it->lock()) {
                    live.push_back(std::move(core));
                    ++it;
                } else {
                    it = metrics_.erase(it);
                }
            }
        }
        std::vector<MetricInfo> out;
        out.reserve(live.size());
        for (const auto& core : live) {
            out.push_back(describe(*core));
        }
        return out;
    }
 
    [[nodiscard]] static std::shared_ptr<Scope> scope(std::string_view name);
    [[nodiscard]] static std::shared_ptr<Scope> scope(std::string_view name, ScopeConfig config);
 
    // --- throwing factories -------------------------------------------------
 
    [[nodiscard]] Counter counter(const CounterSpec& spec) {
        return unwrap(try_counter(spec));
    }
    [[nodiscard]] Gauge gauge(const GaugeSpec& spec) {
        return unwrap(try_gauge(spec));
    }
    [[nodiscard]] Histogram histogram(const HistogramSpec& spec) {
        return unwrap(try_histogram(spec));
    }
    [[nodiscard]] Summary summary(const SummarySpec& spec) {
        return unwrap(try_summary(spec));
    }
    [[nodiscard]] Untyped untyped(const UntypedSpec& spec) {
        return unwrap(try_untyped(spec));
    }
    [[nodiscard]] Info info(const InfoSpec& spec) {
        return unwrap(try_info(spec));
    }
    [[nodiscard]] StateSet stateset(const StateSetSpec& spec) {
        return unwrap(try_stateset(spec));
    }
 
    // --- noexcept fallible mirrors -----------------------------------------
 
    [[nodiscard]] expected<Counter> try_counter(const CounterSpec& spec) noexcept {
        return build<Counter>(MetricType::Counter,
                              spec.name,
                              spec.help,
                              spec.labels,
                              spec.unit,
                              spec.display,
                              {},
                              {},
                              {});
    }
 
    [[nodiscard]] expected<Gauge> try_gauge(const GaugeSpec& spec) noexcept {
        return build<Gauge>(MetricType::Gauge,
                            spec.name,
                            spec.help,
                            spec.labels,
                            spec.unit,
                            spec.display,
                            {},
                            {},
                            {});
    }
 
    [[nodiscard]] expected<Histogram> try_histogram(const HistogramSpec& spec) noexcept {
        std::vector<double> buckets = spec.buckets;
        if (buckets.empty()) {
            buckets.assign(default_histogram_buckets.begin(), default_histogram_buckets.end());
        }
        if (const auto err = validate_buckets(buckets)) {
            return std::unexpected(*err);
        }
        return build<Histogram>(MetricType::Histogram,
                                spec.name,
                                spec.help,
                                spec.labels,
                                spec.unit,
                                spec.display,
                                std::move(buckets),
                                {},
                                {});
    }
 
    [[nodiscard]] expected<Summary> try_summary(const SummarySpec& spec) noexcept {
        std::vector<double> quantiles = spec.quantiles;
        if (quantiles.empty()) {
            quantiles.assign(default_summary_quantiles.begin(), default_summary_quantiles.end());
        }
        if (const auto err = validate_quantiles(quantiles)) {
            return std::unexpected(*err);
        }
        return build<Summary>(MetricType::Summary,
                              spec.name,
                              spec.help,
                              spec.labels,
                              spec.unit,
                              spec.display,
                              {},
                              std::move(quantiles),
                              {});
    }
 
    [[nodiscard]] expected<Untyped> try_untyped(const UntypedSpec& spec) noexcept {
        return build<Untyped>(MetricType::Untyped,
                              spec.name,
                              spec.help,
                              spec.labels,
                              spec.unit,
                              spec.display,
                              {},
                              {},
                              {});
    }
 
    [[nodiscard]] expected<Info> try_info(const InfoSpec& spec) noexcept {
        return build<Info>(
            MetricType::Info, spec.name, spec.help, spec.labels, Unit{}, spec.display, {}, {}, {});
    }
 
    [[nodiscard]] expected<StateSet> try_stateset(const StateSetSpec& spec) noexcept {
        if (spec.states.empty()) {
            return std::unexpected(Error{ErrorCode::EmptyStateSet, std::string(spec.name)});
        }
        return build<StateSet>(MetricType::StateSet,
                               spec.name,
                               spec.help,
                               spec.labels,
                               Unit{},
                               spec.display,
                               {},
                               {},
                               spec.states);
    }
 
private:
    template <class Metric>
    [[nodiscard]] expected<Metric> build(const MetricType type,
                                         const std::string_view name,
                                         const std::string_view help,
                                         const Labels& labels,
                                         const Unit& unit,
                                         const comms::DisplayInfo& display,
                                         std::vector<double> buckets,
                                         std::vector<double> quantiles,
                                         std::vector<std::string> states) noexcept {
        if (!is_valid_metric_name(name)) {
            return std::unexpected(Error{ErrorCode::InvalidMetricName, std::string(name)});
        }
        for (const auto& [label_name, value] : labels.view()) {
            if (!is_valid_label_name(label_name)) {
                return std::unexpected(Error{ErrorCode::InvalidLabelName, label_name});
            }
        }
 
        auto core = std::make_shared<MetricCore>();
        core->type = type;
        core->help = std::string(help);
        core->buckets = std::move(buckets);
        core->quantiles = std::move(quantiles);
        core->states = std::move(states);
        core->source = cell_;
        if (!unit.empty()) {
            core->has_unit = true;
            core->unit_from_dimval = unit.from_dimval;
            core->unit_name = std::string(unit.name);
            core->unit_kind = std::string(unit.kind);
            core->unit_symbol = std::string(unit.symbol);
        }
 
        // Resolve the effective name / labels / display from the registry's live
        // decoration, keeping the base values so the metric can re-resolve when
        // the decoration changes (same machinery as a Scope). The decoration is
        // empty by default, in which case the effective values equal the spec's.
        core->scope = decoration_;
        core->base_name = std::string(name);
        core->base_labels = labels;
        core->base_display = display;
        const std::uint64_t decoration_version = decoration_->version();
        core->name = decoration_->full_name(name);
        core->const_labels = decoration_->effective_labels(labels);
        core->display = decoration_->effective_display(display);
 
        // Register eagerly against the current adapter so the family exists at
        // creation and `metrics()` can list it before first use. A later
        // adapter swap bumps the cell version, and a decoration change bumps the
        // scope version; either triggers re-registration on next use.
        const std::uint64_t adapter_version = cell_->version();
        const AdapterPtr adapter = cell_->adapter();
        const MetricHandle handle = adapter->register_metric(core->build_meta());
        core->bound.store(std::make_shared<const MetricCore::Bound>(
            MetricCore::Bound{.adapter = adapter,
                              .handle = handle,
                              .adapter_version = adapter_version,
                              .scope_version = decoration_version}));
        track(core);
        return Metric{std::move(core)};
    }
 
    void track(const std::shared_ptr<MetricCore>& core) const noexcept {
        const std::scoped_lock lock(mutex_);
        metrics_.push_back(core);
    }
 
    template <class Metric>
    [[nodiscard]] static Metric unwrap(expected<Metric> result) {
        if (!result) {
            throw Exception(std::move(result.error()));
        }
        return std::move(*result);
    }
 
    [[nodiscard]] static std::optional<Error>
    validate_buckets(const std::vector<double>& buckets) noexcept {
        if (buckets.empty()) {
            return Error{ErrorCode::InvalidBuckets, "no buckets"};
        }
        for (std::size_t i = 0; i < buckets.size(); ++i) {
            if (!std::isfinite(buckets[i])) {
                return Error{ErrorCode::InvalidBuckets, "non-finite bound"};
            }
            if (i > 0 && buckets[i] <= buckets[i - 1]) {
                return Error{ErrorCode::InvalidBuckets, "bounds not strictly increasing"};
            }
        }
        return std::nullopt;
    }
 
    [[nodiscard]] static std::optional<Error>
    validate_quantiles(const std::vector<double>& quantiles) noexcept {
        for (const double q : quantiles) {
            if (!std::isfinite(q) || q <= 0.0 || q >= 1.0) {
                return Error{ErrorCode::InvalidQuantiles, "quantile outside (0, 1)"};
            }
        }
        return std::nullopt;
    }
 
    explicit Registry(std::shared_ptr<AdapterCell> cell) noexcept
        : Registry(std::move(cell), std::make_shared<detail::DecorationState>()) {}
 
    Registry(std::shared_ptr<AdapterCell> cell,
             std::shared_ptr<detail::DecorationState> decoration) noexcept
        : cell_(std::move(cell)), decoration_(std::move(decoration)) {}
 
    std::shared_ptr<AdapterCell> cell_;
    mutable std::mutex mutex_;
    mutable std::vector<std::weak_ptr<MetricCore>> metrics_;
    // The live prefix / labels / display applied to every metric this registry
    // creates. Set once at construction (never null), so reads need no lock.
    std::shared_ptr<detail::DecorationState> decoration_;
};
 
// --- free helpers bound to Registry::global() -------------------------------
//
// These let a library create metrics without holding or passing a Registry:
//   auto c = prom::counter({.name = "requests_total", .help = "..."});
// Each delegates to the process-wide Registry::global(), which registers
// against whatever adapter is installed on the global cell at the time of the
// call (a NullAdapter until a backend is installed).
 
[[nodiscard]] inline Counter counter(const CounterSpec& spec) {
    return Registry::global()->counter(spec);
}
[[nodiscard]] inline Gauge gauge(const GaugeSpec& spec) {
    return Registry::global()->gauge(spec);
}
[[nodiscard]] inline Histogram histogram(const HistogramSpec& spec) {
    return Registry::global()->histogram(spec);
}
[[nodiscard]] inline Summary summary(const SummarySpec& spec) {
    return Registry::global()->summary(spec);
}
[[nodiscard]] inline Untyped untyped(const UntypedSpec& spec) {
    return Registry::global()->untyped(spec);
}
[[nodiscard]] inline Info info(const InfoSpec& spec) {
    return Registry::global()->info(spec);
}
[[nodiscard]] inline StateSet stateset(const StateSetSpec& spec) {
    return Registry::global()->stateset(spec);
}
 
[[nodiscard]] inline expected<Counter> try_counter(const CounterSpec& spec) noexcept {
    return Registry::global()->try_counter(spec);
}
[[nodiscard]] inline expected<Gauge> try_gauge(const GaugeSpec& spec) noexcept {
    return Registry::global()->try_gauge(spec);
}
[[nodiscard]] inline expected<Histogram> try_histogram(const HistogramSpec& spec) noexcept {
    return Registry::global()->try_histogram(spec);
}
[[nodiscard]] inline expected<Summary> try_summary(const SummarySpec& spec) noexcept {
    return Registry::global()->try_summary(spec);
}
[[nodiscard]] inline expected<Untyped> try_untyped(const UntypedSpec& spec) noexcept {
    return Registry::global()->try_untyped(spec);
}
[[nodiscard]] inline expected<Info> try_info(const InfoSpec& spec) noexcept {
    return Registry::global()->try_info(spec);
}
[[nodiscard]] inline expected<StateSet> try_stateset(const StateSetSpec& spec) noexcept {
    return Registry::global()->try_stateset(spec);
}
 
}  // namespace prom