diff options
Diffstat (limited to 'veslibrary/ves_clibrary/evel/evel-library/code/evel_library/quickstart.md')
| -rw-r--r-- | veslibrary/ves_clibrary/evel/evel-library/code/evel_library/quickstart.md | 445 |
1 files changed, 445 insertions, 0 deletions
diff --git a/veslibrary/ves_clibrary/evel/evel-library/code/evel_library/quickstart.md b/veslibrary/ves_clibrary/evel/evel-library/code/evel_library/quickstart.md new file mode 100644 index 0000000..1c735cc --- /dev/null +++ b/veslibrary/ves_clibrary/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 |