.** 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 Alloc_metrics( ); std::unique_ptr Alloc_metrics( std::string source ); std::unique_ptr 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 char* port = (char *) "4560"; auto x = std::unique_ptr( new Xapp( port ) ); auto reading = std::shared_ptr( 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 msg ); Metrics( std::shared_ptr msg, std::string msource ); Metrics( std::shared_ptr 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 char* port = (char *) "4560"; auto x = std::unique_ptr( new Xapp( port ) ); auto msg = std::shared_ptr( x->Alloc_msg( 4096 ) ); auto reading = std::shared_ptr( 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 )