utils::statistics::Writer Class Reference

Class for writing metrics. More...

#include <userver/utils/statistics/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".

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 83 of file writer.hpp.

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 143 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 105 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 136 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 122 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 130 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 86 of file writer.hpp.

---

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

• userver/utils/statistics/writer.hpp