From 2ba9dcf408d5f861738356dfb43c28a803fcd7fc Mon Sep 17 00:00:00 2001 From: John DeNisco Date: Thu, 23 Aug 2018 14:04:22 -0400 Subject: docs: Finish event logger, viewer and cleanup. Change-Id: I3de038439bf0ab5755777c0f4930aec0514f5b63 Signed-off-by: John DeNisco --- docs/gettingstarted/developers/infrastructure.md | 108 ----------------------- 1 file changed, 108 deletions(-) (limited to 'docs/gettingstarted/developers/infrastructure.md') diff --git a/docs/gettingstarted/developers/infrastructure.md b/docs/gettingstarted/developers/infrastructure.md index 688c42133ed..0361a632c37 100644 --- a/docs/gettingstarted/developers/infrastructure.md +++ b/docs/gettingstarted/developers/infrastructure.md @@ -220,111 +220,3 @@ and unserialize complex data structures. The underlying primitive serialize/unserialize functions use network byte-order, so there are no structural issues serializing on a little-endian host and unserializing on a big-endian host. - -Event-logger, graphical event log viewer ----------------------------------------- - -The vppinfra event logger provides very lightweight (sub-100ns) -precisely time-stamped event-logging services. See -./src/vppinfra/{elog.c, elog.h} - -Serialization support makes it easy to save and ultimately to combine a -set of event logs. In a distributed system running NTP over a local LAN, -we find that event logs collected from multiple system elements can be -combined with a temporal uncertainty no worse than 50us. - -A typical event definition and logging call looks like this: - -```c - ELOG_TYPE_DECLARE (e) = - { - .format = "tx-msg: stream %d local seq %d attempt %d", - .format_args = "i4i4i4", - }; - struct { u32 stream_id, local_sequence, retry_count; } * ed; - ed = ELOG_DATA (m->elog_main, e); - ed->stream_id = stream_id; - ed->local_sequence = local_sequence; - ed->retry_count = retry_count; -``` - -The ELOG\_DATA macro returns a pointer to 20 bytes worth of arbitrary -event data, to be formatted (offline, not at runtime) as described by -format\_args. Aside from obvious integer formats, the CLIB event logger -provides a couple of interesting additions. The "t4" format -pretty-prints enumerated values: - -```c - ELOG_TYPE_DECLARE (e) = - { - .format = "get_or_create: %s", - .format_args = "t4", - .n_enum_strings = 2, - .enum_strings = { "old", "new", }, - }; -``` - -The "t" format specifier indicates that the corresponding datum is an -index in the event's set of enumerated strings, as shown in the previous -event type definition. - -The “T” format specifier indicates that the corresponding datum is an -index in the event log’s string heap. This allows the programmer to emit -arbitrary formatted strings. One often combines this facility with a -hash table to keep the event-log string heap from growing arbitrarily -large. - -Noting the 20-octet limit per-log-entry data field, the event log -formatter supports arbitrary combinations of these data types. As in: -the ".format" field may contain one or more instances of the following: - -- i1 - 8-bit unsigned integer -- i2 - 16-bit unsigned integer -- i4 - 32-bit unsigned integer -- i8 - 64-bit unsigned integer -- f4 - float -- f8 - double -- s - NULL-terminated string - be careful -- sN - N-byte character array -- t1,2,4 - per-event enumeration ID -- T4 - Event-log string table offset - -The vpp engine event log is thread-safe, and is shared by all threads. -Take care not to serialize the computation. Although the event-logger is -about as fast as practicable, it's not appropriate for per-packet use in -hard-core data plane code. It's most appropriate for capturing rare -events - link up-down events, specific control-plane events and so -forth. - -The vpp engine has several debug CLI commands for manipulating its event -log: - -``` - vpp# event-logger clear - vpp# event-logger save # for security, writes into /tmp/. - # must not contain '.' or '/' characters - vpp# show event-logger [all] [] # display the event log - # by default, the last 250 entries -``` - -The event log defaults to 128K entries. The command-line argument "... -vlib { elog-events nnn } ..." configures the size of the event log. - -As described above, the vpp engine event log is thread-safe and shared. -To avoid confusing non-appearance of events logged by worker threads, -make sure to code vlib\_global\_main.elog\_main - instead of -vm->elog\_main. The latter form is correct in the main thread, but -will almost certainly produce bad results in worker threads. - -G2 graphical event viewer -------------------------- - -The g2 graphical event viewer can display serialized vppinfra event logs -directly, or via the c2cpel tool. - -
- -Todo: please convert wiki page and figures - -
- -- cgit 1.2.3-korg