docs: Finish event logger, viewer and cleanup.
Change-Id: I3de038439bf0ab5755777c0f4930aec0514f5b63 Signed-off-by: John DeNisco <jdenisco@cisco.com>
This commit is contained in:

committed by
Damjan Marion

parent
33ed3e4c7d
commit
2ba9dcf408
@ -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 <filename> # for security, writes into /tmp/<filename>.
|
||||
# <filename> must not contain '.' or '/' characters
|
||||
vpp# show event-logger [all] [<nnn>] # 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.
|
||||
|
||||
<div class="admonition note">
|
||||
|
||||
Todo: please convert wiki page and figures
|
||||
|
||||
</div>
|
||||
|
||||
|
Reference in New Issue
Block a user