VPP/elog

Introduction

The vppinfra event logger provides very lightweight (sub-100ns), precisely time-stamped event-logging services. 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.

Examples

A typical event definition and a related log entry creation sequence looks like this:

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 vppinfra event logger provides a couple of interesting additions. The “t4” format shown below pretty-prints one of the enumerated values:

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.

Format details

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

Using the event logger in the vpp engine

The vpp engine itself has a bit of a UI for displaying the event log. See