doc/src/user/metrics.im

   1 .** vim: sw=4 ts=4 et :
   2 .if false
   3 ==================================================================================
   4     Copyright (c) 2020 AT&T Intellectual Property.
   5     Copyright (c) 2020 Nokia
   6
   7    Licensed under the Apache License, Version 2.0 (the "License");
   8    you may not use this file except in compliance with the License.
   9    You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18 ==================================================================================
  19 .fi
  20
  21 .if false
  22     This imbed file contains the description of the metrics API.
  23     It should be included by the main user.xfm source.
  24 .fi
  25
  26
  27 &h1(Metrics Support)
  28 The C++ xAPP framework provides a  lightweight interface to the metrics
  29 gateway allowing the xAPP to create and send metrics updates without
  30 needing to understand the underlying message format.
  31 From the xAPP's perspective, the metrics object is created with one or
  32 more key/value measurement pairs and then is sent to the process
  33 responsible for forwarding them to the various collection processes.
  34 The following sections describe the Metrics object and the API associated
  35 with it.
  36
  37
  38 &h2(Creating The Metrics Object)
  39 The &cw(xapp:Metrics) object can be created directly, or via the xapp framework.
  40 When creating directly the xAPP must supply an RMR message for the object to use;
  41 when the framework is used to create the object, the message is created as
  42 as part of the process.
  43
  44 The framework provides three constructors for the metrics instance allowing the
  45 xAPP to supply the measurement source, the source and reporter, or to default to
  46 using the xAPP name as both the source and reporter (see section &ital( &snr_section )
  47 for a more detailed description of these).
  48 The framework constructors are illustrated in figure &frame_builders.
  49 &space
  50
  51 .ca start frame_builder.ca
  52 &ex_start
  53   std::unique_ptr<xapp::Metrics> Alloc_metrics( );
  54   std::unique_ptr<xapp::Metrics> Alloc_metrics( std::string source );
  55   std::unique_ptr<xapp::Metrics> Alloc_metrics( std::string reporter, std::string source );
  56 &ex_end
  57 &export_fig( frame_builders )
  58 &fig_cen(The framework constructors for creating an instance of the metrics object.)
  59 &space
  60 .ca end
  61 .gv remain
  62 &ifroom( 2 : frame_builder.ca )
  63
  64 .ca start create1.ca
  65 &ex_start
  66
  67     #include <ricxfcpp/Metrics>
  68
  69     char* port = (char *) "4560";
  70
  71     auto x = std::unique_ptr<Xapp>( new Xapp( port ) );
  72     auto reading = std::shared_ptr<xapp::Metrics>( x->Alloc_metric( ) );
  73 &ex_end
  74 &export_fig( metric_create_1 )
  75 &fig_cen(Metrics instance creation using the framework. )
  76 &space
  77 .ca end
  78 .gv remain
  79 &ifroom( 2 : create1.ca )
  80
  81 Figures &metric_create_1 illustrates how the framework constructor can be used to
  82 create a metrics instance.
  83 While it is unlikely that an xAPP will create a metrics instance directly, there
  84 are three similar constructors available.
  85 These are prototypes are shown in figure &metrics_builders and their use is illustrated
  86 in figure &metrics_create_2.
  87
  88 .ca start met_builder.ca
  89 &ex_start
  90    Metrics( std::shared_ptr<xapp::Message> msg );
  91    Metrics( std::shared_ptr<xapp::Message> msg, std::string msource );
  92    Metrics( std::shared_ptr<xapp::Message> msg, std::string reporter, std::string msource );
  93 &ex_end
  94 &export_fig( metrics_builders )
  95 &fig_cen(Metrics object constructors.)
  96 &space
  97 .ca end
  98 .gv remain
  99 &ifroom( 1 : met_builder.ca )
 100
 101 .ca start create2.ca
 102 &ex_start
 103     #include <ricxfcpp/Metrics>
 104
 105     char* port = (char *) "4560";
 106
 107     auto x = std::unique_ptr<Xapp>( new Xapp( port ) );
 108     auto msg = std::shared_ptr<xapp::Message>( x->Alloc_msg( 4096 ) );
 109     auto reading = std::shared_ptr<xapp::Metrics>( new Metrics( msg ) );
 110 &ex_end
 111 &export_fig( metrics_create_2 )
 112 &fig_cen(Direct creation of a metrics instance.)
 113 &space
 114 .ca end
 115 .gv remain
 116 &ifroom( 2 : create2.ca )
 117
 118 &h2(Adding Values)
 119 Once an instance of the metrics object is created, the xAPP may push values in
 120 preparation to sending the measurement(s) to the collector.
 121 The &cw(Push_data())  function is used to push each key/value pair and is illustrated
 122 in figure &push_fig.
 123
 124 .ca start push.ca
 125 &ex_start
 126         reading->Push_data( "normal_count", (double) norm_count );
 127         reading->Push_data( "high_count", (double) hi_count );
 128         reading->Push_data( "excessive_count", (double) ex_count );
 129 &ex_end
 130 &export_fig( push_fig )
 131 &fig_cen(Pushing key/value pairs into a metrics instance.)
 132 &space
 133 .ca end
 134 .gv remain
 135 &ifroom( 1 : push.ca )
 136
 137 &h2(Sending A Measurement Set)
 138 After all of the measurement key/value pairs have been added to the instance, the
 139 &cw(Send()) function can be invoked to create the necessary RMR message and send that
 140 to the collection application.
 141 Following the send, the key/value pairs are cleared from the instance and the
 142 xAPP is free to start pushing values into the instance again.
 143 The send function has the following prototype and returns &cw(true) on success and
 144 &cw(false) if the measurements could not be sent.
 145
 146 &h2(Source and Reporter)
 147 &export_var( snr_section : Source and Reporter )
 148 The alarm collector has the understanding that a measurement might be &ital(sourced) from one
 149 piece of equipment, or software component, but reported by another.
 150 For auditing purposes it makes sense to distinguish these, and as such the metrics object
 151 allows the xAPP to identify the case when the source and reporter are something other than
 152 the xAPP which is generating the metrics message(s).
 153
 154 &space
 155 The &ital(source) is the component to which the measurement applies.
 156 This could be a network interface card counting packets, a temperature sensor, or the xAPP
 157 itself reporting xAPP related metrics.
 158 The &ital(reporter) is the application that is reporting the measurement(s) to the collector.
 159
 160 &space
 161 By default, both reporter and source are assumed to be the xAPP, and the name is automatically
 162 determined using the run-time supplied programme name.
 163 Should the xAPP need to report measurements for more than one source it has the option to
 164 create an instance for every reporter source combination, or to set the reporter and/or
 165 source with the generation of each measurement set.
 166 To facilitate the ability to change the source and/or the reporter without the need to create
 167 a new metrics instance, two &ital(setter) functions are provided.
 168 The prototypes for these are shown in figure &setter_fig.
 169 &space
 170
 171 .ca start setter.ca
 172 &ex_start
 173     void Set_source( std::string new_source );
 174     void Set_reporter( std::string new_reporter );
 175 &ex_end
 176 &export_fig( setter_fig )
 177 &fig_cen( Setter functions allowing the reporter and/or source to be set after construction. )
 178 &space
 179 .ca end
 180 .gv remain
 181 &ifroom( 1 : setter.ca )