bdlm_metricsregistry

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Using bdlm::MetricsRegistry

Purpose

Provide a transferable registry of metric registrations.

Deprecated:

This component is not ready for public use.

Classes

• bdlm::MetricsRegistry: transferable registry of metric registrations
• bdlm::MetricsRegistryRegistrationHandle: registration handle providing RAII

Description

This component contains a mechanism, bdlm::MetricsRegistry, that provides a registry of metrics that is transferable to implementations of the bdlm::MetricsAdapter protocol. bdlm, as a low-level metrics facility, does not directly manage schedulers to collect metrics values or publishers to publish those value. Instead bdlm is designed to allow applications to plug in different high-level feature-rich metrics collection and publication frameworks (without requiring a library dependency on those frameworks). A bdlm::MetricsRegistry effectively serves as a proxy for a higher-level metrics collection system implementing the MetricsAdapter protocol – it keeps track of registered metrics allowing a higher-level metrics subsystem to be installed (by calling 'setMetricsAdapter) at any time, either before or after a metric is registered.

A singleton instance of MetricsRegistry is available from the defaultInstance class method. This component also provides a registration handle class, bdlm::MetricsRegistryRegistrationHandle, that provides RAII semantics for metric registration.

Thread Safety

The class bdlm::MetricsRegistry is thread-aware (see {bsldoc_glossary |Thread-Aware}), and bdlm::MetricsRegistryRegistrationHandle is minimally thread-safe (see {bsldoc_glossary |Minimally Thread-Safe}).

Usage

This section illustrates intended use of this component.

Example 1: Using bdlm::MetricsRegistry

This example demonstrates the initialization and usage of the bdlm::MetricsRegistry object, allowing for registering metric callback functions with the bdlm monitoring system.

First, we declare a class that provides some metric for the bdlm monitoring system:

class LowLevelFacility {
    // PRIVATE DATA
    bdlm::MetricsRegistryRegistrationHandle d_metricHandle;
  public:
    // CREATORS
    explicit LowLevelFacility(bdlm::MetricsRegistry& metricsRegistry =
                                 bdlm::MetricsRegistry::defaultInstance());
 
    // ACCESSORS
    int someMetric() const
    {
        return 0; // just a stub
    }
};

Next, we provide a metric function to be used during callback registration:

void metricCallback(bdlm::Metric *value, const LowLevelFacility *object)
{
    *value = bdlm::Metric::Gauge(object->someMetric());
}

Here is the constructor definition that registers the collection callback:

/// Construct a `bdlm::MetricsDescriptor` object to be used when
/// registering the callback function:
LowLevelFacility::LowLevelFacility(bdlm::MetricsRegistry& metricsRegistry)
{
    bdlm::MetricDescriptor descriptor("bdlm",
                                      "example",
                                      1,
                                      "bdlmmetricsregistry",
                                      "bmr",
                                      "identifier");
 
    // Register the collection callback:
    metricsRegistry.registerCollectionCallback(
                               &d_metricHandle,
                               descriptor,
                               bdlf::BindUtil::bind(&metricCallback,
                                                    bdlf::PlaceHolders::_1,
                                                    this));
    assert(d_metricHandle.isRegistered());
}

Notice that the compiler-supplied destructor is sufficient because the d_metricHandle will deregister the metric on destruction.

Now, we construct a bdlm::MetricsRegistry object with a test allocator:

bslma::TestAllocator  ta;
bdlm::MetricsRegistry registry(&ta);
assert(registry.numRegisteredCollectionCallbacks() == 0);

Then, we create the object and pass the constructed bdlm::MetricsRegistry object there:

{
    LowLevelFacility facility(registry);
    assert(registry.numRegisteredCollectionCallbacks() == 1);

If we don't provide a bdlm::MetricsRegistry object explicitly, the default global instance will be used.

Finally, the callback is removed the monitoring system by the destructor of facility object:

} // 'facility.d_metricHandle.unregister()' is called here
assert(registry.numRegisteredCollectionCallbacks() == 0);