BDE 4.14.0 Production release
Loading...
Searching...
No Matches
balm_bdlmmetricsadapter.h
Go to the documentation of this file.
1/// @file balm_bdlmmetricsadapter.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// balm_bdlmmetricsadapter.h -*-C++-*-
8
9#ifndef INCLUDED_BALM_BDLMMETRICSADAPTER
10#define INCLUDED_BALM_BDLMMETRICSADAPTER
11
12#include <bsls_ident.h>
13BSLS_IDENT("$Id: $")
14
15/// @defgroup balm_bdlmmetricsadapter balm_bdlmmetricsadapter
16/// @brief Provide a concrete instance of the `bdlm` metrics adapter.
17/// @addtogroup bal
18/// @{
19/// @addtogroup balm
20/// @{
21/// @addtogroup balm_bdlmmetricsadapter
22/// @{
23///
24/// <h1> Outline </h1>
25/// * <a href="#balm_bdlmmetricsadapter-purpose"> Purpose</a>
26/// * <a href="#balm_bdlmmetricsadapter-classes"> Classes </a>
27/// * <a href="#balm_bdlmmetricsadapter-description"> Description </a>
28/// * <a href="#balm_bdlmmetricsadapter-thread-safety"> Thread Safety </a>
29/// * <a href="#balm_bdlmmetricsadapter-usage"> Usage </a>
30/// * <a href="#balm_bdlmmetricsadapter-example-1-using-balm-bdlmmetricsadapter"> Example 1: Using balm::BdlmMetricsAdapter </a>
31///
32/// # Purpose {#balm_bdlmmetricsadapter-purpose}
33/// Provide a concrete instance of the `bdlm` metrics adapter.
34///
35/// # Classes {#balm_bdlmmetricsadapter-classes}
36///
37/// - balm::BdlmMetricsAdapter: concrete instance of the metrics registar
38///
39/// # Description {#balm_bdlmmetricsadapter-description}
40/// This component provides a concrete instance,
41/// `balm::BdlmMetricsAdapter`, of the `bdlm::MetricsAdapter` protocol, enabling
42/// registration of metric collection callbacks with a provided
43/// `balm::MetricsManager`. `balm::BdlmMetricsAdapter` also provides methods to
44/// aid in population of default `bdlm::MetricDescriptor` attribute values.
45///
46/// ## Thread Safety {#balm_bdlmmetricsadapter-thread-safety}
47///
48///
49/// This class is *thread-aware* (see {@ref bsldoc_glossary |Thread-Aware}).
50///
51/// ## Usage {#balm_bdlmmetricsadapter-usage}
52///
53///
54/// This section illustrates intended use of this component.
55///
56/// ### Example 1: Using balm::BdlmMetricsAdapter {#balm_bdlmmetricsadapter-example-1-using-balm-bdlmmetricsadapter}
57///
58///
59/// This example demonstrates the initialization and usage of the
60/// `balm::BdlmMetricsAdapter` object, allowing for registering metric callback
61/// functions with the `balm` monitoring system.
62///
63/// First, we provide a metric function to be used during callback registration
64/// with the `balm` monitoring system:
65/// @code
66/// void elidedMetric(BloombergLP::bdlm::Metric *value)
67/// {
68/// (void)value;
69/// // ...
70/// }
71/// @endcode
72/// Then, we construct a `balm::MetricsManager` object and use it to construct a
73/// `balm::BdlmMetricsAdapter` that will use "bdlm" as its default metric
74/// namespace, "svc" as its default object indentifier prefix, and will not
75/// attempt to set itself as the default metrics adapter:
76/// @code
77/// balm::MetricsManager manager;
78/// balm::BdlmMetricsAdapter adapter(&manager, "bdlm", "svc");
79/// @endcode
80/// Next, we construct a `bdlm::MetricsDescriptor` object to be used when
81/// registering the callback function, using constants from
82/// `bdlm::MetricDescriptor` for the namespace and identifier to indicate the
83/// implementation of the `bdlm::MetricsAdapter` protocol should supply values:
84/// @code
85/// bdlm::MetricDescriptor descriptor(
86/// bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_NAMESPACE_SELECTION,
87/// "example",
88/// 1,
89/// "balm.bdlmmetricsadapter",
90/// "bmr",
91/// bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_OBJECT_ID_SELECTION);
92/// @endcode
93/// Now, we register the collection callback:
94/// @code
95/// bdlm::MetricsAdapter::CallbackHandle handle =
96/// adapter.registerCollectionCallback(descriptor,
97/// elidedMetric);
98/// @endcode
99/// Finally, presumably during shutdown of the application, we remove the
100/// callback from the monitoring system, and verify the callback was
101/// successfully removed:
102/// @code
103/// assert(0 == adapter.removeCollectionCallback(handle));
104/// @endcode
105/// @}
106/** @} */
107/** @} */
108
109/** @addtogroup bal
110 * @{
111 */
112/** @addtogroup balm
113 * @{
114 */
115/** @addtogroup balm_bdlmmetricsadapter
116 * @{
117 */
118
119#include <bdlf_bind.h>
120
122#include <bdlm_metricsadapter.h>
123
126#include <balm_metricid.h>
127#include <balm_metricrecord.h>
128#include <balm_metricsmanager.h>
129
130#include <bslma_allocator.h>
132
134
135#include <bslmt_lockguard.h>
136#include <bslmt_mutex.h>
137
138#include <bsls_keyword.h>
139
140
141namespace balm {
142
143 // ========================
144 // class BdlmMetricsAdapter
145 // ========================
146
147/// This class implements a pure abstract interface for clients and
148/// suppliers of metrics adapters. The implementation registers callbacks
149/// with a provided `balm::MetricsManager` to enable monitoring of
150/// statistics collection objects.
151///
152/// See @ref balm_bdlmmetricsadapter
154
155 // PRIVATE CLASS METHODS
156
157 /// Load into the specified `records` a new record with the specified
158 /// `id` and statistics obtained from the specified `callback` and, if
159 /// the specified `resetFlag` is `true`, reset the statistics to their
160 /// default state.
161 static void metricCb(bsl::vector<MetricRecord> *records,
162 bool resetFlag,
163 MetricId id,
164 const Callback& callback);
165
166 // DATA
167 MetricsManager *d_metricsManager_p; // held, but not owned,
168 // metrics manager
169
170 const bsl::string d_metricNamespace; // default metric namespace
171 // attribute value
172
173 const bsl::string d_objectIdentifierPrefix; // default prefix for object
174 // identifier attribute
175 // values
176
177 // NOT IMPLEMENTED
180 BdlmMetricsAdapter operator=(const BdlmMetricsAdapter&)
182
183 public:
184 // TRAITS
187
188 // CREATORS
189
190 /// Create a `BdlmMetricsAdapter` object that uses the specified
191 /// `metricsManager` to register and unregister collection callback
192 /// functors, the specified `metricNamespace` as the value returned by
193 /// `defaultNamespace()`, and the specified `objectIdentifierPrefix` as
194 /// the value returned by `defaultObjectIdentifierPrefix`. Optionally
195 /// specify a `basicAllocator` used to supply memory. If
196 /// `basicAllocator` is 0, the currently installed default allocator is
197 /// used.
198 BdlmMetricsAdapter(MetricsManager *metricsManager,
199 const bsl::string_view& metricNamespace,
200 const bsl::string_view& objectIdentifierPrefix,
201 bslma::Allocator *basicAllocator = 0);
202
203 /// Destroy this `BdlmMetricsAdapter` object.
205
206 // MANIPULATORS
207
208 /// Register the specified `callback` with the metrics manager specified
209 /// at construction, using the specified `metricDescriptor`. If
210 /// `metricDescriptor.metricsNamspace()` equals
211 /// `bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_NAMESPACE_SELECTION`,
212 /// use `defaultMetricNamespace()` for the namespace attribute during
213 /// registration. If `metricDescriptor.objectIdentifier()` equals
214 /// `bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_OBJECT_ID_SELECTION`,
215 /// use the concatination of `defaultObjectIdentifierPrefix()`, a
216 /// period, `metricDescriptor.objectTypeAbbreviation()`, a period, and
217 /// `metricDescriptor.instanceNumber()` for the object identifier
218 /// attribute during registration. The category name supplied to the
219 /// `MetricsManager` provided at construction is the concatenation of
220 /// the object type name attribute, a period, the metric name attribute,
221 /// a period, and the object identifier attribute. Return the callback
222 /// handle to be used with `removeCollectionCallback`.
224 const bdlm::MetricDescriptor& metricDescriptor,
225 const Callback& callback) BSLS_KEYWORD_OVERRIDE;
226
229 // Remove the callback associated with the specified 'handle' from the
230 // metrics manager specified at construction. Return 0 on success, or
231 // a non-zero value if 'handle' cannot be found.
232
233 // ACCESSORS
234
235 /// Return the namespace attribute value to be used as the default value
236 /// for `MetricDescriptor` instances.
237 const bsl::string& defaultMetricNamespace() const;
238
239 /// Return a string to be used as the default prefix for a
240 /// `MetricDescriptor` object identifier attribute value.
241 const bsl::string& defaultObjectIdentifierPrefix() const;
242
243 // Aspects
244
245 /// Return the allocator used by this object to supply memory.
246 bslma::Allocator *allocator() const;
247};
248
249// ============================================================================
250// INLINE DEFINITIONS
251// ============================================================================
252
253 // ------------------------
254 // class BdlmMetricsAdapter
255 // ------------------------
256
257// CREATORS
258inline
260 balm::MetricsManager *metricsManager,
261 const bsl::string_view& metricNamespace,
262 const bsl::string_view& objectIdentifierPrefix,
263 bslma::Allocator *basicAllocator)
264: d_metricsManager_p(metricsManager)
265, d_metricNamespace(metricNamespace, basicAllocator)
266, d_objectIdentifierPrefix(objectIdentifierPrefix, basicAllocator)
267{
268}
269
270// MANIPULATORS
271inline
273{
274 return d_metricsManager_p->removeCollectionCallback(handle);
275}
276
277// ACCESSORS
278inline
280{
281 return d_metricNamespace;
282}
283
284inline
286{
287 return d_objectIdentifierPrefix;
288}
289
290inline
292{
293 return d_metricNamespace.get_allocator().mechanism();
294}
295
296} // close package namespace
297
298
299#endif
300
301// ----------------------------------------------------------------------------
302// Copyright 2024 Bloomberg Finance L.P.
303//
304// Licensed under the Apache License, Version 2.0 (the "License");
305// you may not use this file except in compliance with the License.
306// You may obtain a copy of the License at
307//
308// http://www.apache.org/licenses/LICENSE-2.0
309//
310// Unless required by applicable law or agreed to in writing, software
311// distributed under the License is distributed on an "AS IS" BASIS,
312// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
313// See the License for the specific language governing permissions and
314// limitations under the License.
315// ----------------------------- END-OF-FILE ----------------------------------
316
317/** @} */
318/** @} */
319/** @} */
Definition balm_bdlmmetricsadapter.h:153
const bsl::string & defaultObjectIdentifierPrefix() const
Definition balm_bdlmmetricsadapter.h:285
const bsl::string & defaultMetricNamespace() const
Definition balm_bdlmmetricsadapter.h:279
bslma::Allocator * allocator() const
Return the allocator used by this object to supply memory.
Definition balm_bdlmmetricsadapter.h:291
~BdlmMetricsAdapter() BSLS_KEYWORD_OVERRIDE
Destroy this BdlmMetricsAdapter object.
BSLMF_NESTED_TRAIT_DECLARATION(BdlmMetricsAdapter, bslma::UsesBslmaAllocator)
int removeCollectionCallback(const CallbackHandle &handle) BSLS_KEYWORD_OVERRIDE
Definition balm_bdlmmetricsadapter.h:272
CallbackHandle registerCollectionCallback(const bdlm::MetricDescriptor &metricDescriptor, const Callback &callback) BSLS_KEYWORD_OVERRIDE
Definition balm_metricid.h:162
Definition balm_metricsmanager.h:490
int removeCollectionCallback(CallbackHandle handle)
Definition bdlm_metricsadapter.h:293
int CallbackHandle
Definition bdlm_metricsadapter.h:297
Definition bslstl_stringview.h:441
Definition bslstl_string.h:1281
allocator_type get_allocator() const BSLS_KEYWORD_NOEXCEPT
Return the allocator used by this string to supply memory.
Definition bslstl_string.h:6723
Forward declaration.
Definition bslstl_function.h:934
Definition bslstl_vector.h:1025
Definition bslma_allocator.h:457
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
#define BSLS_KEYWORD_DELETED
Definition bsls_keyword.h:609
#define BSLS_KEYWORD_OVERRIDE
Definition bsls_keyword.h:653
Definition balm_bdlmmetricsadapter.h:141
Definition bdlm_instancecount.h:101
Definition bdlb_printmethods.h:283
Definition balxml_encoderoptions.h:68
Definition bslma_usesbslmaallocator.h:343