doc/src/user/metrics.im

.** vim: sw=4 ts=4 et :
.if false
==================================================================================
    Copyright (c) 2020 AT&T Intellectual Property.
    Copyright (c) 2020 Nokia

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
==================================================================================
.fi

.if false
    This imbed file contains the description of the metrics API.
    It should be included by the main user.xfm source.
.fi


&h1(Metrics Support)
The C++ xAPP framework provides a  lightweight interface to the metrics
gateway allowing the xAPP to create and send metrics updates without
needing to understand the underlying message format.
From the xAPP's perspective, the metrics object is created with one or
more key/value measurement pairs and then is sent to the process
responsible for forwarding them to the various collection processes.
The following sections describe the Metrics object and the API associated
with it.


&h2(Creating The Metrics Object)
The &cw(xapp:Metrics) object can be created directly, or via the xapp framework.
When creating directly the xAPP must supply an RMR message for the object to use;
when the framework is used to create the object, the message is created as
as part of the process.

The framework provides three constructors for the metrics instance allowing the
xAPP to supply the measurement source, the source and reporter, or to default to
using the xAPP name as both the source and reporter (see section &ital( &snr_section )
for a more detailed description of these).
The framework constructors are illustrated in figure &frame_builders.
&space

.ca start frame_builder.ca
&ex_start
  std::unique_ptr<xapp::Metrics> Alloc_metrics( );
  std::unique_ptr<xapp::Metrics> Alloc_metrics( std::string source );
  std::unique_ptr<xapp::Metrics> Alloc_metrics( std::string reporter, std::string source );
&ex_end
&export_fig( frame_builders )
&fig_cen(The framework constructors for creating an instance of the metrics object.)
&space
.ca end
.gv remain
&ifroom( 2 : frame_builder.ca )

.ca start create1.ca
&ex_start

    #include <ricxfcpp/Metrics>

    char* port = (char *) "4560";

    auto x = std::unique_ptr<Xapp>( new Xapp( port ) );
    auto reading = std::shared_ptr<xapp::Metrics>( x->Alloc_metric( ) );
&ex_end
&export_fig( metric_create_1 )
&fig_cen(Metrics instance creation using the framework. )
&space
.ca end
.gv remain
&ifroom( 2 : create1.ca )

Figures &metric_create_1 illustrates how the framework constructor can be used to
create a metrics instance.
While it is unlikely that an xAPP will create a metrics instance directly, there
are three similar constructors available.
These are prototypes are shown in figure &metrics_builders and their use is illustrated
in figure &metrics_create_2.

.ca start met_builder.ca
&ex_start
   Metrics( std::shared_ptr<xapp::Message> msg );
   Metrics( std::shared_ptr<xapp::Message> msg, std::string msource );
   Metrics( std::shared_ptr<xapp::Message> msg, std::string reporter, std::string msource );
&ex_end
&export_fig( metrics_builders )
&fig_cen(Metrics object constructors.)
&space
.ca end
.gv remain
&ifroom( 1 : met_builder.ca )

.ca start create2.ca
&ex_start
    #include <ricxfcpp/Metrics>

    char* port = (char *) "4560";

    auto x = std::unique_ptr<Xapp>( new Xapp( port ) );
    auto msg = std::shared_ptr<xapp::Message>( x->Alloc_msg( 4096 ) );
    auto reading = std::shared_ptr<xapp::Metrics>( new Metrics( msg ) );
&ex_end
&export_fig( metrics_create_2 )
&fig_cen(Direct creation of a metrics instance.)
&space
.ca end
.gv remain
&ifroom( 2 : create2.ca )

&h2(Adding Values)
Once an instance of the metrics object is created, the xAPP may push values in
preparation to sending the measurement(s) to the collector.
The &cw(Push_data())  function is used to push each key/value pair and is illustrated
in figure &push_fig.

.ca start push.ca
&ex_start
        reading->Push_data( "normal_count", (double) norm_count );
        reading->Push_data( "high_count", (double) hi_count );
        reading->Push_data( "excessive_count", (double) ex_count );
&ex_end
&export_fig( push_fig )
&fig_cen(Pushing key/value pairs into a metrics instance.)
&space
.ca end
.gv remain
&ifroom( 1 : push.ca )

&h2(Sending A Measurement Set)
After all of the measurement key/value pairs have been added to the instance, the
&cw(Send()) function can be invoked to create the necessary RMR message and send that
to the collection application.
Following the send, the key/value pairs are cleared from the instance and the
xAPP is free to start pushing values into the instance again.
The send function has the following prototype and returns &cw(true) on success and
&cw(false) if the measurements could not be sent.

&h2(Source and Reporter)
&export_var( snr_section : Source and Reporter )
The alarm collector has the understanding that a measurement might be &ital(sourced) from one
piece of equipment, or software component, but reported by another.
For auditing purposes it makes sense to distinguish these, and as such the metrics object
allows the xAPP to identify the case when the source and reporter are something other than
the xAPP which is generating the metrics message(s).

&space
The &ital(source) is the component to which the measurement applies.
This could be a network interface card counting packets, a temperature sensor, or the xAPP
itself reporting xAPP related metrics.
The &ital(reporter) is the application that is reporting the measurement(s) to the collector.

&space
By default, both reporter and source are assumed to be the xAPP, and the name is automatically
determined using the run-time supplied programme name.
Should the xAPP need to report measurements for more than one source it has the option to
create an instance for every reporter source combination, or to set the reporter and/or
source with the generation of each measurement set.
To facilitate the ability to change the source and/or the reporter without the need to create
a new metrics instance, two &ital(setter) functions are provided.
The prototypes for these are shown in figure &setter_fig.
&space

.ca start setter.ca
&ex_start
    void Set_source( std::string new_source );
    void Set_reporter( std::string new_reporter );
&ex_end
&export_fig( setter_fig )
&fig_cen( Setter functions allowing the reporter and/or source to be set after construction. )
&space
.ca end
.gv remain
&ifroom( 1 : setter.ca )