utils::statistics::Writer Class Reference

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

Detailed Description

Class for writing metrics that is provided by utils::statistics::Storage.

Usage is quite straightforward:

    // `storage` is a utils::statistics::Storage, `holder_` is a component member of type utils::statistics::Entry
    holder_ = storage.RegisterWriter(
        "path-begin",
        [&](utils::statistics::Writer& writer) {
            // Metric without labels
            writer["metric1"] = 1;
 
            // Metric with single label
            writer["metric2"].ValueWithLabels(2, {"label_name1", "value1"});
 
            // Metric with multiple labels
            writer["metric3"].ValueWithLabels(3, {{"label_name2", "value2"}, {"label_name3", "value3"}});
 
            // Compute and write a bunch of heavy metrics only if they were requested
            if (auto subpath = writer["a"]["b"]) {
                subpath["mc4"] = HeavyComputation();
                subpath["mc5"] = HeavyComputation2();
            }
        },
        {{"label_for_all", "value_all"}}
    );

The above sample would produce the following metrics:

path-begin.metric1: label_for_all=value_all GAUGE 1
path-begin.metric2: label_for_all=value_all, label_name1=value1 GAUGE 2
path-begin.metric3: label_for_all=value_all, label_name2=value2, label_name3=value3 GAUGE 3
path-begin.a.b.mc4: label_for_all=value_all GAUGE 4
path-begin.a.b.mc5: label_for_all=value_all GAUGE 5

The Writer can be customized for writing custom metric types by providing a void DumpMetric(utils::statistics::Writer& writer, const CustomMetric& 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 92 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 174 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 114 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 146 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 132 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 140 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 95 of file writer.hpp.

---

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

• userver/utils/statistics/writer.hpp