diff options
Diffstat (limited to 'VES5.0/evel/evel-library/code/evel_library/quickstart.md')
| -rw-r--r-- | VES5.0/evel/evel-library/code/evel_library/quickstart.md | 445 |
1 files changed, 0 insertions, 445 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 deleted file mode 100644 index 1c735cc4..00000000 --- a/VES5.0/evel/evel-library/code/evel_library/quickstart.md +++ /dev/null @@ -1,445 +0,0 @@ -# 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 |