vnfs/VESreporting_vFW5.0_DANOS/evel/evel-library/code/evel_library/readme.md

   1 # EVEL Library Overview {#mainpage}
   2
   3 # Introduction
   4
   5 The ECOMP Vendor Event Listener ("EVEL") library encapsulates the use of
   6 AT&T's JSON API to the collector function within the ECOMP infrastructure.
   7
   8 As such, it provides a reference implementation of the EVEL JSON API which
   9 can either be directly as part of a project or can be used to inform the
  10 independent implementation of an equivalent binding to the API in another
  11 development environment.
  12
  13 This section provides an overview of the library and how it is integrated
  14 into the target application.  If all you want is a set of instructions to
  15 get you started, the @ref quickstart "Quick Start" section is for you.  If
  16 you want a more in-depth understanding of the _EVEL Library_ then this section
  17 provides an overview and then you can read the detailed API documentation for
  18 each function. The documentation for evel.h is a good starting point, since
  19 that defines the public API of the _EVEL Library_.
  20
  21 # Library Structure
  22
  23 The API is designed to be used on multi-process platforms where each process
  24 may be multi-threaded.  Each process using this library will create an
  25 independent HTTP client (using libcURL).  Each process will have a single
  26 thread running the HTTP client but that thread receives work on a
  27 ring-buffer from however may threads are required to implement the function.
  28
  29 **Note**: libcurl imposes a constraint that it is initialized before
  30 the process starts multi-threaded operation.
  31
  32 # Typical Usage
  33
  34 The library is designed to be very straightforward to use and lightweight to
  35 integrate into projects. The only serious external dependency is on libcURL.
  36
  37 The supplied Makefile produces a single library **libevel.so** or
  38 **libevel.a** which your application needs to be linked against.
  39
  40 Each process within the application which wants to generate events needs to
  41 call ::evel_initialize at the start of day (observing the above warning
  42 about not being MT safe at this stage.)   The initialization specifies the
  43 details of where the API is located.  Management of configuration is the
  44 responsibility of the client.
  45
  46 Once initialized, and now MT-safe, there are factory functions to produce
  47 new events:
  48 - Faults  - ::evel_new_fault
  49 - Measurements - ::evel_new_measurement
  50 - Report - ::evel_new_report
  51 - State Change - ::evel_new_state_change
  52 - Syslog - ::evel_new_syslog
  53 - Other - ::evel_new_other
  54 - Mobile Flow - ::evel_new_mobile_flow
  55
  56 There is also a factory function ::evel_new_mobile_gtp_flow_metrics to create
  57 the parameter gtp_per_flow_metrics, which is then configured and passed to the
  58 ::evel_new_mobile_flow factory function.
  59
  60 The event structures are initialized with mandatory fields at the point of
  61 creation and optional fields may be added thereafter.  Once set, values in
  62 the structures are immutable.
  63
  64 Once the event is prepared, it may be posted, using ::evel_post_event,  at
  65 which point the calling thread relinquishes all responsibility for the
  66 event.  It will be freed once successfully or unsuccessfully posted to the
  67 API.  If, for any reason, you change your mind and don't want to post a
  68 created event, it must be destroyed with ::evel_free_event.
  69
  70 Finally, at the end of day, the library can be terminated cleanly by calling
  71 ::evel_terminate.
  72
  73 ## Example Code
  74
  75 The following fragment illustrates the above usage:
  76
  77 ```C
  78
  79 EVEL_ERR_CODES evel_initialize(const char * const fqdn,
  80                                int port,
  81                                const char * const bakup_fqdn,
  82                                int bakup_port,
  83                                const char * const path,
  84                                const char * const topic,
  85                                int ring_buf_size,
  86                                int secure,
  87                                const char * const cert_file_path,
  88                                const char * const key_file_path,
  89                                const char * const ca_info,
  90                                const char * const ca_file_path,
  91                                long verify_peer,
  92                                long verify_host,
  93                                const char * const username,
  94                                const char * const password,
  95                                const char * const bakup_username,
  96                                const char * const bakup_password,
  97                                const char * const source_ip,
  98                                const char * const bakup_source_ip,
  99                                EVEL_SOURCE_TYPES source_type,
 100                                const char * const role,
 101                                int verbosity
 102                                )  {
 103     fprintf(stderr, "Failed to initialize the EVEL library!!!");
 104     exit(-1);
 105   }
 106
 107   ...
 108
 109   fault = evel_new_fault("My alarm condition",
 110                          "It broke very badly",
 111                          EVEL_PRIORITY_NORMAL,
 112                          EVEL_SEVERITY_MAJOR);
 113   if (fault != NULL)
 114   {
 115     evel_fault_type_set(fault, "Bad things happen...");
 116     evel_fault_interface_set(fault, "My Interface Card");
 117     evel_fault_addl_info_add(fault, "name1", "value1");
 118     evel_fault_addl_info_add(fault, "name2", "value2");
 119     evel_rc = evel_post_event((EVENT_HEADER *)fault);
 120     if (evel_rc != EVEL_SUCCESS)
 121     {
 122       EVEL_ERROR("Post failed %d (%s)", evel_rc, evel_error_string());
 123     }
 124   }
 125
 126 ```
 127
 128 The public API to the library is defined in evel.h.  The internal APIs
 129 within library are defined in separate headers (<em>e.g.</em>
 130 evel_internal.h), but these should not need to be included by the code
 131 using the library.
 132
 133 # Example Application
 134
 135 A simple command-line application to generate events is provided as part of
 136 the source package (the above code fragment is taken from that application).
 137
 138 The following illustrates its operation to a co-located "test-collector":
 139 ```
 140 $ ./evel_demo --fqdn 127.0.0.1 --port 30000 --path vendor_event_listener --topic example_vnf --verbose
 141 ./evel_demo built Feb 26 2016 18:14:48
 142 * About to connect() to 169.254.169.254 port 80 (#0)
 143 *   Trying 169.254.169.254... * Timeout
 144 * connect() timed out!
 145 * Closing connection #0
 146 * About to connect() to 127.0.0.1 port 30000 (#0)
 147 *   Trying 127.0.0.1... * connected
 148 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
 149 * Server auth using Basic with user 'Alice'
 150 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
 151 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
 152 User-Agent: libcurl-agent/1.0
 153 Host: 127.0.0.1:30000
 154 Accept: */*
 155 Content-type: application/json
 156 Content-Length: 510
 157
 158 * HTTP 1.0, assume close after body
 159 < HTTP/1.0 204 No Content
 160 < Date: Fri, 04 Mar 2016 15:37:22 GMT
 161 < Server: WSGIServer/0.1 Python/2.6.6
 162 <
 163 * Closing connection #0
 164 * About to connect() to 127.0.0.1 port 30000 (#0)
 165 *   Trying 127.0.0.1... * connected
 166 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
 167 * Server auth using Basic with user 'Alice'
 168 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
 169 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
 170 User-Agent: libcurl-agent/1.0
 171 Host: 127.0.0.1:30000
 172 Accept: */*
 173 Content-type: application/json
 174 Content-Length: 865
 175
 176 * HTTP 1.0, assume close after body
 177 < HTTP/1.0 204 No Content
 178 < Date: Fri, 04 Mar 2016 15:37:22 GMT
 179 < Server: WSGIServer/0.1 Python/2.6.6
 180 <
 181 * Closing connection #0
 182 * About to connect() to 127.0.0.1 port 30000 (#0)
 183 *   Trying 127.0.0.1... * connected
 184 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
 185 * Server auth using Basic with user 'Alice'
 186 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
 187 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
 188 User-Agent: libcurl-agent/1.0
 189 Host: 127.0.0.1:30000
 190 Accept: */*
 191 Content-type: application/json
 192 Content-Length: 2325
 193
 194 * HTTP 1.0, assume close after body
 195 < HTTP/1.0 204 No Content
 196 < Date: Fri, 04 Mar 2016 15:37:22 GMT
 197 < Server: WSGIServer/0.1 Python/2.6.6
 198 <
 199 * Closing connection #0
 200 ^C
 201
 202 Interrupted - quitting!
 203 $
 204 ```
 205
 206 # Restrictions and Limitations
 207
 208 ## Constraint Validation
 209
 210 The _EVEL Library_ has been designed to be production-safe code with the
 211 emphasis at this stage being in correctness of operation rather than
 212 raw performance.
 213
 214 The API tries to check as much information as possible to avoid misuse and
 215 will **assert()** if constraints are not satisfied.  This is likely to lead
 216 to the rapid discovery of coding errors by programmers, but does mean that
 217 the application can fail abruptly if the library is misused in any way.
 218
 219 ## Performance
 220
 221 The default Makefile avoids aggressive optimizations so that any core-files
 222 are easy to interpret.  Production code should use greater optimization
 223 levels.
 224
 225 As described above, the HTTP client is single threaded and will run all
 226 transactions synchronously.  As transactions are serialized, a client that
 227 generates a lot of events will be paced by the round-trip time.
 228
 229 It would be a straightforward enhancement to use the multi-thread API into
 230 libcurl and use a pool of client threads to run transactions in parallel if
 231 this ever became a bottleneck.
 232
 233 ## Logging
 234
 235 The initialization of the library includes the log verbosity.  The verbose
 236 operation makes the library very chatty so syslog may get rather clogged
 237 with detailed diagnostics.  It is possible to configure syslog to put these
 238 events into a separate file.  A trivial syslog.conf file would be:
 239
 240 ```
 241
 242 # Log all user messages so debug information is captured.
 243
 244 user.*      /var/log/debug
 245 ```
 246
 247 If verbose logging is enabled, the cURL library will generate information
 248 about the HTTP operations on **stdout**.
 249