Merge "VES5.0 development changes not for test"

1 files changed, 445 insertions, 0 deletions

diff --git a/VES5.0/evel/evel-library/code/evel_library/quickstart.md b/VES5.0/evel/evel-library/code/evel_library/quickstart.md
new file mode 100644
index 00000000..1c735cc4
--- /dev/null
+++ b/VES5.0/evel/evel-library/code/evel_library/quickstart.md
@@ -0,0 +1,445 @@
+# Quick Start Guide {#quickstart}
+
+# Introduction {#qs_intro}
+
+This Quick-Start section describes how to:
+
+  *  Install and compile the supplied library code
+  *  Integrate an existing project to use the EVEL library
+  
+# Installation {#qs_install}
+
+The library is supplied as a source-code compressed-tar file. It is 
+straightforward to install and build to integrate with an existing or new
+development project.
+
+## Unpack the Source Code {#qs_unpack}
+
+The file should unpacked into your development environment:
+```
+$ mkdir evel
+$ cd evel
+$ tar zxvf evel-library-package.tgz
+```
+### Satisfy Dependencies {#qs_depend}
+
+Note that all commands in this section are based on CentOS package management
+tools and you may need to substitute the appropriate tools/packages for your
+distribution, for example `apt-get` for Ubuntu.
+
+Ensure that GCC development tools are available.
+
+```
+$ sudo yum install gcc
+```
+Additionally, the library has a dependency on the cURL library, so you'll need 
+the development tools for libCurl installed. (At runtime, only the runtime 
+library is required, of course.)
+
+```
+$ sudo yum install libcurl-devel
+```
+If you wish to make the project documentation, then Doxygen and Graphviz are
+required. (Again, this is only in the development environment, not the runtime 
+environment!)
+
+```
+$ sudo yum install doxygen graphviz
+```
+
+Note that some distributions have quite old versions of Doxygen by default and 
+it may be necessary to install a later version to use all the features.
+
+If you want to build PDFs from the LaTeX you will need a texlive install.
+
+```
+$ sudo yum install texlive
+```
+
+### Test Build {#qs_build}
+Make sure that the library makes cleanly:
+
+```
+$ cd bldjobs
+$ make
+Making dependency file evel_unit.d for evel_unit.c
+Making dependency file evel_test_control.d for evel_test_control.c
+Making dependency file evel_demo.d for evel_demo.c
+Making dependency file jsmn.d for jsmn.c
+Making dependency file evel_logging.d for evel_logging.c
+Making dependency file evel_event_mgr.d for evel_event_mgr.c
+Making dependency file evel_internal_event.d for evel_internal_event.c
+Making dependency file evel_throttle.d for evel_throttle.c
+Making dependency file evel_syslog.d for evel_syslog.c
+Making dependency file evel_strings.d for evel_strings.c
+Making dependency file evel_state_change.d for evel_state_change.c
+Making dependency file evel_scaling_measurement.d for evel_scaling_measurement.c
+Making dependency file evel_signaling.d for evel_signaling.c
+Making dependency file evel_service.d for evel_service.c
+Making dependency file evel_reporting_measurement.d for evel_reporting_measurement.c
+Making dependency file evel_json_buffer.d for evel_json_buffer.c
+Making dependency file evel_other.d for evel_other.c
+Making dependency file evel_option.d for evel_option.c
+Making dependency file evel_mobile_flow.d for evel_mobile_flow.c
+Making dependency file evel_fault.d for evel_fault.c
+Making dependency file evel_event.d for evel_event.c
+Making dependency file double_list.d for double_list.c
+Making dependency file ring_buffer.d for ring_buffer.c
+Making dependency file metadata.d for metadata.c
+Making dependency file evel.d for evel.c
+Making evel.o from evel.c
+Making metadata.o from metadata.c
+Making ring_buffer.o from ring_buffer.c
+Making double_list.o from double_list.c
+Making evel_event.o from evel_event.c
+Making evel_fault.o from evel_fault.c
+Making evel_mobile_flow.o from evel_mobile_flow.c
+Making evel_option.o from evel_option.c
+Making evel_other.o from evel_other.c
+Making evel_json_buffer.o from evel_json_buffer.c
+Making evel_reporting_measurement.o from evel_reporting_measurement.c
+Making evel_service.o from evel_service.c
+Making evel_signaling.o from evel_signaling.c
+Making evel_scaling_measurement.o from evel_scaling_measurement.c
+Making evel_state_change.o from evel_state_change.c
+Making evel_strings.o from evel_strings.c
+Making evel_syslog.o from evel_syslog.c
+Making evel_throttle.o from evel_throttle.c
+Making evel_internal_event.o from evel_internal_event.c
+Making evel_event_mgr.o from evel_event_mgr.c
+Making evel_logging.o from evel_logging.c
+Making jsmn.o from jsmn.c
+Linking API Shared Library
+Linking API Static Library
+Making evel_demo.o from evel_demo.c
+Making evel_test_control.o from evel_test_control.c
+Linking EVEL demo
+Making EVEL training
+$
+``` 
+You should now be able to run the demo CLI application.  Since it will want to
+dynamically link to the library that you've just made, you will need to set 
+your `LD_LIBRARY_PATH` appropriately first. Make sure that you specify
+your actual directory paths correctly in the following:
+
+```
+$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/centos/evel/libs/x86_64
+$ ../output/x86_64/evel_demo
+evel_demo [--help]
+          --fqdn <domain>
+          --port <port_number>
+          [--path <path>]
+          [--topic <topic>]
+          [--username <username>]
+          [--password <password>]
+          [--https]
+          [--cycles <cycles>]
+          [--nothrott]
+
+Demonstrate use of the ECOMP Vendor Event Listener API.
+
+  -h         Display this usage message.
+  --help
+
+  -f         The FQDN or IP address to the RESTful API.
+  --fqdn
+
+  -n         The port number the RESTful API.
+  --port
+
+  -p         The optional path prefix to the RESTful API.
+  --path
+
+  -t         The optional topic part of the RESTful API.
+  --topic
+
+  -u         The optional username for basic authentication of requests.
+  --username
+
+  -w         The optional password for basic authentication of requests.
+  --password
+
+  -s         Use HTTPS rather than HTTP for the transport.
+  --https
+
+  -c         Loop <cycles> times round the main loop.  Default = 1.
+  --cycles
+
+  -v         Generate much chattier logs.
+  --verbose
+
+  -x         Exclude throttling commands from demonstration.
+  --nothrott
+
+$
+```
+Assuming that all worked as expected, you are ready to start integrating with 
+your application. It probably makes sense to make the LD_LIBRARY_PATH change
+above permanent by incorporating it into your `.bash_profile` file.
+
+### Project Documentation {#qs_build_docs}
+
+The source comes with its own documentation included. The documentation can be
+built using the `docs` target in the Makefile. By default this builds HTML
+and LaTeX documentation, the latter being used to prepare PDFs.
+
+To make the documentation:
+```
+$ cd bldjobs
+$ make docs
+Cleaning docs...
+Making Doxygen documentation
+$ 
+```
+
+There is a make target that is intended to install the documentation on a
+"team server" - it will need adaptation for your team's environment - see the 
+`docs_install` target in the Makefile:
+
+```
+$ make docs_install
+Cleaning docs...
+Making Doxygen documentation
+Copying docs to team web-server...
+Enter passphrase for key '/data/home/.ssh/id_rsa':
+annotated.html                           100% 8088     7.9KB/s   00:00    
+arrowdown.png                            100%  246     0.2KB/s   00:00    
+arrowright.png                           100%  229     0.2KB/s   00:00    
+  ...
+$
+```
+
+# Project Integration {#qs_integrate}
+
+There are two key steps to the integration which have to be undertaken:
+
+  * Initialization/Termination of the library.
+  * Creation & posting of individual events.
+  
+Additionally, it may be necessary to consider changes to the EVEL library's
+source code if assumptions made by the library are either not satisfied or 
+inconvenient.  In particular:
+
+  * If the project already uses libcurl then the global initialization of the
+    library should be removed from the _EVEL Library_.
+  * The _EVEL Library_ uses `syslog` for event logging. If the project uses a
+    different event logging process, then EVEL's event logging macros should be
+    rewritten appropriately.
+
+These steps are considered in the [Normal Use](@ref qs_normal_use) and 
+[EVEL Adaptation](@ref qs_adaptation) sections below.
+
+## Normal Use         {#qs_normal_use}
+
+The _EVEL Library_ should be integrated with your project at a per-process 
+level: each process is an independent client of the ECOMP Vendor Event Listener
+API.
+
+### Initialization {#qs_initialize}
+
+The _EVEL Library_ should be initialized before the process becomes 
+multi-threaded. This constraint arises from the use of libcurl which imposes 
+the constraint that initialization occurs before the system is multi-threaded.
+This is described in more detail in the libcurl documentation for the
+[curl_global_init](https://curl.haxx.se/libcurl/c/curl_global_init.html) 
+function.
+
+Initialization stores configuration of the Vendor Event Listener API's details,
+such as the FQDN or IP address of the service, so the initializing process must
+have either extracted this information from its configuration or have this 
+information "hard-wired" into the application, so that it is available at the 
+point the `evel_initialize()` function is called:
+
+```C
+  #include "evel.h"
+  ...
+  if (evel_initialize(api_fqdn,
+                      api_port,
+                      api_path,
+                      api_topic,
+                      api_secure,
+                      "Alice",
+                      "This isn't very secure!",
+                      EVEL_SOURCE_VIRTUAL_MACHINE,
+                      "EVEL demo client",
+                      verbose_mode))
+  {
+    fprintf(stderr, "Failed to initialize the EVEL library!!!");
+    exit(-1);
+  }
+  ...
+```
+Once initialization has occurred successfully, the application may raise events
+and may also use the logging functions such as EVEL_INFO().
+
+Initialization is entirely local (there is no interaction with the service) so
+it is very unlikely to fail, unless the application environment is seriously 
+degraded.
+
+### Event Generation {#qs_generate}
+
+Generating events is a two stage process:
+
+  1.  Firstly, the _EVEL Library_ is called to allocate an event of the correct
+      type. 
+    * If this is successful, the caller is given a pointer to the event.
+    * All mandatory fields on the event are provided to this factory function
+      and are thereafter immutable.
+    * The application may add any necessary optional fields to the event, using
+      the pointer previously returned.
+  2.  The event is sent to the JSON API using the evel_post_event() function.
+    * At this point, the application relinquishes all responsibility for the 
+      event:
+      * It will be posted to the JSON API, if possible.
+      * Whether or not the posting is successful, the memory used will be 
+        freed.
+        
+In practice this looks like:
+
+```C
+  #include "evel.h"
+  ...
+
+  /***************************************************************************/
+  /* Create a new Fault object, setting mandatory fields as we do so...      */
+  /***************************************************************************/
+  fault = evel_new_fault("My alarm condition",
+                         "It broke very badly",
+                         EVEL_PRIORITY_NORMAL,
+                         EVEL_SEVERITY_MAJOR);
+  if (fault != NULL)
+  {
+    /*************************************************************************/
+    /* We have a Fault object - add some optional fields to it...            */
+    /*************************************************************************/
+    evel_fault_type_set(fault, "Bad things happen...");
+    evel_fault_interface_set(fault, "My Interface Card");
+    evel_fault_addl_info_add(fault, "name1", "value1");
+    evel_fault_addl_info_add(fault, "name2", "value2");
+    
+    /*************************************************************************/
+    /* Finally, post the Fault.  In practice this will only ever fail if     */
+    /* local ring-buffer is full because of event overload.                  */
+    /*************************************************************************/
+    evel_rc = evel_post_event((EVENT_HEADER *)fault);
+    if (evel_rc != EVEL_SUCCESS)
+    {
+      EVEL_ERROR("Post failed %d (%s)", evel_rc, evel_error_string());
+    }
+  }
+  ...
+```
+### Event Types {#qs_event_types}
+
+The _EVEL Library_ supports the following types of events:
+
+  1.  Faults
+  
+      These represent the **fault** domain in the event schema.
+      
+  2.  Measurements
+  
+      These represent the **measurementsForVfScaling** domain in the event
+      schema.
+      
+  3.  Reports
+  
+      This is an experimental type, designed to allow VNFs to report 
+      application-level statistics unencumbered with platform measurements.
+      The formal AT&T schema has been updated to include this experimental
+      type as **measurementsForVfReporting**. 
+
+  4.  Mobile Flow
+
+      These represent the **mobileFlow** domain in the event schema.
+
+  5.  Other
+
+      These represent the **other** domain in the event schema.
+
+  6.  Service Events
+
+      These represent the **serviceEvents** domain in the event schema.
+
+  7.  Signaling
+
+      These represent the **signaling** domain in the event schema.
+
+  8.  State Change
+
+      These represent the **stateChange** domain in the event schema.
+
+  9.  Syslog
+
+      These represent the **syslog** domain in the event schema.
+
+### Throttling {#qs_throttling}
+
+The _EVEL library_ supports the following command types as defined in the JSON API:
+
+  1.  commandType: throttlingSpecification
+
+    This is handled internally by the EVEL library, which stores the provided
+    throttling specification internally and applies it to all subsequent events.
+
+  2. commandType: provideThrottlingState
+
+    This is handled internally by the EVEL library, which returns the current
+    throttling specification for each domain.
+
+  3. commandType: measurementIntervalChange
+
+    This is handled by the EVEL library, which makes the latest measurement
+    interval available via the ::evel_get_measurement_interval function.
+    The application is responsible for checking and adhering to the latest
+    provided interval.
+
+### Termination {#qs_termination}
+
+Termination of the _EVEL Library_ is swift and brutal!  Events in the buffer
+at the time are "dropped on the floor" rather than waiting for the buffer to 
+deplete first.
+
+```C
+  #include "evel.h"
+  ...
+  
+  /***************************************************************************/
+  /* Shutdown the library.                                                   */
+  /***************************************************************************/
+  evel_terminate();
+  
+  ...
+``` 
+
+## EVEL Adaptation       {#qs_adaptation}
+
+The _EVEL Library_ is relatively simple and should be easy to adapt into other
+project environments.
+
+### LibcURL Lifecycle
+
+There are two circumstances where initialization of libcurl may be required:
+
+  1.  If libcurl is used by the project already, and therefore already takes 
+      responsibility of its initialization, then the libcurl initialization and 
+      termination functions should be removed from evel_initialize() and 
+      evel_terminate() respectively.
+  2.  If the project is unable to satisfy the constraint that libcurl 
+      initialization takes place in a single-threaded environment at the point
+      that the _EVEL Library_ can be initialized (for example, if MT code is 
+      necessary to read the configuration parameters required for 
+      _EVEL Library_ initialization) then it may be necessary to extract the 
+      libcurl functions and call them separately, earlier in the program's 
+      operation.
+      
+### Event Logging
+
+The _EVEL Library_ uses `syslog` for logging.  If this is inappropriate then
+the log_debug() and log_initialize() functions should be rewritten accordingly.
+
+**Note**: it would be a really bad idea to use the _EVEL Library_ itself for this 
+logging function. 
+[Turtles all the way down...](https://en.wikipedia.org/wiki/Turtles_all_the_way_down)
+  
+  
\ No newline at end of file