writer.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/utils/statistics/writer.hpp
/// @brief @copybrief utils::statistics::Writer
 
#include <atomic>
#include <string_view>
#include <type_traits>
 
#include <userver/utils/function_ref.hpp>
#include <userver/utils/impl/internal_tag.hpp>
#include <userver/utils/statistics/histogram_view.hpp>
#include <userver/utils/statistics/labels.hpp>
#include <userver/utils/statistics/rate.hpp>
#include <userver/utils/statistics/request.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace utils::statistics {
 
class Writer;
class MetricValue;
 
namespace impl {
struct WriterState;
}  // namespace impl
 
/// @brief Returns true, if the `Metric` could be written by @ref utils::statistics::Writer.
///
/// In other words, checks that the `DumpMetric` for the `Metric` is provided or
/// that the metric could be written without providing one.
template <class Metric>
concept HasWriterSupport = std::is_arithmetic_v<Metric> || requires(Writer& writer, const Metric& metric) {
    DumpMetric(writer, metric);
};
 
/// @ingroup userver_universal
///
/// @brief Class for writing metrics that is provided by utils::statistics::Storage.
///
/// Usage is quite straightforward:
///
/// @snippet core/src/utils/statistics/pretty_format_test.cpp  Writer basic sample
///
/// The above sample would produce the following metrics:
///
/// @snippet core/src/utils/statistics/pretty_format_test.cpp  metrics pretty
///
/// The Writer can be customized for writing custom metric types by providing a
/// `void DumpMetric(utils::statistics::Writer& writer, const CustomMetric& value)`
/// function:
///
/// @snippet core/src/utils/statistics/writer_test.cpp  DumpMetric basic
///
/// DumpMetric functions nest well, labels are propagated to the nested
/// DumpMetric:
///
/// @snippet core/src/utils/statistics/writer_test.cpp  DumpMetric nested
///
/// To use the above writers register the metric writer in
/// @ref utils::statistics::Storage component:
///
/// @snippet core/src/utils/statistics/writer_test.cpp  DumpMetric RegisterWriter
///
/// The above metrics in Graphite format would look like:
/// @snippet core/src/utils/statistics/writer_test.cpp  metrics graphite
///
/// The Writer is usable by the utils::statistics::MetricTag. For example, for
/// the following structure:
/// @snippet samples/tcp_full_duplex_service/main.cpp  TCP sample - Stats definition
///
/// The DumpMetric function may look like:
/// @snippet samples/tcp_full_duplex_service/main.cpp  TCP sample - Stats tag
///
/// For information on metrics testing in testsuite refer to
/// @ref TESTSUITE_METRICS_TESTING "Testsuite - Metrics".
///
/// For metrics testing in unit-tests see utils::statistics::Snapshot.
///
/// For introduction to metrics see @ref scripts/docs/en/userver/metrics.md
class Writer final {
public:
    /// Path parts delimiter. In other words, writer["a"]["b"] becomes "a.b"
    static constexpr char kDelimiter = '.';
 
    Writer() = delete;
    Writer(Writer&& other) = delete;
    Writer(const Writer&) = delete;
    Writer& operator=(Writer&&) = delete;
    Writer& operator=(const Writer&) = delete;
 
    ~Writer();
 
    /// Returns a Writer with a ('.' + path) appended
    [[nodiscard]] Writer operator[](std::string_view path) &;
 
    /// Returns a Writer with a ('.' + path) appended
    [[nodiscard]] Writer operator[](std::string_view path) &&;
 
    /// Write metric value to metrics builder via using DumpMetric
    /// function.
    template <class T>
    void operator=(const T& value) {
        if constexpr (std::is_arithmetic_v<T> || std::is_same_v<std::decay_t<T>, Rate> ||
                      std::is_same_v<std::decay_t<T>, HistogramView> || std::is_same_v<std::decay_t<T>, MetricValue>)
        {
            Write(value);
        } else {
            if (state_) {
                static_assert(
                    HasWriterSupport<T>,
                    "Cast the metric to an arithmetic type or provide a "
                    "`void DumpMetric(utils::statistics::Writer& writer, "
                    "const Metric& value)` function for the `Metric` type"
                );
                DumpMetric(*this, value);
            }
        }
    }
 
    /// Write metric value with labels to metrics builder
    template <class T>
    void ValueWithLabels(const T& value, LabelsSpan labels) {
        auto new_writer = MakeChild();
        new_writer.AppendLabelsSpan(labels);
        new_writer = value;
    }
 
    /// Write metric value with labels to metrics builder
    template <class T>
    void ValueWithLabels(const T& value, std::initializer_list<LabelView> il) {
        ValueWithLabels(value, LabelsSpan{il});
    }
 
