storage.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/utils/statistics/storage.hpp
/// @brief @copybrief utils::statistics::Storage
 
#include <atomic>
#include <functional>
#include <initializer_list>
#include <list>
#include <string>
#include <unordered_map>
#include <variant>
#include <vector>
 
#include <userver/engine/shared_mutex.hpp>
#include <userver/formats/json/value_builder.hpp>
#include <userver/utils/assert.hpp>
#include <userver/utils/statistics/entry.hpp>
#include <userver/utils/statistics/metric_value.hpp>
#include <userver/utils/statistics/writer.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace utils::statistics {
 
/// @brief Used in legacy statistics extenders
struct StatisticsRequest final {};
 
/// @brief Class describing the request for metrics data.
///
/// Metric path and metric name are the same thing. For example for code like
///
/// @code
/// writer["a"]["b"]["c"] = 42;
/// @endcode
///
/// the metric name is "a.b.c" and in Prometheus format it would be escaped like
/// "a_b_c{} 42".
///
/// @note `add_labels` should not match labels from Storage, otherwise the
/// returned metrics may not be read by metrics server.
class Request final {
public:
    using AddLabels = std::unordered_map<std::string, std::string>;
 
    /// Default request without parameters. Equivalent to requesting all the
    /// metrics without adding or requiring any labels.
    Request() = default;
 
    /// Makes request for metrics whose path starts with the `prefix`.
    static Request
    MakeWithPrefix(const std::string& prefix, AddLabels add_labels = {}, std::vector<Label> require_labels = {});
 
    /// Makes request for metrics whose path is `path`.
    static Request
    MakeWithPath(const std::string& path, AddLabels add_labels = {}, std::vector<Label> require_labels = {});
 
    /// Return metrics whose path matches with this `prefix`
    const std::string prefix{};
 
    /// Enum for different match types of the `prefix`
    enum class PrefixMatch {
        kNoop,        ///< Do not match, the `prefix` is empty
        kExact,       ///< `prefix` equal to path
        kStartsWith,  ///< Metric path starts with `prefix`
    };
 
    /// Match type of the `prefix`
    const PrefixMatch prefix_match_type = PrefixMatch::kNoop;
 
    /// Require those labels in the metric
    const std::vector<Label> require_labels{};
 
    /// Add those labels to each returned metric
    const AddLabels add_labels{};
 
private:
    Request(
        std::string prefix_in,
        PrefixMatch path_match_type_in,
        std::vector<Label> require_labels_in,
        AddLabels add_labels_in
    );
};
 
using ExtenderFunc = std::function<formats::json::ValueBuilder(const StatisticsRequest&)>;
 
using WriterFunc = std::function<void(Writer&)>;
 
namespace impl {
 
struct MetricsSource final {
    std::string prefix_path;
    std::vector<std::string> path_segments;
    ExtenderFunc extender;
 
    WriterFunc writer;
    std::vector<Label> writer_labels;
};
 
using StorageData = std::list<MetricsSource>;
using StorageIterator = StorageData::iterator;
 
inline constexpr bool kCheckSubscriptionUB = utils::impl::kEnableAssert;
 
}  // namespace impl
 
class BaseFormatBuilder {
public:
    virtual ~BaseFormatBuilder();
 
    virtual void HandleMetric(std::string_view path, LabelsSpan labels, const MetricValue& value) = 0;
};
 
/// @ingroup userver_clients
///
/// Storage of metrics, usually retrieved from components::StatisticsStorage.
///
/// See utils::statistics::Writer for an information on how to write metrics.
class Storage final {
public:
    Storage();
 
    Storage(const Storage&) = delete;
 
    /// Creates new Json::Value and calls every deprecated registered extender
    /// func over it.
    ///
    /// @deprecated Use VisitMetrics instead.
    formats::json::Value GetAsJson() const;
 
    /// Visits all the metrics and calls `out.HandleMetric` for each metric.
    void VisitMetrics(BaseFormatBuilder& out, const Request& request = {}) const;
 
    /// @cond
    /// Must be called from StatisticsStorage only. Don't call it from user
    /// components.
    void StopRegisteringExtenders();
    /// @endcond
 
    /// @brief Add a writer function. Note that `func` is called concurrently with
    /// other code, so it should be thread\coroutine safe.
    Entry RegisterWriter(std::string common_prefix, WriterFunc func, std::vector<Label> add_labels = {});
 
    /// @deprecated Use RegisterWriter instead.
    Entry RegisterExtender(std::string prefix, ExtenderFunc func);
 
    void UnregisterExtender(impl::StorageIterator iterator, impl::UnregisteringKind kind) noexcept;
 
private:
    Entry DoRegisterExtender(impl::MetricsSource&& source);
 
    std::atomic<bool> may_register_extenders_;
    impl::StorageData metrics_sources_;
    mutable engine::SharedMutex mutex_;
};
 
}  // namespace utils::statistics
 
USERVER_NAMESPACE_END