Provide a scheduler for publishing metrics.
More...
Namespaces |
namespace | balm |
Detailed Description
- Outline
-
-
- Purpose:
- Provide a scheduler for publishing metrics.
-
- Classes:
-
- See also:
- Component 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:
- 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. 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
). 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
. 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). 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. 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.