balm_publicationscheduler

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Thread Safety
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a scheduler for publishing metrics.

Classes

• balm::PublicationScheduler: a scheduler for publishing metrics

See also

balm_metricsmanager

Description

This component defines a class, balm::PublicationScheduler, that provides a scheduling mechanism for the publication of metrics. At construction, a balm::PublicationScheduler is provided the addresses of a balm::MetricsManager and a bdlmt::TimerEventScheduler. The publication scheduler provides a scheduleCategory method that schedules an individual metric category to be published repeatedly at a given interval, and a setDefaultSchedule method that schedules the publication of any category not given an individual schedule. The balm::PublicationScheduler creates timer events using the bdlmt::TimerEventScheduler. At the end of a scheduled time interval, the publication scheduler invokes the metrics manager's publish operation with the set of categories to publish. Note that the publication scheduler will combine categories that occur at the same frequency into a single invocation of the metrics manager's publish operation. The publication scheduler also provides a method to cancel the publication of a particular category, or of all categories.

Alternative Systems for Telemetry

Bloomberg software may alternatively use the GUTS telemetry API, which is integrated into Bloomberg infrastructure.

Thread Safety

balm::PublicationScheduler is fully thread-safe, meaning that all non-creator operations on a given instance can be safely invoked simultaneously from multiple threads.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following example demonstrates how to use balm::PublicationScheduler. Before instantiating the publication scheduler, we create a bdlmt::TimerEventScheduler as well as a balm::MetricsManager. We obtain collectors for three different metric categories, "A", "B", and "C", that we will use to generate metric values for publication.

bslma::Allocator         *allocator = bslma::Default::allocator(0);
bdlmt::TimerEventScheduler  timer(allocator);
balm::MetricsManager       manager(allocator);
 
balm::Collector *A = manager.collectorRepository().getDefaultCollector(
                                                                 "A", "a");
balm::Collector *B = manager.collectorRepository().getDefaultCollector(
                                                                 "B", "b");
balm::Collector *C = manager.collectorRepository().getDefaultCollector(
                                                                 "C", "c");

We now create an instance of SimpleStreamPublisher, which implements the balm::Publisher protocol. Note that SimpleStreamPublisher is an example implementation of the balm::Publisher protocol defined in the balm_publisher component. In practice, clients typically use a standard publisher class (e.g., balm::StreamPublisher).

    bsl::shared_ptr<balm::Publisher> publisher(
                        new (*allocator) SimpleStreamPublisher(bsl::cout),
                        allocator);

We now register the publisher we have created with the metrics manager to publish our categories. Then, we start the timer-event scheduler we will supply to the balm::PublicationScheduler.

manager.addGeneralPublisher(publisher);
timer.start();

Now we construct a balm::PublicationScheduler and pass it the respective addresses of both the metrics manager and the timer-event scheduler. We schedule the publication of category "A" and "B" every .05 seconds, then we set the scheduled default publication to every .10 seconds. Note that those time intervals were chosen to ensure fast and consistent output for this example. In normal usage the interval between publications should be large enough to ensure that metric publication does not negatively affect the performance of the application (a 30 second interval is typical).

balm::PublicationScheduler scheduler(&manager, &timer, allocator);
scheduler.scheduleCategory("A", bsls::TimeInterval(.05));
scheduler.scheduleCategory("B", bsls::TimeInterval(.05));
scheduler.setDefaultSchedule(bsls::TimeInterval(.10));

We can use the accessor operations to verify the schedule that we have specified.

bsls::TimeInterval intervalA, intervalB, intervalC, defaultInterval;
assert( scheduler.findCategorySchedule(&intervalA, "A"));
assert( scheduler.findCategorySchedule(&intervalB, "B"));
assert(!scheduler.findCategorySchedule(&intervalC, "C"));
assert( scheduler.getDefaultSchedule(&defaultInterval));
 
assert(bsls::TimeInterval(.05) == intervalA);
assert(bsls::TimeInterval(.05) == intervalB);
assert(bsls::TimeInterval(.10) == defaultInterval);

Finally we add a couple of metrics and wait just over .1 seconds.

A->update(1.0);
B->update(2.0);
C->update(3.0);
bslmt::ThreadUtil::sleep(bsls::TimeInterval(.11));

The output of the publication should look similar to:

19NOV2008_18:34:26.766+0000    2 Records   0.0517s Elapsed Time
        A.a [count = 1, total = 1, min = 1, max = 1]
        B.b [count = 1, total = 2, min = 2, max = 2]
19NOV2008_18:34:26.816+0000    2 Records   0.050183s Elapsed Time
        A.a [count = 0, total = 0, min = inf, max = -inf]
        B.b [count = 0, total = 0, min = inf, max = -inf]
19NOV2008_18:34:26.817+0000    1 Records   0.102473s Elapsed Time
        C.c [count = 1, total = 3, min = 3, max = 3]

Note that category C is published as part of the scheduled default publication. Also note that categories A and B are emitted as a single publication: the scheduler combines categories published at the same frequency into a single publication event to minimize the number of times balm::MetricsManager::publish is invoked.