utils::statistics::Writer Class Reference

#include <userver/utils/statistics/writer.hpp>

Detailed Description

Class for writing metrics.

The Writer could be customized by providing a void DumpMetric(utils::statistics::Writer& writer, const Metric& value) function:

struct ComponentMetricsNested {
    std::atomic<int> nested1{17};
    std::atomic<int> nested2{18};
};
 
void DumpMetric(utils::statistics::Writer& writer, const ComponentMetricsNested& m) {
    // Metric without labels
    writer["nested1"] = m.nested1;
 
    // Metric with label
    writer["nested2"].ValueWithLabels(m.nested2, {"label_name", "label_value"});
}

DumpMetric functions nest well, labels are propagated to the nested DumpMetric:

struct ComponentMetrics {
    rcu::RcuMap<std::string, ComponentMetricsNested> metrics;
};
 
void DumpMetric(utils::statistics::Writer& writer, const ComponentMetrics& m) {
    for (const auto& [key, value] : m.metrics) {
        UASSERT(value);
        writer.ValueWithLabels(*value, {{"a_label", key}, {"b_label", "b"}});
    }
}

To use the above writers register the metric writer in utils::statistics::Storage component:

    holder_ = storage.RegisterWriter(
        "begin-on-the-metric-path",
        [&](Writer& writer) {
            // Metric without labels
            writer["metric1"] = 42;
 
            ComponentMetrics& metrics = component_metrics_;
            writer["more_metrics"] = metrics;
        },
        {{"label_for_all", "labell value"}}
    );

The above metrics in Graphite format would look like:

begin-on-the-metric-path.metric1;label_for_all=labell_value 42 1674810371
begin-on-the-metric-path.more_metrics.nested1;label_for_all=labell_value;a_label=metric-in-map;b_label=b 17 1674810371
begin-on-the-metric-path.more_metrics.nested2;label_for_all=labell_value;a_label=metric-in-map;b_label=b;label_name=label_value 18 1674810371

The Writer is usable by the utils::statistics::MetricTag. For example, for the following structure:

struct Stats {
    std::atomic<std::uint64_t> opened_sockets{0};
    std::atomic<std::uint64_t> closed_sockets{0};
    std::atomic<std::uint64_t> bytes_read{0};
};

The DumpMetric function may look like:

const utils::statistics::MetricTag<Stats> kTcpEchoTag{"tcp-echo"};
 
void DumpMetric(utils::statistics::Writer& writer, const Stats& stats) {
    writer["sockets"]["opened"] = stats.opened_sockets;
    writer["sockets"]["closed"] = stats.closed_sockets;
    writer["bytes"]["read"] = stats.bytes_read;
}
 
void ResetMetric(Stats& stats) {
    stats.opened_sockets = 0;
    stats.closed_sockets = 0;
    stats.bytes_read = 0;
}

For information on metrics testing in testsuite refer to Testsuite - Metrics.

For metrics testing in unit-tests see utils::statistics::Snapshot.

Examples

samples/tcp_full_duplex_service/tcp_full_duplex_service.cpp.

Definition at line 84 of file writer.hpp.

Public Member Functions
	Writer (Writer &&other)=delete
	Writer (const Writer &)=delete
Writer &	operator= (Writer &&)=delete
Writer &	operator= (const Writer &)=delete
Writer	operator[] (std::string_view path) &
	Returns a Writer with a ('.' + path) appended.
Writer	operator[] (std::string_view path) &&
	Returns a Writer with a ('.' + path) appended.
template<class T >
void	operator= (const T &value)
template<class T >
void	ValueWithLabels (const T &value, LabelsSpan labels)
	Write metric value with labels to metrics builder.
template<class T >
void	ValueWithLabels (const T &value, std::initializer_list< LabelView > il)
	Write metric value with labels to metrics builder.
template<class T >
void	ValueWithLabels (const T &value, const LabelView &label)
	Write metric value with label to metrics builder.
	operator bool () const noexcept

Static Public Attributes
static constexpr char	kDelimiter = '.'
	Path parts delimiter. In other words, writer["a"]["b"] becomes "a.b".

Member Function Documentation

operator bool()

utils::statistics::Writer::operator bool ( ) const

inlineexplicitnoexcept

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.

Definition at line 166 of file writer.hpp.

operator=()

template<class T >

void utils::statistics::Writer::operator= ( const T & value )

inline

Write metric value to metrics builder via using DumpMetric function.

Definition at line 106 of file writer.hpp.

ValueWithLabels() [1/3]

template<class T >

void utils::statistics::Writer::ValueWithLabels ( const T & value, const LabelView & label )

inline

Write metric value with label to metrics builder.

Definition at line 138 of file writer.hpp.

ValueWithLabels() [2/3]

template<class T >

void utils::statistics::Writer::ValueWithLabels ( const T & value, LabelsSpan labels )

inline

Write metric value with labels to metrics builder.

Definition at line 124 of file writer.hpp.

ValueWithLabels() [3/3]

template<class T >

void utils::statistics::Writer::ValueWithLabels ( const T & value, std::initializer_list< LabelView > il )

inline

Write metric value with labels to metrics builder.

Definition at line 132 of file writer.hpp.

Member Data Documentation

kDelimiter

constexpr char utils::statistics::Writer::kDelimiter = '.'

inlinestaticconstexpr

Path parts delimiter. In other words, writer["a"]["b"] becomes "a.b".

Definition at line 87 of file writer.hpp.

---

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

• userver/utils/statistics/writer.hpp