Log buffer¶

This chapter describes the LogBuffer interface which is able to read and write log messages.

Sources¶

The log messages contained in a log buffer can originate from different sources. See Log sources table for the list of log sources and their abbreviation.

Log sources¶
Log source	Abbrev.	Description
Client	C	Logging originating from the client.
Controller (non real-time task)	N	Logging originating from the controller non real-time task.
Controller (real-time task)	R	Logging originating from the controller real-time task.

The abbreviation of the log source of a message is contained in the log message structure, see Entry format table.

Categories¶

Log categories are used to distinguish different types of log messages, e.g. function calls or error messages. The available categories are described in Table Log categories. The table also describes the category abbreviations used in the message structure (see Entry format) and the requirements one category may have on other categories, e.g. function call logging must be enabled to enable function argument logging.

Log categories¶
Log category	Abbrev.	Category requirements	Description
User	U0	-	Enables logging of user messages.
FunctionCall	F0	-	Enables logging of function calls.
FunctionArgument	F0	FunctionCall	Enables logging of function calls with arguments.
CallbackCall	C0	-	Enables logging of callback function calls.
CallbackArgument	C0	CallbackCall	Enables logging of callback function calls with arguments.
InternalCall	I0	-	Enables logging of internal function calls.
InternalArgument	I0	InternalCall	Enables logging of internal function calls with arguments.
Debug	D0	-	Enables logging of debug messages (e.g. from the trajectory generator).
Warning	W0	-	Enables logging of warning messages.
Error	E0	-	Enables logging of error messages (e.g. XML parse errors). This log category is default enabled and cannot be disabled.

Log messages inserted via AddMessage are logged using the log category User.

ILogBuffer.AddMessage()

LogCategory.User

C++

ILogBuffer::AddMessage()

ELogCategory::User

Entry format¶

Each log message is saved together with the timestamp, the associated log source and the log category. Note that the timestamp is based on the system time of the log source. Due to potential drift between the system times of different log sources, it is not guaranteed that the timestamps are consecutive.

System time can be set using the API.

ITopController.Time

C++

ITopController::SetTime()

Each log entry read from the buffer is formatted like YYYY-MM-DD hh:mm:ss.ppp S C N I msg. The entry formatting is described in Table Log entry format.

Log entry format¶
Identifier	Format	Description
YYYY	[0-9]{4}	Year (on the log source)
MM	01-12	Month (on the log source)
DD	01-31	Day (on the log source)
hh	00-23	Hour (on the log source)
mm	00-59	Minute (on the log source)
ss	00-59	Second (on the log source)
ppp	[0-9]{3}	Millisecond (on the log source)
S	[CNR]	Log source abbreviation see table Log sources
C	[A-Z][0-9]	Log category abbreviation see table Log categories
N	string	Controller name
I	0X[0-9A-F]{8}	Thread identifier (on the log source)
msg	string	Message

Behavior¶

Log entries are stored in a circular buffer. The user can reserve a log reader to read the contents of the buffer.

Each log reader keeps track of its read pointer rp_i to indicate the first unread message in the buffer for reader \(i\). Upon reservation the read pointer of the log reader is initialized such that it contains all available messages in the buffer. A log reader is released by calling Dispose (for C#), or by letting all shared pointers to the log reader instance go out of scope (for C++).

Figure Log buffer behavior shows the behavior of the log buffer with multiple log readers.

Log buffer behavior¶

A write pointer wp₀ keeps track of the next location where a log entry can be stored. A write to the buffer is always possible and overwrites unread messages if the buffer is full. To prevent buffer overflow the user should take care that log entries are read frequent enough, e.g. to receive a trigger when the buffer reaches a certain capacity.

ILogReader.SubscribeRemainingCapacity()

C++

ILogReader::SubscribeRemainingCapacity()

Performance¶

Logging can have a severe impact on the latency of an application. The number of log categories that should be enabled is a balance between the performance of the application and the detail of log entries required for debugging or analyzing the system. By default only the Error log category is enabled.