1 # EVEL Library Overview {#mainpage}
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.
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.
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_.
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.
29 **Note**: libcurl imposes a constraint that it is initialized before
30 the process starts multi-threaded operation.
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.
37 The supplied Makefile produces a single library **libevel.so** or
38 **libevel.a** which your application needs to be linked against.
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.
46 Once initialized, and now MT-safe, there are factory functions to produce
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
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.
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.
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.
70 Finally, at the end of day, the library can be terminated cleanly by calling
75 The following fragment illustrates the above usage:
79 if (evel_initialize(api_fqdn,
85 "This isn't very secure!",
86 EVEL_SOURCE_VIRTUAL_MACHINE,
90 fprintf(stderr, "Failed to initialize the EVEL library!!!");
96 fault = evel_new_fault("My alarm condition",
97 "It broke very badly",
102 evel_fault_type_set(fault, "Bad things happen...");
103 evel_fault_interface_set(fault, "My Interface Card");
104 evel_fault_addl_info_add(fault, "name1", "value1");
105 evel_fault_addl_info_add(fault, "name2", "value2");
106 evel_rc = evel_post_event((EVENT_HEADER *)fault);
107 if (evel_rc != EVEL_SUCCESS)
109 EVEL_ERROR("Post failed %d (%s)", evel_rc, evel_error_string());
115 The public API to the library is defined in evel.h. The internal APIs
116 within library are defined in separate headers (<em>e.g.</em>
117 evel_internal.h), but these should not need to be included by the code
120 # Example Application
122 A simple command-line application to generate events is provided as part of
123 the source package (the above code fragment is taken from that application).
125 The following illustrates its operation to a co-located "test-collector":
127 $ ./evel_demo --fqdn 127.0.0.1 --port 30000 --path vendor_event_listener --topic example_vnf --verbose
128 ./evel_demo built Feb 26 2016 18:14:48
129 * About to connect() to 169.254.169.254 port 80 (#0)
130 * Trying 169.254.169.254... * Timeout
131 * connect() timed out!
132 * Closing connection #0
133 * About to connect() to 127.0.0.1 port 30000 (#0)
134 * Trying 127.0.0.1... * connected
135 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
136 * Server auth using Basic with user 'Alice'
137 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
138 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
139 User-Agent: libcurl-agent/1.0
140 Host: 127.0.0.1:30000
142 Content-type: application/json
145 * HTTP 1.0, assume close after body
146 < HTTP/1.0 204 No Content
147 < Date: Fri, 04 Mar 2016 15:37:22 GMT
148 < Server: WSGIServer/0.1 Python/2.6.6
150 * Closing connection #0
151 * About to connect() to 127.0.0.1 port 30000 (#0)
152 * Trying 127.0.0.1... * connected
153 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
154 * Server auth using Basic with user 'Alice'
155 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
156 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
157 User-Agent: libcurl-agent/1.0
158 Host: 127.0.0.1:30000
160 Content-type: application/json
163 * HTTP 1.0, assume close after body
164 < HTTP/1.0 204 No Content
165 < Date: Fri, 04 Mar 2016 15:37:22 GMT
166 < Server: WSGIServer/0.1 Python/2.6.6
168 * Closing connection #0
169 * About to connect() to 127.0.0.1 port 30000 (#0)
170 * Trying 127.0.0.1... * connected
171 * Connected to 127.0.0.1 (127.0.0.1) port 30000 (#0)
172 * Server auth using Basic with user 'Alice'
173 > POST /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1
174 Authorization: Basic QWxpY2U6VGhpcyBpc24ndCB2ZXJ5IHNlY3VyZSE=
175 User-Agent: libcurl-agent/1.0
176 Host: 127.0.0.1:30000
178 Content-type: application/json
181 * HTTP 1.0, assume close after body
182 < HTTP/1.0 204 No Content
183 < Date: Fri, 04 Mar 2016 15:37:22 GMT
184 < Server: WSGIServer/0.1 Python/2.6.6
186 * Closing connection #0
189 Interrupted - quitting!
193 # Restrictions and Limitations
195 ## Constraint Validation
197 The _EVEL Library_ has been designed to be production-safe code with the
198 emphasis at this stage being in correctness of operation rather than
201 The API tries to check as much information as possible to avoid misuse and
202 will **assert()** if constraints are not satisfied. This is likely to lead
203 to the rapid discovery of coding errors by programmers, but does mean that
204 the application can fail abruptly if the library is misused in any way.
208 The default Makefile avoids aggressive optimizations so that any core-files
209 are easy to interpret. Production code should use greater optimization
212 As described above, the HTTP client is single threaded and will run all
213 transactions synchronously. As transactions are serialized, a client that
214 generates a lot of events will be paced by the round-trip time.
216 It would be a straightforward enhancement to use the multi-thread API into
217 libcurl and use a pool of client threads to run transactions in parallel if
218 this ever became a bottleneck.
222 The initialization of the library includes the log verbosity. The verbose
223 operation makes the library very chatty so syslog may get rather clogged
224 with detailed diagnostics. It is possible to configure syslog to put these
225 events into a separate file. A trivial syslog.conf file would be:
229 # Log all user messages so debug information is captured.
231 user.* /var/log/debug
234 If verbose logging is enabled, the cURL library will generate information
235 about the HTTP operations on **stdout**.