    /// Write metric value with label to metrics builder
    template <class T>
    void ValueWithLabels(const T& value, const LabelView& label) {
        ValueWithLabels(value, LabelsSpan{&label, &label + 1});
    }
 
    /// @cond
    /// func must be called even for filtered out Writers, e.g. to always collect
    /// totals
    template <class Func>
    void WithLabels(utils::impl::InternalTag, LabelsSpan labels, Func func) {
        auto new_writer = MakeChild();
        new_writer.AppendLabelsSpan(labels);
        func(new_writer);
    }
 
    template <class Func>
    void WithLabels(utils::impl::InternalTag, std::initializer_list<LabelView> il, Func func) {
        WithLabels(utils::impl::InternalTag{}, LabelsSpan{il}, func);
    }
 
    template <class Func>
    void WithLabels(utils::impl::InternalTag, const LabelView& label, Func func) {
        WithLabels(utils::impl::InternalTag{}, LabelsSpan{&label, &label + 1}, func);
    }
    /// @endcond
 
    /// Returns true if this writer would actually write data. Returns false if
    /// the data is not required by request and metrics construction could be
    /// skipped.
    explicit operator bool() const noexcept { return !!state_; }
 
    /// @cond
    explicit Writer(impl::WriterState* state) noexcept;
    explicit Writer(impl::WriterState& state, LabelsSpan labels);
    /// @endcond
 
private:
    using ULongLong = unsigned long long;
 
    using PathSizeType = std::uint16_t;
    using LabelsSizeType = std::uint8_t;
 
    void Write(unsigned long long value);
    void Write(long long value);
    void Write(double value);
    void Write(Rate value);
    void Write(HistogramView value);
    void Write(MetricValue value);
 
    void Write(float value) { Write(static_cast<double>(value)); }
 
    void Write(unsigned long value) { Write(static_cast<ULongLong>(value)); }
    void Write(long value) { Write(static_cast<long long>(value)); }
    void Write(unsigned int value) { Write(static_cast<long long>(value)); }
    void Write(int value) { Write(static_cast<long long>(value)); }
    void Write(unsigned short value) { Write(static_cast<long long>(value)); }
    void Write(short value) { Write(static_cast<long long>(value)); }
 
    Writer MakeChild();
 
    struct MoveTag {};
    Writer(Writer& other, MoveTag) noexcept;
 
    Writer MoveOut() noexcept { return Writer{*this, MoveTag{}}; }
 
    void ResetState() noexcept;
    void ValidateUsage();
 
    void AppendPath(std::string_view path);
    void AppendLabelsSpan(LabelsSpan labels);
 
    impl::WriterState* state_;
    const PathSizeType initial_path_size_;
    PathSizeType current_path_size_;
    const LabelsSizeType initial_labels_size_;
    LabelsSizeType current_labels_size_;
};
 
/// Non-owning reference to a function that writes metrics via @ref Writer.
using WriterFuncRef = utils::function_ref<void(Writer&) const>;
 
template <class Metric>
void DumpMetric(Writer& writer, const std::atomic<Metric>& m) {
    static_assert(std::atomic<Metric>::is_always_lock_free, "std::atomic misuse");
    writer = m.load();
}
 
/// @brief Low-level connecting function that dumps metrics from @a func into @a out.
///
/// Calls @a func with a @ref Writer. Each metric written through that `Writer`
/// is forwarded to `out.HandleMetric`. @a request filters the metrics and may
/// attach extra labels; `request.prefix` is a match filter, not a path to write
/// under.
///
/// @ref utils::statistics::Storage::VisitMetrics uses this function to dump
/// Writer-based metrics. It is used to implement formats such as:
/// - @ref utils::statistics::ToPrometheusFormat "Prometheus"
/// - @ref utils::statistics::ToGraphiteFormat "Graphite"
/// - @ref utils::statistics::ToJsonFormat "JSON"
/// - @ref utils::statistics::ToPrettyFormat "pretty format"
/// - @ref utils::statistics::ToSolomonFormat "Solomon"
/// - @ref utils::statistics::GetPortabilityWarnings "portability info"
///
/// @param func writes metrics to the provided @ref Writer
/// @param out receives each written metric via @ref BaseFormatBuilder::HandleMetric
/// @param request metric filter and extra labels
void VisitMetrics(WriterFuncRef func, BaseFormatBuilder& out, const Request& request = {});
 
/// @overload
///
/// Dumps @a metric via `writer = metric` (`DumpMetric` / built-in Writer support).
void VisitMetrics(const HasWriterSupport auto& metric, BaseFormatBuilder& out, const Request& request = {}) {
    utils::statistics::VisitMetrics([&metric](Writer& writer) { writer = metric; }, out, request);
}
 
}  // namespace utils::statistics
 
USERVER_NAMESPACE_END