feat docs: improve documentation for metrics

Tests: протестировано CI
commit_hash:bcefc5d1d0ef6b1c67f12c06fccef8d50f64c709

core/include/userver/utils/statistics/writer.hpp

@@ -46,10 +46,18 @@ inline constexpr bool kHasWriterSupport = impl::HasDumpMetricWriter<Metric>();
 
 // clang-format off
 
-/// @brief Class for writing metrics
+/// @brief Class for writing metrics that is provided by utils::statistics::Storage.
 ///
-/// The Writer could be customized by providing a
-/// `void DumpMetric(utils::statistics::Writer& writer, const Metric& value)`
+/// 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

core/src/utils/statistics/pretty_format_test.cpp

@@ -7,6 +7,51 @@ USERVER_NAMESPACE_BEGIN
 
 namespace {
 
+int HeavyComputation() { return 4; }
+
+int HeavyComputation2() { return 5; }
+
+UTEST(MetricsPrettyFormat, SampleBasic) {
+    utils::statistics::Storage storage;
+
+    utils::statistics::Entry holder_;
+    /// [Writer basic sample]
+    // `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"}}
+    );
+    /// [Writer basic sample]
+
+    auto result = utils::statistics::ToPrettyFormat(storage, utils::statistics::Request::MakeWithPrefix("path-begin"));
+
+    constexpr std::string_view ethalon = /** [metrics pretty] */ R"(
+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
+)"; /** [metrics pretty] */
+
+    EXPECT_EQ(result, ethalon.substr(1));
+}
+
 UTEST(MetricsPrettyFormat, CheckFormat) {
     utils::statistics::Storage storage;
 

scripts/docs/en/userver/service_monitor.md

@@ -5,7 +5,7 @@ get the service statistics and metrics.
 
 To produce metrics in declarative style refer to the docs of the
 utils::statistics::MetricTag; to register your metrics writer on per component
-basis refer to the docs of utils::statistics::Storage. To test metrics refer to
+basis refer to the docs of utils::statistics::Writer. To test metrics refer to
 the @ref TESTSUITE_METRICS_TESTING "testsuite metrics testing".