]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | #pragma once |
2 | ||
3 | #include <atomic> | |
4 | ||
5 | #include "prometheus/client_metric.h" | |
6 | #include "prometheus/detail/builder.h" // IWYU pragma: export | |
7 | #include "prometheus/detail/core_export.h" | |
8 | #include "prometheus/metric_type.h" | |
9 | ||
10 | namespace prometheus { | |
11 | ||
12 | /// \brief A gauge metric to represent a value that can arbitrarily go up and | |
13 | /// down. | |
14 | /// | |
15 | /// The class represents the metric type gauge: | |
16 | /// https://prometheus.io/docs/concepts/metric_types/#gauge | |
17 | /// | |
18 | /// Gauges are typically used for measured values like temperatures or current | |
19 | /// memory usage, but also "counts" that can go up and down, like the number of | |
20 | /// running processes. | |
21 | /// | |
22 | /// The class is thread-safe. No concurrent call to any API of this type causes | |
23 | /// a data race. | |
24 | class PROMETHEUS_CPP_CORE_EXPORT Gauge { | |
25 | public: | |
26 | static const MetricType metric_type{MetricType::Gauge}; | |
27 | ||
28 | /// \brief Create a gauge that starts at 0. | |
29 | Gauge() = default; | |
30 | ||
31 | /// \brief Create a gauge that starts at the given amount. | |
32 | Gauge(double); | |
33 | ||
34 | /// \brief Increment the gauge by 1. | |
35 | void Increment(); | |
36 | ||
37 | /// \brief Increment the gauge by the given amount. | |
38 | void Increment(double); | |
39 | ||
40 | /// \brief Decrement the gauge by 1. | |
41 | void Decrement(); | |
42 | ||
43 | /// \brief Decrement the gauge by the given amount. | |
44 | void Decrement(double); | |
45 | ||
46 | /// \brief Set the gauge to the given value. | |
47 | void Set(double); | |
48 | ||
49 | /// \brief Set the gauge to the current unixtime in seconds. | |
50 | void SetToCurrentTime(); | |
51 | ||
52 | /// \brief Get the current value of the gauge. | |
53 | double Value() const; | |
54 | ||
55 | /// \brief Get the current value of the gauge. | |
56 | /// | |
57 | /// Collect is called by the Registry when collecting metrics. | |
58 | ClientMetric Collect() const; | |
59 | ||
60 | private: | |
61 | void Change(double); | |
62 | std::atomic<double> value_{0.0}; | |
63 | }; | |
64 | ||
65 | /// \brief Return a builder to configure and register a Gauge metric. | |
66 | /// | |
67 | /// @copydetails Family<>::Family() | |
68 | /// | |
69 | /// Example usage: | |
70 | /// | |
71 | /// \code | |
72 | /// auto registry = std::make_shared<Registry>(); | |
73 | /// auto& gauge_family = prometheus::BuildGauge() | |
74 | /// .Name("some_name") | |
75 | /// .Help("Additional description.") | |
76 | /// .Labels({{"key", "value"}}) | |
77 | /// .Register(*registry); | |
78 | /// | |
79 | /// ... | |
80 | /// \endcode | |
81 | /// | |
82 | /// \return An object of unspecified type T, i.e., an implementation detail | |
83 | /// except that it has the following members: | |
84 | /// | |
85 | /// - Name(const std::string&) to set the metric name, | |
86 | /// - Help(const std::string&) to set an additional description. | |
87 | /// - Labels(const Labels&) to assign a set of | |
88 | /// key-value pairs (= labels) to the metric. | |
89 | /// | |
90 | /// To finish the configuration of the Gauge metric register it with | |
91 | /// Register(Registry&). | |
92 | PROMETHEUS_CPP_CORE_EXPORT detail::Builder<Gauge> BuildGauge(); | |
93 | ||
94 | } // namespace prometheus |